diff --git a/.aipass/hooks.json b/.aipass/hooks.json
index d4f049ee..0e84c6df 100644
--- a/.aipass/hooks.json
+++ b/.aipass/hooks.json
@@ -3,6 +3,11 @@
   "hooks_enabled": true,
 
   "UserPromptSubmit": {
+    "presence_gate": {
+      "enabled": true,
+      "handler": "aipass.hooks.apps.handlers.security.presence_gate.handle",
+      "matcher": ""
+    },
     "identity_injector": {
       "enabled": true,
       "handler": "aipass.hooks.apps.handlers.prompt.identity.handle",
@@ -98,6 +103,11 @@
       "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": ""
     }
   },
 
diff --git a/.aipass/tier1_navmap.md b/.aipass/tier1_navmap.md
index ab898dd7..3da3426b 100644
--- a/.aipass/tier1_navmap.md
+++ b/.aipass/tier1_navmap.md
@@ -55,7 +55,7 @@ src/aipass/<name>/
  - @skills — capability framework. Discoverable, self-contained skill units any agent can run; consume AIPass services as opt-in imports (e.g. the Telegram skill).
  - @daemon — task scheduler. Cron-triggered firing; each branch owns its `.daemon/schedule.json`, the daemon discovers and fires.
  - @commons — the social space. Where branches post, comment, vote, and gather as a community.
- - @backup — local-first backups. Project-owned snapshots and restore for any directory; no external service.
+ - @backup — local-first backups. Snapshots + versioning + restore for any directory; optional Google Drive sync (planned). `.backup/` is a shared runtime namespace — @memory rollover and @flow (plan archive) also write there.
 
 # Daily commands
 
@@ -96,6 +96,7 @@ Your continuity across sessions. Save proactively — after milestones, decision
  - `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.
+ - Entry caps are hook-enforced (over-limit edit = rejected whole). The live cap is rendered in each file's `*_meta` line — read it before writing, draft to ~80% of it; if rejected, rewrite hard in one pass.
 
 # House rules
 
diff --git a/.backupignore b/.backupignore
index f606661b..57595e6b 100644
--- a/.backupignore
+++ b/.backupignore
@@ -2,7 +2,6 @@
 # Lines starting with # are comments. Blank lines are ignored.
 # Edit this file to customize. Source defaults: handlers/ignore/patterns.py
 
-.backup_system/
 .backup/
 .git/
 .svn/
@@ -27,4 +26,3 @@ dist/
 *.log
 .ruff_cache/
 .coverage
-*logs
\ No newline at end of file
diff --git a/.claude/commands/prep.md b/.claude/commands/prep.md
index c165fbdc..69a71810 100644
--- a/.claude/commands/prep.md
+++ b/.claude/commands/prep.md
@@ -25,7 +25,18 @@ Each memory file plays a distinct role. Update based on what actually changed th
 - **`date`** — ISO date/datetime.
 - Plus its text field + extras: key_learnings `{number, date, key, value}` · sessions `{number, date, summary, status, tags}` · todos `{number, date, task, priority, status}` · observations `{number, date, note, tags}`.
 
-**When adding:** stamp `number` + `date`, then **prepend** (newest on top). **Don't hand-trim** — rollover archives the oldest *by number* to @memory automatically.
+**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
 
@@ -55,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]
diff --git a/.claude/templates/memo.md b/.claude/templates/memo.md
index 37b06a61..6c9bc059 100644
--- a/.claude/templates/memo.md
+++ b/.claude/templates/memo.md
@@ -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
diff --git a/.codex/skills/memo/SKILL.md b/.codex/skills/memo/SKILL.md
index 95135647..250f122a 100644
--- a/.codex/skills/memo/SKILL.md
+++ b/.codex/skills/memo/SKILL.md
@@ -18,14 +18,14 @@ 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.
+- **.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** — rollover archives the oldest *by number* to @memory automatically.
+**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
 
diff --git a/.codex/skills/prep/SKILL.md b/.codex/skills/prep/SKILL.md
index d18832c4..a75955b4 100644
--- a/.codex/skills/prep/SKILL.md
+++ b/.codex/skills/prep/SKILL.md
@@ -18,7 +18,9 @@ Purpose: Button up everything at the end of a session — or before a /compact.
 - **.trinity/observations.json** — Add collaboration insights if anything notable happened. Skip if nothing new.
 - **.trinity/passport.json** — Only update if role/purpose/principles genuinely changed this session.
 
-**Entry shape — one rule for all four types:** `key_learnings`, `sessions`, `todos` (local.json) and `observations` (observations.json) are all **lists, newest at top (index 0)**. Every entry carries a **`number`** (monotonic int per type — highest = newest, never reused; new = current max + 1) and a **`date`** (ISO), plus its text field + extras: key_learnings `{number, date, key, value}` · sessions `{number, date, summary, status, tags}` · todos `{number, date, task, priority, status}` · observations `{number, date, note, tags}`. Stamp `number` + `date` and **prepend**; **don't hand-trim** — rollover archives the oldest *by number* automatically.
+**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
 
@@ -48,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]
diff --git a/.gitignore b/.gitignore
index 0f2dca62..6035a54b 100644
--- a/.gitignore
+++ b/.gitignore
@@ -87,29 +87,29 @@ 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
diff --git a/CHANGELOG.md b/CHANGELOG.md
index f13c2d3e..469da464 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -9,6 +9,451 @@ PyPI version — not the changelog header.
 
 ---
 
+## [2026-07-02]
+
+Released as **2.6.1**. Rolls up the DPLAN-0226 / FPLAN-0289 / TDPLAN-0010 /
+FPLAN-0298 batch (unified Telegram↔Claude Code bridge, single-session presence
+gate, live Telegram streaming, `aipass init` template selector + portability,
+`@backup share`) — all documented under `[2026-07-01]` — plus the CI
+stabilization below.
+
+### Fixed
+
+- **CI green — six regressions from the DPLAN-0226 / FPLAN-0289 / TDPLAN-0010
+  batch (PR #646).** The dev branch had gone red across `seedgo-audit`, the
+  `test` matrix, and Windows; root-caused and fixed at source:
+  - **seedgo** — the new `template_check` advisory checker was gating CI.
+    `branch_audit.py` averaged *all* checker scores into the branch total, so
+    `template_check`'s `ADVISORY=True` was never honored and it dragged 7
+    branches below the 100% floor on legitimate README brace-examples. Added a
+    `gating_scores` filter that excludes `ADVISORY is True` checkers before
+    computing the average (strict `is True` to avoid MagicMock false-positives)
+    and exposed `advisory_standards` in the audit output. Also refreshed the
+    provider hooks snapshot fixture to include the `presence_gate`
+    `UserPromptSubmit` hook (FPLAN-0289), fixing 4 `test_hooks_snapshot` tests.
+  - **hooks** — `cc_sessions.py` (added by the bridge, `f6cbe34`) was missing
+    its README entry and a seedgo `modules` bypass (it reads external
+    `~/.claude/sessions/*.json`, not branch data, so `json_handler` is the wrong
+    tool — same precedent as `presence.py`). Added both.
+  - **spawn** — retired the `passport(disabled).py` / `passport_ops(disabled).py`
+    pair to `.archive/`; the `(disabled)` suffix kept them visible to the type
+    checker, which flagged a broken cross-import between them.
+  - **ai_mail** — `test_child_inherits_broker_fd` gave its throwaway test branch
+    a real `.trinity/passport.json` so the broker's new `.trinity`-marker
+    resolution (`f914ab6`) can resolve it and permit the delete.
+  - **spawn** — the `builder→aipass_framework` template rename (`13463c0`) left
+    `.gitignore` exceptions pointing at the old `templates/builder/` path, so
+    `DASHBOARD.local.json` + ~10 other template files were silently untracked
+    since the rename — present on disk (dirty tree passed) but absent from clean
+    clones/CI, so `test_full_spawn` failed only in a clean checkout. Fixed all 23
+    `.gitignore` exception paths and committed the now-visible template
+    scaffolding.
+  - **skills** — `test_streaming` asserted a `+1` newline byte, but `write_text`
+    text mode translates `\n`→`\r\n` on Windows (2 bytes), failing `windows-setup`
+    only. Switched the test's transcript writes to `write_bytes()` for
+    deterministic LF; production `_tail_transcript_bytes` was already CRLF-safe.
+
+## [2026-07-01]
+
+### Added
+
+- **`aipass init` is now a template selector (TDPLAN-0010)** — `init` presents a
+  chooser with **`empty project`** at the top, pre-selected as the default
+  (creates just the project folder, no scaffold), and **`aipass_framework`**
+  below it (the full AIPass agent framework — the old always-on behavior, now
+  opt-in). Flag and positional forms both work: `aipass init --list` (branches
+  before the `--` catch-all) and `aipass init <template>`. The AIPass-specific
+  stages (8 spawn-first-agent / 9 ping-registry / 11 handoff / 12 init_report,
+  `AIPASS_SPECIFIC_STAGES`) and the `bootstrap.init_project()` scaffold are now
+  gated on the chosen template, so an empty project stays empty. In-product pip
+  hints in `init_flow.py` + `doctor.py` retuned to clone/`setup.sh`. 8 new
+  selector tests; 499 tests pass. (built by @aipass, FPLAN-0295, TDPLAN-0010)
+
+- **Unified Telegram ↔ Claude Code bridge — CC-native session discovery
+  (DPLAN-0226)** — a Telegram message to a branch's bot now lands directly in
+  that branch's live Claude Code session, and the reply tails back out to
+  Telegram — a full round trip, **live-proven end-to-end from Patrick's own
+  Telegram client** (not just a self-test). The bot's inbound path
+  (`base_bot.ensure_tmux_session`) discovers the active session by enumerating
+  CC-native `~/.claude/sessions/<pid>.json` files (match `cwd`, confirm PID
+  alive, newest by `startedAt`), maps it to a tmux pane by cwd, and injects the
+  message — replacing the old `PRESENCE.central.json` pointer, which is kept but
+  commented out. The outbound path gains a CC-native "Strategy 0" in
+  `_resolve_active_transcript` that prefers the discovered transcript, so
+  assistant replies relay back reliably. Anthropic ToS rules out a cloud peer,
+  so all delivery is local (tmux/PTY). New `session_boot.py` boot wrapper
+  (attach-if-live-else-start-in-tmux; a thin `~/.bashrc claude()` shim delegates
+  to it). Hooks tests 66 green (presence_gate / cc_sessions / session_boot),
+  telegram presence_pointer 42 green. (DPLAN-0226 P1/P2, FPLAN-0290/0291/0292)
+
+- **Seedgo stale-template audit checker (`template_check`)** — a new advisory
+  standard that flags branches still carrying unrendered template markers in
+  their local prompts / config, so a citizen that never customized its scaffold
+  no longer fails silently. Auto-discovered like every other checker; advisory
+  (warns, never blocks). Ships with `template_content.py` and a `template.md`
+  standard doc, covered by `test_template_check.py`. (built by @seedgo, DPLAN-0228)
+
+### Fixed
+
+- **Drone `--json` output no longer corrupts machine JSON** — `--json`
+  pass-through was routed through Rich's `console.print()`, which defaults to
+  width 80 on a non-TTY and hard-wraps mid-string, producing invalid JSON
+  (e.g. `"Security \nScan"`). Fixed by writing raw JSON with `sys.stdout.write()`
+  in the pass-through paths (`drone.py` + `router.py`) while keeping Rich for
+  drone's own human UI. Verified live end-to-end. (fixed by @drone, td-49)
+
+### Changed
+
+- **README: pip removed, clone-only install (TDPLAN-0010)** — the top-level
+  README no longer documents `pip install aipass` anywhere: the PyPI badge, the
+  install steps (hero + Quick Start), the Project Status version badge, and the
+  uninstall `pip uninstall` line are all removed. Install is now a single path —
+  `git clone … && ./setup.sh` (puts `aipass` + `drone` on PATH), then
+  `aipass init` scaffolds agents into your own project on top. Quick Start
+  reorganized into Install → Your own project → Explore the full framework.
+  (packaging code untouched; docs are clone-first.) (DPLAN-0228, devpulse)
+
+- **Spawn: `builder` template → `aipass_framework`, birthright retired,
+  per-project registry targeting (TDPLAN-0010)** — the citizen_class/template
+  `builder` is renamed to **`aipass_framework`** across `class_registry.py`,
+  `core.py`, `meta_ops.py`, `update_ops.py`, `sync_registry_ops.py`, help text,
+  and the template dir itself (`templates/builder/` → `templates/aipass_framework/`).
+  The class is no longer baked as a literal in the template passport — a new
+  **`{{CITIZEN_CLASS}}` placeholder** (passport line 21, `placeholders.py`) now
+  takes it from the create call. **`birthright`** (0 live users) is retired to
+  `templates/.archive/birthright/` and its `passport` command disabled
+  (`passport.py` / `passport_ops.py` → `(disabled).py`, routing removed).
+  **Per-project registry targeting:** `spawn`'s `find_registry()` no longer
+  passes `package_root` to the shared discovery (killing the silent fallback to
+  AIPass's own registry for external targets), and `_spawn_agent` now validates
+  containment and, if the found registry is outside the target's project, walks
+  up from the target for `.git`/`pyproject.toml`/`setup.py`/`setup.cfg` to use
+  **that project's own registry** — so an agent created into any project is
+  tracked by that project's registry, never AIPass's. The
+  `_validate_path_containment` isolation invariant is untouched. `create` also
+  degrades gracefully when `@memory` is unavailable (empty meta-tabs, no crash).
+  297 tests pass. (built by @spawn, FPLAN-0294, TDPLAN-0010)
+
+- **Drone resolution + access checks made project-portable (TDPLAN-0010
+  foundation)** — five `src/aipass`/fixed-depth self-location hardcodes are
+  replaced with `.trinity/`-marker walk-ups: `rm_handler` sibling protection,
+  `commit_handler` test-gate branch detection, `broker/daemon` allowed-bases,
+  the `handlers/__init__` import-guard access check (now `is_relative_to()`
+  instead of scanning path parts for the literal `aipass`), and
+  `registry_handler`'s `parents[4]` last-resort (now a
+  `.git`/`pyproject.toml`/`setup.py`/`setup.cfg` marker walk). `@name`→path
+  resolution now works for an agent in any project layout via a CWD-first
+  registry walk (AIPASS_HOME only as a last resort when the CWD ancestry has no
+  registry at all). The `_validate_branch_path` containment invariant is
+  untouched — per-project isolation preserved. (Drone uses its own resolver, not
+  the shared `registry_discovery.py`.) 838 tests pass. (built by @drone,
+  FPLAN-0296, TDPLAN-0010)
+
+- **ai_mail routing made project-portable (TDPLAN-0010 foundation)** — the
+  fixed-depth `_REPO_ROOT = parents[2].parents[2]` self-location in
+  `email.py` / `email_send.py` / `dispatch.py` (4 sites) is replaced with the
+  portable `find_repo_root()` marker-walk already used in
+  `delivery.py` / `wake.py` / `paths.py`, so mail resolves via the project
+  marker instead of a hardcoded tree depth — a prerequisite for agents that
+  live outside `src/aipass/`. Per-project isolation preserved (no cross-project
+  mailbox routing). 737 tests + seedgo 100%. (built by @ai_mail, FPLAN-0293,
+  TDPLAN-0010)
+
+- **Presence gate re-sourced to CC-native session files (presence_gate v2)** —
+  the single-session guard now sources truth from `~/.claude/sessions/<pid>.json`
+  via a new `cc_sessions` module (`find_occupant`/`find_live_for_cwd`) instead of
+  `PRESENCE.central.json`. Resume-aware (a `/resume` keeps the same PID, so the
+  session is correctly recognized as re-entry, not a duplicate) and exit-aware
+  (CC deletes the file on clean exit). `handle_stop` is now a plain no-op —
+  cleanup is CC's job. The old `presence.py` / `PRESENCE.central.json` are
+  preserved, just no longer sourced. (DPLAN-0226 P1)
+
+## [2026-06-25]
+
+### Added
+
+- **Daemon auto-runner — systemd user timer (the deferred last mile of the
+  decentralized scheduler)** — `.daemon/schedule.json` jobs now fire **hands-off**.
+  A oneshot `daemon-tick.service` + `daemon-tick.timer` (every ~2 min, mirroring
+  the `prax-monitor.service` pattern: user-scope `~/.config/systemd/user/`, `%h`
+  not hardcoded paths, venv-python ExecStart `-m aipass.daemon.apps.daemon run`,
+  logs to `~/.aipass/daemon-tick.log` outside any tailed dir) reuses the existing
+  fcntl-locked `run.py` tick unchanged — the timer is the ticker. New
+  `apps/modules/timer_install.py` installs/enables it idempotently. Live-proven:
+  @devpulse received a `DAEMON TEST` ping from a branch woken purely by the timer,
+  no human tick. Tick profile: ~1.7s (import overhead only); the earlier CPU spike
+  was `wake_branch` spawning opus agents concurrently, **not** the tick — so
+  scheduled wakes want light models + staggering. Closes the piece DPLAN-0204 /
+  FPLAN-0282 deferred. 461 daemon tests green, seedgo 100%. (FPLAN-0287)
+
+- **Prax monitor → Telegram relay (`prax_monitor` bot)** — the live
+  `drone @prax monitor run` Mission-Control feed now mirrors to a dedicated
+  Telegram bot, so the whole-system monitor is watchable from a phone ("same
+  monitor, different window"). New `monitoring/telegram_relay.py` taps the single
+  render seam (`_render_event`), buffers events, and flushes every 5s (4000-char
+  split, 150-line flood cap, `disable_notification`); fail-silent-once when
+  unconfigured. Gated behind `--relay` / `AIPASS_PRAX_MONITOR_RELAY=1` so a local
+  `monitor run` stays console-only (no double-send). Bot config (token + chat_id)
+  loads from the @api secret `telegram/prax_monitor`. Ships a reboot-survivable
+  `prax-monitor.service` user unit. 937 prax tests green (31 new). (DPLAN-0221)
+
+- **Self-documenting `.trinity` state-tabs** — each memory-file section
+  (`todos` / `key_learnings` / `sessions` / `observations`) now carries a
+  config-sourced `⟦ rollover ON/OFF · keep N · ≤chars ⟧` tab rendered directly
+  above it, so an agent editing a section sees its rollover state and character
+  cap at the edit point (stops over-limit writes). Values are generated from
+  `memory.config.json` (single source of truth) via @memory's new
+  `render_all_meta_tabs()` / `tab_renderer.py`; @memory's `spawn_pusher` carries
+  the `{{*_META}}` placeholders into @spawn's branch templates, and @spawn
+  resolves them at create (`build_replacements_dict`, fail-loud on missing keys)
+  so new branches auto-populate. `refresh_all_tabs` keeps live branches synced;
+  @memory README documents the system. (FPLAN-0285, FPLAN-0286)
+
+### Changed
+
+- **Todo management — delete-on-done discipline** — `todos[]` are operational
+  and exempt from rollover (confirmed; the vestigial `todos` entry was removed
+  from `memory.config.json` rollover defaults). Because rollover never trims
+  them, finished todos must be **deleted**, not left as `status: done` (which
+  pile up and resurface as "open" across sessions). `/prep` and `/memo` (Claude
+  + Codex) and the `CLAUDE.md` startup protocol now codify: delete each todo when
+  done (proof → session entry), reconcile on load. (FPLAN-0285)
+
+### Fixed
+
+- **Daemonized wakes killed by systemd cgroup teardown (td-48)** — timer-fired
+  `wake_branch()` calls spawned the dispatch monitor + claude child, then died
+  within seconds with no email and a stale lock, while the *same* wake from an
+  interactive terminal worked. Root cause: a systemd oneshot service defaults to
+  `KillMode=control-group`, so when the ~1.7s tick process exits, systemd SIGTERMs
+  **every member of its cgroup** — `start_new_session=True` is irrelevant because
+  systemd tracks by cgroup, not process group. Fix in `ai_mail` dispatch: detect
+  the systemd context (`INVOCATION_ID`) and re-spawn the monitor via
+  `systemd-run --user` in its **own transient unit**, escaping the parent cgroup
+  (falls back to direct `Popen` when not under systemd); plus `stdin=DEVNULL` on
+  both the monitor and claude `Popen` calls and monitor PID self-registration in
+  the lock. Now genuinely live-proven through the timer: 3 branches
+  (commons/cli/backup) woken purely by `daemon-tick.timer` each emailed @devpulse
+  and exited clean (~20s, code=0). 737 ai_mail tests green, seedgo 100%.
+
+- **seedgo-audit — telegram ported-but-unwired functions** — the DPLAN-0218
+  relocation pulled the telegram lib into the seedgo gate's scope, surfacing 16
+  `unused_function` flags across 8 handler files. These are *not* dead code —
+  they're ported-but-unwired from the ~9k-line Dev-Pass port (S249), awaiting
+  DPLAN-0220 wiring (on_response hooks, response_router, tmux session mgmt, file
+  up/download, multi-bot, config helpers). Added name-scoped `unused_function`
+  bypasses in `skills/.seedgo/bypass.json` (the existing mechanism), each citing
+  DPLAN-0220, and documented every one in `SKILL.md` → *Ported-but-unwired* with
+  a "remove the bypass as you wire each fn" note. @skills back to 100%.
+
+- **seedgo-audit — @spawn direct JSON read** — `core.py` adopt-path read a
+  passport via `json.loads(path.read_text())` (direct file op), failing the
+  `json_handler` standard and the CI seedgo-audit gate. Switched to
+  `json_handler.read_json()` (the same pattern used a few lines above), dropping
+  the now-unused `import json as _json`. @spawn back to 100%; 315 spawn tests
+  green.
+
+- **Windows CI — telegram `bot_registry` crashed test collection** — the module
+  did a bare `import fcntl` (POSIX-only), so on Windows all 8 telegram test
+  modules that transitively import it failed at *collection* with
+  `ModuleNotFoundError: No module named 'fcntl'`, reddening Windows Test on the
+  last several PRs. Guarded the import (`try/except ImportError → fcntl = None`,
+  the established hooks/daemon convention) and routed the three flock call-sites
+  through no-op-on-Windows `_lock`/`_unlock` helpers — advisory locking still
+  applies on POSIX, is skipped where unavailable. Fixing collection then
+  *unmasked* three telegram tests that had never actually run on Windows, all
+  test-portability bugs (not product bugs): a log-streamer byte-count broke on
+  CRLF translation (fixture now writes `newline=""`); a registry write-failure
+  test used the Unix-only `/proc` path (now a cross-platform file-as-directory
+  parent); and `validate_bot_config` rejected valid POSIX `work_dir`s on Windows
+  because `Path.is_absolute()` is host-dependent (now tests POSIX *and* Windows
+  absoluteness). 493 telegram tests green.
+
+- **prax-monitor service feedback loop** — the unit wrote its own stdout into
+  `system_logs/`, the very directory the monitor tails *and* @trigger watches,
+  creating a self-reinforcing loop (monitor output → re-tailed and recorded by
+  @trigger into `trigger_data.json` → reported as a file change → more output).
+  Moved the service log to `~/.aipass/` to break the cycle. Also corrected the
+  ExecStart to `monitor run` (relay enabled via env) — the module `__main__`
+  rejects the drone-style `run all --relay` argument form. (DPLAN-0221)
+
+## [2026-06-24]
+
+### Changed
+
+- **Skill library relocated to `src/aipass/skills/lib/`** — first-party skills
+  were split across `catalog/` (built-in, cross-branch) and `.aipass/skills/`
+  (the branch-prompt dir, cwd-relative). Renamed `catalog/`→`lib/`, moved the
+  telegram skill in, archived three orphan test-fixture skills, and retired
+  `.aipass/skills/` from the branch. This unifies all 6 first-party skills under
+  one built-in tier and **fixes the telegram skill not being discoverable from
+  other branches** (it sat in a cwd-relative path). The public discovery
+  convention (`.aipass/skills/` + `~/.aipass/skills/`) is unchanged. One
+  functional line changed (`discovery_handler` built-in path); telegram's test
+  `conftest` path-depth, the systemd `.service` ExecStart, and seedgo bypass +
+  test paths were updated to match. Packaging, imports, and gitignore are
+  unaffected (everything stays under `src/aipass/`). 252/252 skills tests green;
+  cross-branch discovery verified from another branch. Moving telegram into the
+  gate's scope newly surfaced 9 pre-existing `unused_function` flags in its
+  handlers — triage tracked separately. (DPLAN-0218)
+
+### Added
+
+- **`@api` in-process `set_secret` write-door** — `aipass.api.apps.modules.secrets.set_secret(provider, slug, value, *, as_json=False)`
+  mirrors the existing `get_secret`, writing `~/.secrets/aipass/<provider>/<slug>.json`
+  (dirs `0o700`, files `0o600`, value never echoed to stdout or logged). The @api
+  secrets store was previously read-only; this is the writer the telegram
+  mother-bot needs to persist a newly-created bot's config so the child can read
+  its token. 515 @api tests pass (11 new), @api seedgo 100%. (DPLAN-0220)
+
+- **Prax-monitor v1 on Telegram — `/monitor` system-wide log subscription** —
+  the old Dev-Pass "prax monitor bot" (a `@prax` push relay on a dedicated token)
+  was stripped during the port; this revives the capability as a feature of the
+  existing `@aipass` bot (no second bot, no new credential). New `/monitor on`
+  (errors+warnings) / `all` (firehose) / `off` / `status` command on `base_bot`,
+  shown in the slash menu + `/help`. The subscribed chat is persisted to the `@api`
+  store (`set_secret('telegram','monitor',{chat_id,mode})`) so it survives restart,
+  and `base_bot` boot-starts the stream from it on startup — set-and-forget under
+  systemd. `LogStreamer` gained `system_wide` (glob all `system_logs/*.log`, not one
+  branch) + `level_filter` (default keeps `WARNING`/`ERROR`/`CRITICAL`, `all` =
+  passthrough); `_init_positions` still seeks EOF so subscribing never floods
+  history. 33 new tests (`test_monitor.py`), telegram suite 493/493, skills 252/252,
+  @skills seedgo 98%. (First @skills run crashed mid-edit on 3 string-handling
+  syntax errors; continued + fixed.) The richer AS-WAS `@prax` event-feed relay
+  (rendered Mission-Control stream, needs a dedicated-bot-token decision) is tracked
+  as Route B. (DPLAN-0221)
+
+### Fixed
+
+- **Telegram port — wave 1 (persistence + monitor + state hygiene)**, surfaced by
+  a full completeness audit against `TELEGRAM_PORT_MAP.md` (366 tags, ~83% ported,
+  452/452 tests green): (1) **bot launch** — `bot_factory.start_bot_process` and
+  `telegram-bot@.service` used a non-existent `~/.venv/bin/python3`; now launch via
+  `sys.executable -m …base_bot` (added `lib/__init__.py` + `lib/telegram/__init__.py`
+  for package resolution, since base_bot uses relative imports). (2) **reboot
+  survival** — `enable_service` now installs the systemd unit to
+  `~/.config/systemd/user/` + `daemon-reload` (previously the unit was never
+  installed, so `enable` silently no-op'd). (3) **state hygiene** — gitignored
+  `skills/.../lib/telegram/.local/` so the runtime registry/offset/lock files stop
+  leaking into the repo. (4) **prax-monitor** — `log_streamer` tailed a hardcoded
+  `~/system_logs` while prax writes to the repo-root `system_logs`; now resolves the
+  repo root (honoring `AIPASS_TEST_LOG_DIR`) so the log stream actually delivers.
+  (5) **auto-create (GAP1)** — `create_bot` wrote a new bot's config only to a disk
+  shadow file while the runtime loads its token exclusively from the @api store, so
+  a minted bot started then exited with no config; `create_bot` now calls
+  `set_secret('telegram', bot_id, config, as_json=True)` (fail-loud) so the
+  create→@api→load round-trip works and the mother-bot can mint startable bots. New
+  round-trip + fail-loud tests; telegram suite 454/454.
+  (6) **/help + Telegram command menu** — `setMyCommands` only ran inside
+  `create_bot`, so hand-launched bots (like the live `@aipass`) had no slash-menu,
+  and the menu list had drifted from `/help`; `base_bot` now sets its menu on
+  startup from a single source (`build_botfather_commands`, also used by
+  `create_bot` — `DEFAULT_BOT_COMMANDS` retired), so the Telegram menu and `/help`
+  list the same enriched commands incl. `/create`/`/cancel`. Wiring the builder
+  (rather than deleting it as "dead") also lifted Unused_Function 92→93%. 6 new
+  tests, telegram suite 460/460. (A running bot needs a restart to pick up the
+  startup menu.)
+  (DPLAN-0220)
+
+- **Telegram `@aipass` deployed under systemd (reboot survival + clean lifecycle)** —
+  the live mother-bot was a hand-launched foreground process: no reboot survival, and
+  `stop_bot`/restart targeted an uninstalled `telegram-bot@base` unit, so there was no
+  working lifecycle command. Installed the user service + `enable --now` +
+  `loginctl enable-linger` (`Linger=yes`); the 17:26 startup log confirms the full
+  chain live — `Telegram API OK`, **`Command menu set (6 commands)`** (the new `/help`
+  menu), stale-lock cleanup, poll loop, tmux Claude session preserved, `NRestarts=0`.
+  Also corrected the ported unit's `StandardOutput`/`StandardError`, which pointed at a
+  non-existent `~/system_logs` (would have crash-looped the service) — now
+  `<repo>/system_logs`, matching where the app already logs. Restart is now
+  `systemctl --user restart telegram-bot@base`. (DPLAN-0220)
+
+- **seedgo CLI help checkers green-lit non-compliant `--help` output** — the
+  `cli`/`help_text`/`introspection` standards are static source scans (they
+  confirm a `print_help` function, `console.print`, and `--help` wiring exist)
+  but never execute `--help`, so a module could score 100% while rendering raw
+  argparse. `@ai_mail` did exactly that via `console.print(parser.format_help())`,
+  laundering argparse's plain text through the approved console API and dodging
+  the existing `parser.print_help()` ban. Closed the loophole: `cli_check` now
+  flags `.format_help()`, `cli.md`/`cli_content.py` name it alongside
+  `print_help()`, +2 regression tests. Also rewrote `@ai_mail`'s `print_help()`
+  to render hand-rolled Rich (the `--help` content was complete, just unstyled).
+  A behavioral `--help` check (run it, assert not raw argparse) is noted as a
+  follow-up. (DPLAN-0217) On its first CI run the tightened checker immediately
+  surfaced the same pattern in 4 `@api` modules (`api_key`, `usage_tracker`,
+  `google_client`, `openrouter_client`) — migrated to Rich, `@api` back to 100%.
+- **seedgo `readme_check` ignored the `(disabled)` marker in self-scans** — its
+  module-list and test-count scans now skip `foo(disabled).py`, matching the
+  central audit collector. An in-place disabled module no longer trips a false
+  "missing module" violation; disabled test files no longer inflate README test
+  counts (td-103).
+- **seedgo `unused_function` bypasses are now name-scoped** — bypasses match by
+  function name (`functions: [...]`) instead of line number (`lines: [...]`),
+  which drifted silently when code shifted and re-flagged exempted functions
+  (bit us S216/S217). `lines` stays supported for other standards. Migrated the
+  10 existing line-scoped entries across drone/memory/skills and dropped 3 dead
+  entries already pointing past EOF (td-009).
+- **Dispatch footer no longer tells workers to close the orchestrator's plan** —
+  the standard email footer's checklist item read `CLOSE FPLAN → drone @flow
+  close <plan_id>`, which led dispatched agents to close the master/parent plan
+  referenced in their brief (bit us in FPLAN-0260). Reworded to `CLOSE YOUR PLAN
+  → ... this task's plan only, never the master/parent` — a worker still closes
+  the sub-plan handed to it, but the master stays the orchestrator's to close on
+  completion (td-6).
+
+### Changed
+
+- **Backup `.backupignore` default moved out of code into a template file** — the
+  seed content backup writes into a new project's `.backupignore` now lives in
+  `backup/templates/backupignore.template` (loaded at register), matching the
+  AIPass convention that templates are data files, not hardcoded Python. Retired
+  the `BUILTIN_IGNORES` list; `_build_backupignore()` reads the template and
+  **raises** if it's missing — never silently empty, since an empty
+  `.backupignore` would back up everything and crash. Docs/comments repointed to
+  the template (td-30).
+
+### Removed
+
+- **Dead `bulletin_created` trigger handler** — the event handler that wrote a
+  `bulletin_board` section into every branch dashboard is retired: nothing fired
+  the event, its `BULLETINS.central.json` store no longer exists, and prax
+  already prunes `bulletin_board` as a deprecated section. Archived + unwired
+  from the event registry; prax's pruning stays (td-102).
+- **Dead `backup/run/` test dir** — leftover from an ad-hoc backup test run
+  (only its generated `.backupignore` had been tracked); removed (td-218).
+
+### Documentation
+
+- **Backup docs corrected** — `.backup/` is now documented as a **shared runtime
+  namespace** (@backup stores + @memory rollover safety copies + @flow plan
+  archive), not @backup-exclusive. @backup's README gained full command coverage,
+  the `.backup/` store layout, and a `.backupignore` ("gitignore for backups")
+  section; its branch prompt's stale `.backup_system/` / `drive_test.py` names
+  were fixed. Root README lists @backup and documents `.backupignore`; the navmap
+  was corrected. The shipped root `/.backupignore` was realigned to
+  `BUILTIN_IGNORES` (dropped stale `.backup_system/` + over-broad `*logs`).
+  @memory and @flow READMEs now cross-reference their `.backup/` writes, and the
+  orphaned `prax/.backupignore` (a stale per-branch config) was removed.
+- **Root README agent roster brought current** — added the three missing agents
+  (`@daemon`, `@skills`, `@commons`) to the tree and tables, and normalized the
+  agent count to **17** everywhere (was an inconsistent mix of "13" and "14").
+  `@daemon` joins Quality & operations; a new "Capabilities and community" group
+  covers `@skills` + `@commons` (td-28).
+- **`/prep` now reconciles todos against reality** — the session-wrap command
+  (both the Claude `.claude/commands/prep.md` and the Codex skill mirror) gained
+  a step to audit every open todo against the actual system (`ls`/`find`/`git
+  ls-files`/`grep`/`audit`) and close what's verifiably done — catching todos
+  finished in a past session but never closed.
+- **Backup ignore architecture documented** — confirmed and written down the
+  two-layer model so it stops getting re-discovered: `BUILTIN_IGNORES` is the
+  **seed** that generates a new project's `.backupignore` at register and is
+  never consulted at backup time; `.backupignore` (via `load_spec`) is the
+  **runtime source of truth**. There's no static fallback, so the seed is
+  safety-critical — an empty `.backupignore` backs up everything and can crash
+  the machine. Added a "How Ignores Work" README section + code comments on
+  `BUILTIN_IGNORES` and `load_spec`. Also added `logs/` to the seed so new
+  projects exclude log directories (e.g. prax `.jsonl` output) by default, not
+  just `*.log` files (td-27).
+
 ## [2026-06-23]
 
 The **2.6.0** release — a large `dev → main` merge spanning several weeks (68 commits).
diff --git a/CLAUDE.md b/CLAUDE.md
index 7ef166d6..e77b3513 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -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`.
\ No newline at end of file
+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.
\ No newline at end of file
diff --git a/README.md b/README.md
index 91ba5f31..a19f9807 100644
--- a/README.md
+++ b/README.md
@@ -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,8 +30,10 @@ 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
+git clone https://github.com/AIOSAI/AIPass.git
+cd AIPass && ./setup.sh               # installs the `aipass` + `drone` commands on your PATH
+
+cd ~ && mkdir my-project && cd my-project
 aipass init run
 ```
 
@@ -78,12 +79,17 @@ 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 && ./setup.sh               # Creates venv, installs, puts `aipass` + `drone` on your PATH, bootstraps 17 agents
+```
 
-mkdir my-project && cd my-project
+### 2. Your own project
+
+```bash
+cd ~ && mkdir my-project && cd my-project
 aipass init run                       # Guided setup — project, first agent, terminal handoff
 ```
 
@@ -97,15 +103,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
 ```
@@ -149,13 +151,13 @@ 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)
@@ -170,7 +172,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.
@@ -201,6 +207,15 @@ These agents work on the **same filesystem, same project, same time** — no san
 | [**hooks**](src/aipass/hooks/README.md) | Hook engine — per-project config, sound control, event dispatch |
 | [**trigger**](src/aipass/trigger/README.md) | Event-driven automation + self-healing |
 | [**cli**](src/aipass/cli/README.md) | Terminal formatting and rich output |
+| [**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>
 
@@ -225,7 +240,7 @@ 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/) |
+| Version | See [git tags](https://github.com/AIOSAI/AIPass/tags) |
 | Agents | 13 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 |
@@ -266,8 +281,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.
diff --git a/pyproject.toml b/pyproject.toml
index 926eef23..a8d82265 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "aipass"
-version = "2.6.0"
+version = "2.6.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"
@@ -51,6 +51,9 @@ memory = [
     "chromadb>=1.0",
     "fastembed>=0.4",
 ]
+telegram = [
+    "telethon>=1.36",
+]
 seedgo = []
 dev = [
     "pytest>=9.0.3",
diff --git a/src/aipass/__init__.py b/src/aipass/__init__.py
index 8958d6c1..6231dcb6 100644
--- a/src/aipass/__init__.py
+++ b/src/aipass/__init__.py
@@ -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.6.0"
+__version__ = "2.6.1"
diff --git a/src/aipass/ai_mail/apps/ai_mail.py b/src/aipass/ai_mail/apps/ai_mail.py
index 42294ea4..6c72ada6 100644
--- a/src/aipass/ai_mail/apps/ai_mail.py
+++ b/src/aipass/ai_mail/apps/ai_mail.py
@@ -16,7 +16,6 @@ Main handles routing, modules implement functionality.
 # Standard library imports
 import sys
 import importlib
-import argparse
 import signal
 from pathlib import Path
 from typing import Any, List
@@ -51,52 +50,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()
 
 
 # =============================================================================
diff --git a/src/aipass/ai_mail/apps/handlers/dispatch/dispatch_monitor.py b/src/aipass/ai_mail/apps/handlers/dispatch/dispatch_monitor.py
index eb514abf..6a85b9f0 100644
--- a/src/aipass/ai_mail/apps/handlers/dispatch/dispatch_monitor.py
+++ b/src/aipass/ai_mail/apps/handlers/dispatch/dispatch_monitor.py
@@ -245,6 +245,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,
@@ -327,6 +328,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:
diff --git a/src/aipass/ai_mail/apps/handlers/dispatch/wake.py b/src/aipass/ai_mail/apps/handlers/dispatch/wake.py
index aecdfa41..6b8c34f3 100644
--- a/src/aipass/ai_mail/apps/handlers/dispatch/wake.py
+++ b/src/aipass/ai_mail/apps/handlers/dispatch/wake.py
@@ -290,6 +290,78 @@ def _check_pid_alive(pid: int) -> bool:
         return True  # Exists but can't check — assume alive
 
 
+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 ──────────────────────────────────
 
 
@@ -487,54 +559,92 @@ 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:
+            process = subprocess.Popen(
+                monitor_cmd,
+                stdin=subprocess.DEVNULL,
+                stdout=subprocess.DEVNULL,
+                stderr=subprocess.DEVNULL,
+                start_new_session=True,
+                cwd=str(branch_path),
+                env=spawn_env,
+            )
 
-        # 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"
diff --git a/src/aipass/ai_mail/apps/handlers/email/footer.py b/src/aipass/ai_mail/apps/handlers/email/footer.py
index c5ef8dab..6263ac0c 100644
--- a/src/aipass/ai_mail/apps/handlers/email/footer.py
+++ b/src/aipass/ai_mail/apps/handlers/email/footer.py
@@ -22,7 +22,7 @@ STANDARD_FOOTER = """
 ⚠️ 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.
diff --git a/src/aipass/ai_mail/apps/modules/dispatch.py b/src/aipass/ai_mail/apps/modules/dispatch.py
index 986bccbc..aa84158e 100644
--- a/src/aipass/ai_mail/apps/modules/dispatch.py
+++ b/src/aipass/ai_mail/apps/modules/dispatch.py
@@ -269,6 +269,7 @@ def _orchestrate_dispatch_send(args: List[str]) -> bool:
     from aipass.ai_mail.apps.handlers.email.error_dispatch import dispatch_send_error, on_email_delivered
     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
@@ -277,7 +278,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(
@@ -350,14 +351,14 @@ def _orchestrate_dispatch_send(args: List[str]) -> bool:
 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
+    from aipass.ai_mail.apps.handlers.paths import find_repo_root
 
     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]
+    _repo_root = find_repo_root()
     devpulse_path = devpulse_info.get("path", "")
     if not devpulse_path:
         logger.warning("[dispatch] Cannot spawn watchdog — @devpulse has no path")
diff --git a/src/aipass/ai_mail/apps/modules/email.py b/src/aipass/ai_mail/apps/modules/email.py
index 32fc0dcd..294bd269 100644
--- a/src/aipass/ai_mail/apps/modules/email.py
+++ b/src/aipass/ai_mail/apps/modules/email.py
@@ -39,10 +39,11 @@ 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
 
 _AI_MAIL_DIR = Path(__file__).resolve().parents[2]
-_REPO_ROOT = _AI_MAIL_DIR.parents[2]
+_REPO_ROOT = find_repo_root()
 
 try:
     from aipass.ai_mail.apps.handlers.central_writer import update_central
diff --git a/src/aipass/ai_mail/apps/modules/email_send.py b/src/aipass/ai_mail/apps/modules/email_send.py
index ceddc702..16745e70 100644
--- a/src/aipass/ai_mail/apps/modules/email_send.py
+++ b/src/aipass/ai_mail/apps/modules/email_send.py
@@ -35,9 +35,10 @@ 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
 
 _AI_MAIL_DIR = Path(__file__).resolve().parents[2]
-_REPO_ROOT = _AI_MAIL_DIR.parents[2]
+_REPO_ROOT = find_repo_root()
 
 try:
     from aipass.ai_mail.apps.handlers.central_writer import update_central
diff --git a/src/aipass/ai_mail/tests/test_dispatch_monitor.py b/src/aipass/ai_mail/tests/test_dispatch_monitor.py
index a1fae84f..ff5f2f24 100644
--- a/src/aipass/ai_mail/tests/test_dispatch_monitor.py
+++ b/src/aipass/ai_mail/tests/test_dispatch_monitor.py
@@ -1731,10 +1731,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")
 
diff --git a/src/aipass/ai_mail/tests/test_footer.py b/src/aipass/ai_mail/tests/test_footer.py
index d47c5534..9dcf6eff 100644
--- a/src/aipass/ai_mail/tests/test_footer.py
+++ b/src/aipass/ai_mail/tests/test_footer.py
@@ -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
 
 
diff --git a/src/aipass/ai_mail/tests/test_wake.py b/src/aipass/ai_mail/tests/test_wake.py
index 2ce16c40..d715891f 100644
--- a/src/aipass/ai_mail/tests/test_wake.py
+++ b/src/aipass/ai_mail/tests/test_wake.py
@@ -601,6 +601,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 +832,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:
diff --git a/src/aipass/aipass/.aipass/aipass_local_prompt.md b/src/aipass/aipass/.aipass/aipass_local_prompt.md
index 3f6273d8..bc1a27ca 100644
--- a/src/aipass/aipass/.aipass/aipass_local_prompt.md
+++ b/src/aipass/aipass/.aipass/aipass_local_prompt.md
@@ -12,9 +12,9 @@ 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
 
diff --git a/src/aipass/aipass/apps/modules/doctor.py b/src/aipass/aipass/apps/modules/doctor.py
index 0ec8217e..a275bff5 100644
--- a/src/aipass/aipass/apps/modules/doctor.py
+++ b/src/aipass/aipass/apps/modules/doctor.py
@@ -399,11 +399,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", ""))
diff --git a/src/aipass/aipass/apps/modules/init_flow.py b/src/aipass/aipass/apps/modules/init_flow.py
index 7e68e830..cbf2bdca 100644
--- a/src/aipass/aipass/apps/modules/init_flow.py
+++ b/src/aipass/aipass/apps/modules/init_flow.py
@@ -92,6 +92,11 @@ 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]
+AIPASS_SPECIFIC_STAGES = {8, 9, 11, 12}
+
 
 # --- LOCAL JSON HELPERS ---
 def _read_local_json() -> dict:
@@ -597,12 +602,12 @@ def stage_10_smoke_test(non_interactive: bool = False, dry_run: bool = False) ->
     if drone_bin:
         console.print(f"[green]✓[/green] 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}")
     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)
     return {"drone": drone_bin, "aipass": aipass_bin}
@@ -775,6 +780,7 @@ def run_init(
     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."""
     # Pre-flight: refuse to run inside existing projects or agent dirs
@@ -783,9 +789,20 @@ def run_init(
         console.print(f"[red]✗[/red] {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:
@@ -804,7 +821,7 @@ def run_init(
     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)),
@@ -834,6 +851,9 @@ def run_init(
     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 +866,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()
+        console.print("[green]✓[/green] Project initialized.")
+        console.print("[dim]Run 'aipass init agent <name>' to add an agent.[/dim]")
+
     return 0
 
 
@@ -878,8 +903,10 @@ def print_help() -> None:
     console.print("  [green]aipass init run --non-interactive[/green]    [dim]# CI/headless[/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 --template <name>[/green]    [dim]# select template[/dim]")
     console.print("  [green]aipass init run --no-docker[/green]          [dim]# skip docker offer[/dim]")
     console.print("  [green]aipass init run --dry-run[/green]            [dim]# walk all stages, no writes[/dim]")
+    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()
@@ -1008,6 +1035,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,6 +1058,7 @@ def handle_command(command: str, args: list[str]) -> bool:
         name = _flag_value("--name")
         cli = _flag_value("--cli")
         style = _flag_value("--style")
+        template = _flag_value("--template")
         no_docker = "--no-docker" in run_args
         dry_run = "--dry-run" in run_args
 
@@ -1032,6 +1069,7 @@ def handle_command(command: str, args: list[str]) -> bool:
             style=style,
             no_docker=no_docker,
             dry_run=dry_run,
+            template=template,
         )
         json_handler.log_operation(
             "init_run",
@@ -1040,6 +1078,12 @@ 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:
diff --git a/src/aipass/aipass/tests/test_init_flow.py b/src/aipass/aipass/tests/test_init_flow.py
index 7e8b3251..a641eb2a 100644
--- a/src/aipass/aipass/tests/test_init_flow.py
+++ b/src/aipass/aipass/tests/test_init_flow.py
@@ -16,6 +16,10 @@ from unittest.mock import MagicMock, patch
 import pytest
 
 from aipass.aipass.apps.modules.init_flow import (
+    AIPASS_SPECIFIC_STAGES,
+    TEMPLATE_AIPASS,
+    TEMPLATE_CHOICES,
+    TEMPLATE_EMPTY,
     TOTAL_STAGES,
     _get_last_completed_stage,
     _get_setup_progress,
@@ -287,7 +291,7 @@ class TestRunInit:
         assert result == 0
 
     def test_non_interactive_runs_all_stages(self, tmp_local_json) -> None:
-        """non_interactive=True runs all 12 stages from fresh state."""
+        """non_interactive=True with aipass_framework runs all 12 stages."""
         patches = self._patch_all_stages()
         mocks = []
         ctx = __import__("contextlib").ExitStack()
@@ -296,7 +300,7 @@ class TestRunInit:
         with ctx:
             with patch("aipass.aipass.apps.modules.init_flow.json_handler"):
                 with patch("aipass.aipass.apps.modules.init_flow.console"):
-                    result = run_init(non_interactive=True)
+                    result = run_init(non_interactive=True, template=TEMPLATE_AIPASS)
         assert result == 0
 
     def test_keyboard_interrupt_pauses_gracefully(self, tmp_local_json) -> None:
@@ -304,7 +308,7 @@ class TestRunInit:
         with patch("aipass.aipass.apps.modules.init_flow.stage_1_welcome", side_effect=KeyboardInterrupt):
             with patch("aipass.aipass.apps.modules.init_flow.console"):
                 with patch("aipass.aipass.apps.modules.init_flow.warning"):
-                    result = run_init(non_interactive=False)
+                    result = run_init(non_interactive=False, template=TEMPLATE_EMPTY)
         assert result == 0
 
     def test_stage_error_continues(self, tmp_local_json) -> None:
@@ -336,7 +340,7 @@ class TestRunInit:
             warning=MagicMock(),
             console=MagicMock(),
         ):
-            result = run_init(non_interactive=True)
+            result = run_init(non_interactive=True, template=TEMPLATE_AIPASS)
         assert result == 0
 
     def test_resumes_from_last_completed(self, tmp_local_json_with_progress: Path) -> None:
@@ -361,7 +365,7 @@ class TestRunInit:
             warning=MagicMock(),
             console=MagicMock(),
         ):
-            run_init(non_interactive=True)
+            run_init(non_interactive=True, template=TEMPLATE_AIPASS)
         stage_1_mock.assert_not_called()
         stage_4_mock.assert_called_once()
 
@@ -719,3 +723,114 @@ class TestInitUpdateRegistrySync:
         ):
             rc = _handle_init_update([str(tmp_path)])
         assert rc == 0
+
+
+# =============================================================================
+# TestTemplateSelector
+# =============================================================================
+
+
+class TestTemplateSelector:
+    """Tests for the template selector in aipass init."""
+
+    @staticmethod
+    def _stage_patches():
+        """Return patches for all 12 stage functions as no-ops."""
+        stage_names = [
+            "stage_1_welcome",
+            "stage_2_system_detect",
+            "stage_3_doctor",
+            "stage_4_user_profile",
+            "stage_5_style_questions",
+            "stage_6_tool_choice",
+            "stage_7_docker_offer",
+            "stage_8_first_agent",
+            "stage_9_ping_sweep",
+            "stage_10_smoke_test",
+            "stage_11_handoff",
+            "stage_12_done",
+        ]
+        return {name: MagicMock(return_value={}) for name in stage_names}
+
+    def test_empty_project_default_skips_scaffold(self, tmp_local_json) -> None:
+        """empty project (default) = no scaffold, stages 8,9,11,12 skipped."""
+        mocks = self._stage_patches()
+        with patch.multiple(_MOD, console=MagicMock(), warning=MagicMock(), **mocks):
+            result = run_init(non_interactive=True, template=TEMPLATE_EMPTY)
+        assert result == 0
+        for name in (
+            "stage_1_welcome",
+            "stage_2_system_detect",
+            "stage_3_doctor",
+            "stage_4_user_profile",
+            "stage_5_style_questions",
+            "stage_6_tool_choice",
+            "stage_7_docker_offer",
+            "stage_10_smoke_test",
+        ):
+            assert mocks[name].called, f"{name} should have been called"
+        for name in ("stage_8_first_agent", "stage_9_ping_sweep", "stage_11_handoff", "stage_12_done"):
+            assert not mocks[name].called, f"{name} should NOT have been called"
+
+    def test_aipass_framework_runs_full_scaffold(self, tmp_local_json) -> None:
+        """aipass_framework = full scaffold + all 12 stages."""
+        mocks = self._stage_patches()
+        with patch.multiple(_MOD, console=MagicMock(), warning=MagicMock(), **mocks):
+            with patch(
+                "aipass.aipass.apps.handlers.init.bootstrap.init_project",
+                return_value={},
+            ):
+                result = run_init(non_interactive=True, template=TEMPLATE_AIPASS)
+        assert result == 0
+        for name in mocks:
+            assert mocks[name].called, f"{name} should have been called"
+
+    def test_list_flag_shows_catalog(self) -> None:
+        """aipass init --list shows the catalog (not swallowed into run)."""
+        with patch(f"{_MOD}.console") as mock_console:
+            result = handle_command("init", ["--list"])
+        assert result is True
+        printed = " ".join(str(c) for c in mock_console.print.call_args_list)
+        for t in TEMPLATE_CHOICES:
+            assert t in printed
+
+    def test_template_flag_form_works(self, tmp_local_json) -> None:
+        """aipass init run --template aipass_framework passes template to run_init."""
+        with patch(f"{_MOD}.run_init", return_value=0) as mock_run:
+            with pytest.raises(SystemExit):
+                handle_command("init", ["run", "--template", TEMPLATE_AIPASS])
+        mock_run.assert_called_once()
+        _, kwargs = mock_run.call_args
+        assert kwargs["template"] == TEMPLATE_AIPASS
+
+    def test_positional_template_routes_to_run_init(self, tmp_local_json) -> None:
+        """aipass init aipass_framework routes to run_init with template."""
+        with patch(f"{_MOD}.run_init", return_value=0) as mock_run:
+            with pytest.raises(SystemExit):
+                handle_command("init", [TEMPLATE_AIPASS])
+        mock_run.assert_called_once()
+        _, kwargs = mock_run.call_args
+        assert kwargs["template"] == TEMPLATE_AIPASS
+
+    def test_positional_path_still_works(self, tmp_local_json) -> None:
+        """Non-template positional args still route to scaffold."""
+        with patch(f"{_MOD}._preflight_check", return_value=None):
+            with patch(f"{_MOD}._handle_init_scaffold", return_value=0) as mock_scaffold:
+                with pytest.raises(SystemExit):
+                    handle_command("init", ["/tmp/test-proj"])
+        mock_scaffold.assert_called_once_with(["/tmp/test-proj"])
+
+    def test_pip_hints_say_clone(self, tmp_local_json) -> None:
+        """in-product hints say clone/setup.sh, not pip."""
+        with patch(f"{_MOD}.console"):
+            with patch(f"{_MOD}.warning") as mock_warn:
+                with patch(f"{_MOD}.shutil.which", return_value=None):
+                    stage_10_smoke_test()
+        for call in mock_warn.call_args_list:
+            msg = call[0][0].lower()
+            assert "setup.sh" in msg
+            assert "pip" not in msg
+
+    def test_aipass_specific_stages_constant(self) -> None:
+        """AIPASS_SPECIFIC_STAGES contains exactly {8, 9, 11, 12}."""
+        assert AIPASS_SPECIFIC_STAGES == {8, 9, 11, 12}
diff --git a/src/aipass/api/README.md b/src/aipass/api/README.md
index 07fcd33a..e0ee8ddb 100644
--- a/src/aipass/api/README.md
+++ b/src/aipass/api/README.md
@@ -5,8 +5,8 @@
 > Centralized external API gateway — authenticated service clients for all external APIs
 
 **Module:** `aipass.api` | **Role:** `api_gateway`
-**Seedgo:** 100% (37/37 at 100%) | **Tests:** 504 pass | **Functions:** 82 public (82 tested)
-**Last Updated:** 2026-06-15
+**Seedgo:** 100% (38/38 at 100%) | **Tests:** 515 pass | **Functions:** 84 public (84 tested)
+**Last Updated:** 2026-06-24
 
 ---
 
@@ -68,7 +68,7 @@ api/
 │   │   └── usage/aggregation.py, cleanup.py, tracking.py
 │   └── integrations/                  # Private driver space (gitignored)
 │       └── {project}/driver.py
-└── tests/                             # 504 tests across 28 files
+└── tests/                             # 515 tests across 28 files
 ```
 
 Three-tier: entry point routes to modules (orchestration), modules delegate to handlers (business logic). Modules auto-discovered from `apps/modules/*.py` via `handle_command()`.
@@ -88,11 +88,12 @@ service = get_drive_service(thread_safe=True)   # For concurrent workers
 from aipass.api.apps.modules.google_client import get_google_service
 service = get_google_service("calendar", "v3")
 
-from aipass.api.apps.modules.secrets import get_secret, list_secrets
+from aipass.api.apps.modules.secrets import get_secret, set_secret, list_secrets
 token = get_secret("telegram", "bot")               # Returns bot_token string
 config = get_secret("telegram", "bot", as_json=True) # Returns full dict
-slugs = list_secrets("telegram")                     # Returns ["bot", "webhook", ...]
-# CLI never prints raw values — use the Python API above for programmatic access
+set_secret("telegram", "newbot", cfg, as_json=True)  # Writes ~/.secrets/aipass/telegram/newbot.json
+slugs = list_secrets("telegram")                     # Returns ["bot", "newbot", ...]
+# Values never reach stdout — use the Python API above for programmatic access
 ```
 
 ---
@@ -128,6 +129,6 @@ Private drivers in `apps/integrations/{project}/driver.py` (gitignored) register
 
 ---
 
-*Last Updated: 2026-05-16*
+*Last Updated: 2026-06-24*
 
 [← Back to AIPass](../../../README.md)
diff --git a/src/aipass/api/apps/handlers/auth/secrets.py b/src/aipass/api/apps/handlers/auth/secrets.py
index 6cc77f93..38031c7c 100644
--- a/src/aipass/api/apps/handlers/auth/secrets.py
+++ b/src/aipass/api/apps/handlers/auth/secrets.py
@@ -9,17 +9,19 @@
 """
 Secrets Store Handler
 
-Reads structured secrets from ~/.secrets/aipass/<provider>/<slug>.
+Reads and writes structured secrets in ~/.secrets/aipass/<provider>/<slug>.
 Supports JSON config files and raw secret files.
 
 Functions:
     get_secret() - Read a secret by provider/slug
+    set_secret() - Write a secret to the provider store
     list_secrets() - List available slugs for a provider
 """
 
 import json
+import os
 from pathlib import Path
-from typing import Any, List, Optional
+from typing import Any, List, Optional, Union
 
 from aipass.prax import logger
 from aipass.api.apps.handlers.json import json_handler
@@ -115,6 +117,53 @@ def list_secrets(provider: str) -> List[str]:
     return sorted(slugs)
 
 
+# ==============================================
+# SECRET WRITING
+# ==============================================
+
+
+def set_secret(provider: str, slug: str, value: Union[str, dict], *, as_json: bool = False) -> Path:
+    """
+    Write a secret to the provider store.
+
+    Destination: ~/.secrets/aipass/<provider>/<slug>.json
+
+    Args:
+        provider: Provider directory name (e.g., 'telegram')
+        slug: Secret identifier (without .json extension)
+        value: Secret value — string or dict
+        as_json: If True, json.dump the value; else write as plain string
+
+    Returns:
+        Path to the written file
+
+    Raises:
+        OSError: If directory creation or file write fails
+    """
+    provider_dir = SECRETS_BASE / provider
+    provider_dir.mkdir(parents=True, exist_ok=True)
+    os.chmod(provider_dir, 0o700)
+
+    target = provider_dir / f"{slug}.json"
+
+    if as_json:
+        content = json.dumps(value, indent=2).encode("utf-8")
+    else:
+        content = json.dumps(str(value)).encode("utf-8")
+
+    fd = os.open(str(target), os.O_WRONLY | os.O_CREAT | os.O_TRUNC, 0o600)
+    try:
+        os.write(fd, content)
+    finally:
+        os.close(fd)
+
+    json_handler.log_operation(
+        "secret_written",
+        {"provider": provider, "slug": slug, "format": "json" if as_json else "raw"},
+    )
+    return target
+
+
 # ==============================================
 # PRIVATE HELPERS
 # ==============================================
diff --git a/src/aipass/api/apps/modules/api_key.py b/src/aipass/api/apps/modules/api_key.py
index 2485d4a2..8c13aadf 100644
--- a/src/aipass/api/apps/modules/api_key.py
+++ b/src/aipass/api/apps/modules/api_key.py
@@ -250,55 +250,48 @@ def get_validation_rules(provider: str) -> dict:
 
 
 def print_help():
-    """Print help output for API key management"""
-    import argparse
-
-    parser = argparse.ArgumentParser(
-        prog="drone @api",
-        description="API Key Management Module - Manage API keys and credentials",
-        formatter_class=argparse.RawDescriptionHelpFormatter,
-        epilog="""
-COMMANDS:
-  get-key          - Retrieve API key for a provider
-  get-secret       - Read secret from provider store
-  validate         - Validate API key
-  list-providers   - List available providers
-  init             - Initialize .env template
-
-USAGE:
-  drone @api <command> [args]
-  drone @api --help
-
-EXAMPLES:
-  # Get key for provider
-  drone @api get-key openrouter
-
-  # Check if a secret exists (masked summary, no raw value)
-  drone @api get-secret telegram/bot
-
-  # Write secret to a protected file
-  drone @api get-secret telegram/bot --out /tmp/token.txt
-
-  # Write secret as JSON to a protected file
-  drone @api get-secret telegram/bot --out /tmp/bot.json --json
-
-  # List secrets for a provider
-  drone @api get-secret telegram --list
-
-  # Programmatic access (in-process, no stdout):
-  #   from aipass.api.apps.modules.secrets import get_secret
-
-  # Validate key
-  drone @api validate openrouter
-
-  # List providers
-  drone @api list-providers
-
-  # Initialize environment
-  drone @api init
-        """,
-    )
-    console.print(parser.format_help())
+    """Print drone-compliant help output with Rich markup"""
+    console.print()
+    console.print("[bold cyan]API_KEY — Manage API keys and credentials[/bold cyan]")
+    console.print()
+    console.print("[yellow]COMMANDS:[/yellow]")
+    console.print("  [cyan]get-key[/cyan]         [dim]Retrieve API key for a provider[/dim]")
+    console.print("  [cyan]get-secret[/cyan]      [dim]Read secret from provider store[/dim]")
+    console.print("  [cyan]validate[/cyan]        [dim]Validate API key[/dim]")
+    console.print("  [cyan]list-providers[/cyan]  [dim]List available providers[/dim]")
+    console.print("  [cyan]init[/cyan]            [dim]Initialize .env template[/dim]")
+    console.print()
+    console.print("[yellow]USAGE:[/yellow]")
+    console.print("  [cyan]drone @api[/cyan] <command> [args]")
+    console.print("  [cyan]drone @api[/cyan] --help")
+    console.print()
+    console.print("[yellow]EXAMPLES:[/yellow]")
+    console.print("  [cyan]drone @api get-key openrouter[/cyan]")
+    console.print()
+    console.print("  [dim]# Check if a secret exists (masked summary, no raw value)[/dim]")
+    console.print("  [cyan]drone @api get-secret telegram/bot[/cyan]")
+    console.print()
+    console.print("  [dim]# Write secret to a protected file[/dim]")
+    console.print("  [cyan]drone @api get-secret telegram/bot --out /tmp/token.txt[/cyan]")
+    console.print()
+    console.print("  [dim]# Write secret as JSON to a protected file[/dim]")
+    console.print("  [cyan]drone @api get-secret telegram/bot --out /tmp/bot.json --json[/cyan]")
+    console.print()
+    console.print("  [dim]# List secrets for a provider[/dim]")
+    console.print("  [cyan]drone @api get-secret telegram --list[/cyan]")
+    console.print()
+    console.print("  [dim]# Programmatic access (in-process, no stdout):[/dim]")
+    console.print("  [dim]from aipass.api.apps.modules.secrets import get_secret[/dim]")
+    console.print()
+    console.print("  [dim]# Validate key[/dim]")
+    console.print("  [cyan]drone @api validate openrouter[/cyan]")
+    console.print()
+    console.print("  [dim]# List providers[/dim]")
+    console.print("  [cyan]drone @api list-providers[/cyan]")
+    console.print()
+    console.print("  [dim]# Initialize environment[/dim]")
+    console.print("  [cyan]drone @api init[/cyan]")
+    console.print()
 
 
 if __name__ == "__main__":
diff --git a/src/aipass/api/apps/modules/google_client.py b/src/aipass/api/apps/modules/google_client.py
index c4dbc4fe..f4023861 100644
--- a/src/aipass/api/apps/modules/google_client.py
+++ b/src/aipass/api/apps/modules/google_client.py
@@ -82,31 +82,25 @@ def print_introspection() -> None:
 
 
 def print_help() -> None:
-    """Print module help."""
-    import argparse
-
-    parser = argparse.ArgumentParser(
-        prog="drone @api",
-        description="Google Client - Google API authentication and service access",
-        formatter_class=argparse.RawDescriptionHelpFormatter,
-        epilog="""
-COMMANDS (via drone @api):
-  validate google   - Check Google OAuth2 credentials
-  reauth google     - Re-run OAuth2 flow for Google
-
-CROSS-BRANCH API:
-  from aipass.api.apps.modules.google_client import get_drive_service
-  service = get_drive_service()
-
-CREDENTIAL SETUP:
-  1. Get OAuth client secret from Google Cloud Console
-  2. Save as: ~/.secrets/aipass/google_client_secret.json
-  3. Run: drone @api reauth google
-  4. Complete OAuth consent in browser
-  5. Credentials saved to: ~/.secrets/aipass/google_creds.json
-        """,
-    )
-    console.print(parser.format_help())
+    """Print drone-compliant help output with Rich markup"""
+    console.print()
+    console.print("[bold cyan]GOOGLE_CLIENT — Google API authentication and service access[/bold cyan]")
+    console.print()
+    console.print("[yellow]COMMANDS:[/yellow]  [dim](via drone @api)[/dim]")
+    console.print("  [cyan]validate google[/cyan]  [dim]Check Google OAuth2 credentials[/dim]")
+    console.print("  [cyan]reauth google[/cyan]   [dim]Re-run OAuth2 flow for Google[/dim]")
+    console.print()
+    console.print("[yellow]CROSS-BRANCH API:[/yellow]")
+    console.print("  [dim]from aipass.api.apps.modules.google_client import get_drive_service[/dim]")
+    console.print("  [dim]service = get_drive_service()[/dim]")
+    console.print()
+    console.print("[yellow]CREDENTIAL SETUP:[/yellow]")
+    console.print("  [dim]1.[/dim] Get OAuth client secret from Google Cloud Console")
+    console.print("  [dim]2.[/dim] Save as: [cyan]~/.secrets/aipass/google_client_secret.json[/cyan]")
+    console.print("  [dim]3.[/dim] Run: [cyan]drone @api reauth google[/cyan]")
+    console.print("  [dim]4.[/dim] Complete OAuth consent in browser")
+    console.print("  [dim]5.[/dim] Credentials saved to: [cyan]~/.secrets/aipass/google_creds.json[/cyan]")
+    console.print()
 
 
 # =============================================
diff --git a/src/aipass/api/apps/modules/openrouter_client.py b/src/aipass/api/apps/modules/openrouter_client.py
index b425da2f..5f05a406 100644
--- a/src/aipass/api/apps/modules/openrouter_client.py
+++ b/src/aipass/api/apps/modules/openrouter_client.py
@@ -52,62 +52,39 @@ def print_introspection():
 
 
 def print_help():
-    """Print module help with argparse"""
-    import argparse
-
-    parser = argparse.ArgumentParser(
-        prog="drone @api",
-        description="OpenRouter Client - Manage LLM API connections",
-        formatter_class=argparse.RawDescriptionHelpFormatter,
-        epilog="""
-COMMANDS:
-  test             - Test OpenRouter connection
-  call             - Make API call to model
-  models           - List available models
-  status           - Check connection status
-
-USAGE:
-  drone @api test
-  drone @api call <prompt> [--model MODEL]
-  drone @api models
-  drone @api status
-
-ARGUMENTS:
-  prompt - Prompt to send to the model
-  --model - Model to use (optional)
-
-EXAMPLES:
-  # Test OpenRouter connection
-  drone @api test
-
-  # Make an API call
-  drone @api call "What is AI?" --model gpt-4
-
-  # List available models
-  drone @api models
-
-  # Check connection status
-  drone @api status
-        """,
-    )
-
-    subparsers = parser.add_subparsers(dest="command", help="Available commands")
-
-    # test command
-    subparsers.add_parser("test", help="Test OpenRouter connection")
-
-    # call command
-    call_parser = subparsers.add_parser("call", help="Make API call to model")
-    call_parser.add_argument("prompt", help="Prompt to send")
-    call_parser.add_argument("--model", help="Model to use")
-
-    # models command
-    subparsers.add_parser("models", help="List available models")
-
-    # status command
-    subparsers.add_parser("status", help="Check connection status")
-
-    console.print(parser.format_help())
+    """Print drone-compliant help output with Rich markup"""
+    console.print()
+    console.print("[bold cyan]OPENROUTER_CLIENT — Manage LLM API connections[/bold cyan]")
+    console.print()
+    console.print("[yellow]COMMANDS:[/yellow]")
+    console.print("  [cyan]test[/cyan]     [dim]Test OpenRouter connection[/dim]")
+    console.print("  [cyan]call[/cyan]     [dim]Make API call to model[/dim]")
+    console.print("  [cyan]models[/cyan]   [dim]List available models[/dim]")
+    console.print("  [cyan]status[/cyan]   [dim]Check connection status[/dim]")
+    console.print()
+    console.print("[yellow]USAGE:[/yellow]")
+    console.print("  [cyan]drone @api test[/cyan]")
+    console.print("  [cyan]drone @api call[/cyan] <prompt> [--model MODEL]")
+    console.print("  [cyan]drone @api models[/cyan]")
+    console.print("  [cyan]drone @api status[/cyan]")
+    console.print()
+    console.print("[yellow]ARGUMENTS:[/yellow]")
+    console.print("  [cyan]prompt[/cyan]   [dim]Prompt to send to the model[/dim]")
+    console.print("  [cyan]--model[/cyan]  [dim]Model to use (optional)[/dim]")
+    console.print()
+    console.print("[yellow]EXAMPLES:[/yellow]")
+    console.print("  [dim]# Test OpenRouter connection[/dim]")
+    console.print("  [cyan]drone @api test[/cyan]")
+    console.print()
+    console.print("  [dim]# Make an API call[/dim]")
+    console.print('  [cyan]drone @api call "What is AI?" --model gpt-4[/cyan]')
+    console.print()
+    console.print("  [dim]# List available models[/dim]")
+    console.print("  [cyan]drone @api models[/cyan]")
+    console.print()
+    console.print("  [dim]# Check connection status[/dim]")
+    console.print("  [cyan]drone @api status[/cyan]")
+    console.print()
 
 
 def handle_command(command: str, args: List[str]) -> bool:
diff --git a/src/aipass/api/apps/modules/secrets.py b/src/aipass/api/apps/modules/secrets.py
index 327398a9..d5e44892 100644
--- a/src/aipass/api/apps/modules/secrets.py
+++ b/src/aipass/api/apps/modules/secrets.py
@@ -9,17 +9,19 @@
 """
 Secrets Module
 
-Cross-branch in-process API for reading secrets from the provider store.
+Cross-branch in-process API for the secrets provider store.
 Consumers import directly instead of shelling out to the CLI.
 
 Functions:
     get_secret() - Read a secret by provider/slug
+    set_secret() - Write a secret to the provider store
     list_secrets() - List available slugs for a provider
     handle_command() - Route CLI commands (seedgo module discovery)
 """
 
 import sys
-from typing import Any, List, Optional
+from pathlib import Path
+from typing import Any, List, Optional, Union
 
 from aipass.prax import logger  # noqa: F401 — seedgo imports standard
 from aipass.cli.apps.modules import console, header
@@ -42,6 +44,7 @@ def print_introspection():
 
     console.print("[cyan]Available Workflows:[/cyan]")
     console.print("  • get_secret() - Read secret by provider/slug")
+    console.print("  • set_secret() - Write secret to provider store")
     console.print("  • list_secrets() - List slugs for a provider")
     console.print()
 
@@ -96,6 +99,30 @@ def get_secret(provider: str, slug: str, as_json: bool = False) -> Optional[Any]
     return result
 
 
+def set_secret(provider: str, slug: str, value: Union[str, dict], *, as_json: bool = False) -> Path:
+    """
+    Write a secret to the provider store.
+
+    This is the sanctioned cross-branch write path. Consumers call this
+    instead of shelling out to the CLI.
+
+    Args:
+        provider: Provider directory name (e.g., 'telegram')
+        slug: Secret identifier (without .json extension)
+        value: Secret value — string or dict
+        as_json: If True, json.dump the value; else write as plain string
+
+    Returns:
+        Path to the written file
+
+    Raises:
+        OSError: If directory creation or file write fails
+    """
+    result = _handler.set_secret(provider, slug, value, as_json=as_json)
+    json_handler.log_operation("secrets_set", {"provider": provider, "slug": slug, "wrote": str(result)})
+    return result
+
+
 def list_secrets(provider: str) -> List[str]:
     """
     List available secret slugs for a provider.
diff --git a/src/aipass/api/apps/modules/usage_tracker.py b/src/aipass/api/apps/modules/usage_tracker.py
index 23d4e09b..78795c70 100644
--- a/src/aipass/api/apps/modules/usage_tracker.py
+++ b/src/aipass/api/apps/modules/usage_tracker.py
@@ -53,76 +53,44 @@ def print_introspection():
 
 
 def print_help():
-    """Print module help with argparse"""
-    import argparse
-
-    parser = argparse.ArgumentParser(
-        prog="drone @api",
-        description="Usage Tracker - Monitor API usage and costs",
-        formatter_class=argparse.RawDescriptionHelpFormatter,
-        epilog="""
-COMMANDS:
-  track            - Track API usage
-  stats            - Show usage statistics
-  session          - Show session data
-  caller-usage     - Show usage by caller
-  cleanup          - Clean up old usage data
-
-USAGE:
-  drone @api track <caller>
-  drone @api stats
-  drone @api session
-  drone @api caller-usage <caller>
-  drone @api cleanup [days]
-
-ARGUMENTS:
-  caller - Caller identifier
-  days - Number of days to retain (default: 30)
-
-EXAMPLES:
-  # Track usage for a caller
-  drone @api track my_application
-
-  # Show usage statistics
-  drone @api stats
-
-  # Show session data
-  drone @api session
-
-  # Show usage for specific caller
-  drone @api caller-usage my_application
-
-  # Cleanup data older than 60 days
-  drone @api cleanup 60
-        """,
-    )
-
-    subparsers = parser.add_subparsers(dest="command", help="Available commands")
-
-    # track command
-    track_parser = subparsers.add_parser("track", help="Track API usage")
-    track_parser.add_argument("caller", help="Caller identifier")
-
-    # stats command
-    subparsers.add_parser("stats", help="Show usage statistics")
-
-    # session command
-    subparsers.add_parser("session", help="Show session data")
-
-    # caller-usage command
-    caller_parser = subparsers.add_parser("caller-usage", help="Show usage by caller")
-    caller_parser.add_argument("caller", help="Caller identifier")
-
-    # cleanup command
-    cleanup_parser = subparsers.add_parser("cleanup", help="Clean up old usage data")
-    cleanup_parser.add_argument(
-        "days",
-        nargs="?",
-        default=str(DEFAULT_RETENTION_DAYS),
-        help=f"Days to retain (default: {DEFAULT_RETENTION_DAYS})",
-    )
-
-    console.print(parser.format_help())
+    """Print drone-compliant help output with Rich markup"""
+    console.print()
+    console.print("[bold cyan]USAGE_TRACKER — Monitor API usage and costs[/bold cyan]")
+    console.print()
+    console.print("[yellow]COMMANDS:[/yellow]")
+    console.print("  [cyan]track[/cyan]         [dim]Track API usage[/dim]")
+    console.print("  [cyan]stats[/cyan]         [dim]Show usage statistics[/dim]")
+    console.print("  [cyan]session[/cyan]       [dim]Show session data[/dim]")
+    console.print("  [cyan]caller-usage[/cyan]  [dim]Show usage by caller[/dim]")
+    console.print("  [cyan]cleanup[/cyan]       [dim]Clean up old usage data[/dim]")
+    console.print()
+    console.print("[yellow]USAGE:[/yellow]")
+    console.print("  [cyan]drone @api track[/cyan] <caller>")
+    console.print("  [cyan]drone @api stats[/cyan]")
+    console.print("  [cyan]drone @api session[/cyan]")
+    console.print("  [cyan]drone @api caller-usage[/cyan] <caller>")
+    console.print("  [cyan]drone @api cleanup[/cyan] [days]")
+    console.print()
+    console.print("[yellow]ARGUMENTS:[/yellow]")
+    console.print("  [cyan]caller[/cyan]  [dim]Caller identifier[/dim]")
+    console.print("  [cyan]days[/cyan]    [dim]Number of days to retain (default: 30)[/dim]")
+    console.print()
+    console.print("[yellow]EXAMPLES:[/yellow]")
+    console.print("  [dim]# Track usage for a caller[/dim]")
+    console.print("  [cyan]drone @api track my_application[/cyan]")
+    console.print()
+    console.print("  [dim]# Show usage statistics[/dim]")
+    console.print("  [cyan]drone @api stats[/cyan]")
+    console.print()
+    console.print("  [dim]# Show session data[/dim]")
+    console.print("  [cyan]drone @api session[/cyan]")
+    console.print()
+    console.print("  [dim]# Show usage for specific caller[/dim]")
+    console.print("  [cyan]drone @api caller-usage my_application[/cyan]")
+    console.print()
+    console.print("  [dim]# Cleanup data older than 60 days[/dim]")
+    console.print("  [cyan]drone @api cleanup 60[/cyan]")
+    console.print()
 
 
 def handle_command(command: str, args: List[str]) -> bool:
@@ -194,9 +162,10 @@ def track_usage(args: List[str]):
 
     if result.get("success"):
         metrics = result.get("metrics", {})
-        success(
-            f"Tracked: {metrics.get('tokens_prompt', 0)} prompt + {metrics.get('tokens_completion', 0)} completion tokens, ${metrics.get('total_cost', 0):.6f}"
-        )
+        prompt_t = metrics.get("tokens_prompt", 0)
+        comp_t = metrics.get("tokens_completion", 0)
+        cost = metrics.get("total_cost", 0)
+        success(f"Tracked: {prompt_t} prompt + {comp_t} completion tokens, ${cost:.6f}")
     else:
         error(f"Tracking failed: {result.get('error', 'unknown')}")
 
diff --git a/src/aipass/api/tests/test_secrets.py b/src/aipass/api/tests/test_secrets.py
index a4804592..a5d79e15 100644
--- a/src/aipass/api/tests/test_secrets.py
+++ b/src/aipass/api/tests/test_secrets.py
@@ -21,8 +21,19 @@ Tests — handlers/auth/secrets.py (get_secret, list_secrets):
 - list_secrets: non-existent provider returns empty list
 - list_secrets: skips dotfiles, __pycache__, directories
 
+Tests — handlers/auth/secrets.py (set_secret):
+- set_secret: writes string value to provider/slug.json
+- set_secret: as_json writes JSON-serialized dict
+- set_secret: creates provider directory if missing
+- set_secret: file has 0o600 permissions (POSIX)
+- set_secret: provider dir has 0o700 permissions (POSIX)
+- set_secret: overwrites existing secret
+- set_secret: round-trip with get_secret returns same value
+- set_secret: round-trip with get_secret as_json returns same dict
+
 Tests — modules/secrets.py (in-process door):
 - get_secret wraps handler and logs operation
+- set_secret wraps handler and logs operation
 - list_secrets wraps handler
 
 Tests — api_key.py (get_secret_cmd — hardened, no raw values to stdout):
@@ -52,6 +63,7 @@ from aipass.api.apps.modules.api_key import handle_command as _hc  # noqa: F401
 from aipass.api.apps.modules.secrets import handle_command as _hc2  # noqa: F401 — seedgo test_coverage detection
 from aipass.api.apps.handlers.auth.secrets import (
     get_secret,
+    set_secret,
     list_secrets,
 )
 from aipass.api.apps.modules.api_key import get_secret_cmd
@@ -491,3 +503,131 @@ class TestGetSecretCmd:
         get_secret_cmd(["empty_provider", "--list"])
 
         mock_secrets.list_secrets.assert_called_once_with("empty_provider")
+
+
+# =============================================
+# set_secret (handler)
+# =============================================
+
+
+class TestSetSecret:
+    """Verifies secret writing under various conditions."""
+
+    def test_writes_string_value(self, tmp_path: Path) -> None:
+        """Writes a plain string value to provider/slug.json."""
+        with patch(PATCH_SECRETS_BASE, tmp_path), patch(PATCH_JSON_HANDLER), patch(PATCH_LOGGER):
+            result = set_secret("telegram", "bot", "my-token-value")
+
+        assert result == tmp_path / "telegram" / "bot.json"
+        assert json.loads(result.read_text(encoding="utf-8")) == "my-token-value"
+
+    def test_as_json_writes_dict(self, tmp_path: Path) -> None:
+        """as_json=True writes JSON-serialized dict."""
+        data = {"bot_token": "abc123", "webhook_url": "https://example.com"}
+
+        with patch(PATCH_SECRETS_BASE, tmp_path), patch(PATCH_JSON_HANDLER), patch(PATCH_LOGGER):
+            result = set_secret("telegram", "bot", data, as_json=True)
+
+        written = json.loads(result.read_text(encoding="utf-8"))
+        assert written == data
+
+    def test_creates_provider_directory(self, tmp_path: Path) -> None:
+        """Creates provider directory if it doesn't exist."""
+        assert not (tmp_path / "newprovider").exists()
+
+        with patch(PATCH_SECRETS_BASE, tmp_path), patch(PATCH_JSON_HANDLER), patch(PATCH_LOGGER):
+            set_secret("newprovider", "cred", "value")
+
+        assert (tmp_path / "newprovider").is_dir()
+
+    @pytest.mark.skipif(sys.platform == "win32", reason="File permission checks are POSIX-only")
+    def test_file_has_0600_permissions(self, tmp_path: Path) -> None:
+        """Written file has 0o600 permissions."""
+        with patch(PATCH_SECRETS_BASE, tmp_path), patch(PATCH_JSON_HANDLER), patch(PATCH_LOGGER):
+            result = set_secret("telegram", "bot", "token")
+
+        file_mode = stat.S_IMODE(os.stat(result).st_mode)
+        assert file_mode == 0o600
+
+    @pytest.mark.skipif(sys.platform == "win32", reason="File permission checks are POSIX-only")
+    def test_provider_dir_has_0700_permissions(self, tmp_path: Path) -> None:
+        """Provider directory has 0o700 permissions."""
+        with patch(PATCH_SECRETS_BASE, tmp_path), patch(PATCH_JSON_HANDLER), patch(PATCH_LOGGER):
+            set_secret("telegram", "bot", "token")
+
+        dir_mode = stat.S_IMODE(os.stat(tmp_path / "telegram").st_mode)
+        assert dir_mode == 0o700
+
+    def test_overwrites_existing_secret(self, tmp_path: Path) -> None:
+        """Overwrites an existing secret file."""
+        with patch(PATCH_SECRETS_BASE, tmp_path), patch(PATCH_JSON_HANDLER), patch(PATCH_LOGGER):
+            set_secret("telegram", "bot", "old-value")
+            set_secret("telegram", "bot", "new-value")
+
+        content = json.loads((tmp_path / "telegram" / "bot.json").read_text(encoding="utf-8"))
+        assert content == "new-value"
+
+    def test_round_trip_string(self, tmp_path: Path) -> None:
+        """set_secret then get_secret returns the same string value."""
+        with patch(PATCH_SECRETS_BASE, tmp_path), patch(PATCH_JSON_HANDLER), patch(PATCH_LOGGER):
+            set_secret("telegram", "bot", "round-trip-token")
+            result = get_secret("telegram", "bot")
+
+        assert result == "round-trip-token"
+
+    def test_round_trip_json(self, tmp_path: Path) -> None:
+        """set_secret as_json then get_secret as_json returns the same dict."""
+        data = {"bot_token": "abc123", "chat_id": 42}
+
+        with patch(PATCH_SECRETS_BASE, tmp_path), patch(PATCH_JSON_HANDLER), patch(PATCH_LOGGER):
+            set_secret("telegram", "bot", data, as_json=True)
+            result = get_secret("telegram", "bot", as_json=True)
+
+        assert result == data
+
+    def test_logs_operation(self, tmp_path: Path) -> None:
+        """set_secret logs the write operation via json_handler."""
+        mock_jh = MagicMock()
+        with patch(PATCH_SECRETS_BASE, tmp_path), patch(PATCH_JSON_HANDLER, mock_jh), patch(PATCH_LOGGER):
+            set_secret("telegram", "bot", "token")
+
+        mock_jh.log_operation.assert_called_once()
+        call_args = mock_jh.log_operation.call_args[0]
+        assert call_args[0] == "secret_written"
+        assert call_args[1]["provider"] == "telegram"
+        assert call_args[1]["slug"] == "bot"
+
+
+# =============================================
+# set_secret (module door)
+# =============================================
+
+
+class TestSetSecretModule:
+    """Verifies the module-level set_secret wrapper."""
+
+    def test_set_secret_wraps_handler(self, tmp_path: Path) -> None:
+        """Module set_secret delegates to handler and logs the operation."""
+        mock_handler = MagicMock()
+        mock_handler.set_secret.return_value = tmp_path / "telegram" / "bot.json"
+        mock_jh = MagicMock()
+
+        with patch(PATCH_MOD_HANDLER, mock_handler), patch(PATCH_MOD_JSON_HANDLER, mock_jh):
+            result = secrets_module.set_secret("telegram", "bot", "token-val")
+
+        assert result == tmp_path / "telegram" / "bot.json"
+        mock_handler.set_secret.assert_called_once_with("telegram", "bot", "token-val", as_json=False)
+        mock_jh.log_operation.assert_called_once()
+        assert mock_jh.log_operation.call_args[0][0] == "secrets_set"
+
+    def test_set_secret_as_json(self) -> None:
+        """Module set_secret passes as_json through to handler."""
+        mock_handler = MagicMock()
+        mock_handler.set_secret.return_value = Path("/fake/path.json")
+        mock_jh = MagicMock()
+        data = {"bot_token": "abc"}
+
+        with patch(PATCH_MOD_HANDLER, mock_handler), patch(PATCH_MOD_JSON_HANDLER, mock_jh):
+            secrets_module.set_secret("telegram", "bot", data, as_json=True)
+
+        mock_handler.set_secret.assert_called_once_with("telegram", "bot", data, as_json=True)
diff --git a/src/aipass/backup/.aipass/aipass_local_prompt.md b/src/aipass/backup/.aipass/aipass_local_prompt.md
index e7cd8959..382a2e8f 100644
--- a/src/aipass/backup/.aipass/aipass_local_prompt.md
+++ b/src/aipass/backup/.aipass/aipass_local_prompt.md
@@ -39,7 +39,7 @@ apps/
 │   ├── settings.py        # Settings UI (stub — low priority)
 │   ├── drive_sync.py      # Drive sync (stub — DPLAN-003)
 │   ├── drive_stats.py     # Drive stats (stub)
-│   ├── drive_test.py      # Drive test (stub)
+│   ├── drive_check.py     # Drive check (stub — DPLAN-003)
 │   └── drive_clear.py     # Drive clear (stub)
 └── handlers/
     ├── copy/              # File copying (snapshot + versioned)
@@ -47,7 +47,7 @@ apps/
     ├── ignore/            # .backupignore patterns + whitelist
     ├── json/              # JSON persistence, atomic writes, ops log
     ├── path/              # Backup path building
-    ├── project/           # Config, registry, setup (.backup_system/)
+    ├── project/           # Config, registry, setup (.backup/)
     ├── report/            # Result formatting
     ├── scan/              # Directory walking + filtering
     ├── state/             # Changelog, metadata, timestamps
@@ -58,14 +58,14 @@ apps/
 ## Integration
 
 - **Depends on:** @prax for logging, @cli for Rich console output
-- **Serves:** Any project on the PC — backups are project-owned (.backup_system/ in target root)
+- **Serves:** Any project on the PC — backups are project-owned (.backup/ in target root)
 
 ## Working Habits
 
-- Project-owned design: .backup_system/ and .backupignore live in the TARGET project, not centrally
+- Project-owned design: .backup/ and .backupignore live in the TARGET project, not centrally
 - Normal citizen namespace: uses `from aipass.backup.apps.modules.*` / `from aipass.backup.apps.handlers.*`
 - Entry point sets AIPASS_BRANCH_NAME env var for Prax
-- BUILTIN_IGNORES in patterns.py is the single source for default ignore patterns
+- templates/backupignore.template is the single source for default ignore patterns
 
 ## Known Gotchas
 
diff --git a/src/aipass/backup/.daemon/schedule.json b/src/aipass/backup/.daemon/schedule.json
new file mode 100644
index 00000000..212d84b8
--- /dev/null
+++ b/src/aipass/backup/.daemon/schedule.json
@@ -0,0 +1,18 @@
+{
+  "version": 1,
+  "branch": "@backup",
+  "jobs": [
+    {
+      "id": "wake-test",
+      "enabled": false,
+      "schedule": {
+        "type": "interval",
+        "interval_minutes": 5
+      },
+      "wake": {
+        "fresh": true
+      },
+      "prompt": "AUTOMATED DAEMON TEST. Do ONLY this: run drone @ai_mail email @devpulse \"DAEMON TEST \u2014 backup\" \"Woke via @daemon systemd timer. No memory touched.\" then STOP. Do NOT run startup, do NOT update memory, do NOT do anything else."
+    }
+  ]
+}
diff --git a/src/aipass/backup/README.md b/src/aipass/backup/README.md
index 0952e8d0..6d5cf52e 100644
--- a/src/aipass/backup/README.md
+++ b/src/aipass/backup/README.md
@@ -64,11 +64,61 @@ apps/
 backup register <path> [--name <name>]   # Register a project for backup
 backup snapshot <path|@name>             # Full mirror backup
 backup versioned <path|@name>            # Incremental timestamped backup
-backup all <path|@name>                  # Snapshot + versioned
+backup all <path|@name>                  # Snapshot + versioned + drive
 backup status <path|@name>              # Show backup info and history
-backup --version                        # Show version
+backup restore <path|@name> list <file>  # List available versions of a file
+backup restore <path|@name> file <f> <o> # Restore a file version to output path
+backup settings <path|@name>             # Settings UI (stub)
+backup drive_sync <path|@name>           # Google Drive sync (stub — DPLAN-003)
+backup drive_check <path|@name>          # Drive connectivity check (stub — DPLAN-003)
+backup drive_stats <path|@name>          # Drive storage stats (stub — DPLAN-003)
+backup drive_clear <path|@name>          # Clear Drive sync state (stub — DPLAN-003)
 ```
 
+All 11 commands are auto-discovered by the entry point router.
+
+---
+
+## `.backup/` Store Structure
+
+Each registered project gets a `.backup/` directory at its root:
+
+```
+.backup/
+├── config.json          # Project backup configuration
+├── snapshots/           # Full mirror copies (eager — created on register)
+├── versioned/           # Incremental timestamped backups (lazy)
+├── logs/                # Operation logs (eager — created on register)
+├── timestamps.json      # Backup timing metadata (lazy)
+├── changelog.json       # Change history (lazy)
+└── drive_tracker.json   # Drive sync dedup tracker (lazy)
+```
+
+On `register`, only `snapshots/` and `logs/` are created eagerly (plus `config.json`). The rest are created lazily on first use.
+
+**Shared namespace:** `.backup/` is NOT exclusive to @backup. Three writers use it:
+- **@backup** — snapshot/versioned stores at a registered project root
+- **@memory** — rollover safety copies (`rollover_backup_*.json`) written to `<branch>/.backup/` during memory overflow
+- **@flow** — closed plans archived to `<repo-root>/.backup/processed_plans/` for vectorization by @memory
+
+The root `.gitignore` covers all three with a single `.backup/` entry.
+
+---
+
+## How Ignores Work
+
+Two layers — seed and runtime:
+
+1. **`templates/backupignore.template`** — the **seed**. Read by `setup._build_backupignore()` and written into a new project's `.backupignore` at `register` time. Never consulted at backup time. If this file is missing, registration raises — an empty seed would back up everything and crash the machine.
+2. **`.backupignore`** — the **runtime source of truth**. `load_spec()` reads it on every backup; the seed template is not applied. True pathspec/gitwildmatch semantics: `#` comments, `!` negation, trailing `/` for dirs, last-match-wins.
+
+There is no static fallback. The seed IS the safety mechanism — an empty or missing `.backupignore` means back up everything (`.venv`, `node_modules`, `.git`), which can crash the machine. Keep the template sane.
+
+- To change defaults for **new** projects → edit `templates/backupignore.template`
+- To change ignores for an **existing** project → edit its `.backupignore`
+
+The repo-root `/.backupignore` ships intentionally as the curated default so users don't snapshot junk.
+
 ---
 
 ## Integration Points
@@ -78,4 +128,4 @@ backup --version                        # Show version
 - @cli — Rich console output
 
 ### Provides To
-- Any project on the PC — backups are project-owned (.backup/ in target root)
+- Any project on the PC — backups are project-owned (`.backup/` in target root)
diff --git a/src/aipass/backup/apps/backup.py b/src/aipass/backup/apps/backup.py
index 8dc2fe5f..958afe25 100644
--- a/src/aipass/backup/apps/backup.py
+++ b/src/aipass/backup/apps/backup.py
@@ -73,6 +73,7 @@ def print_help() -> None:
     console.print("  [green]drive_sync[/green]   Sync backups to the remote drive")
     console.print("  [green]drive_check[/green]  Test the remote drive connection")
     console.print("  [green]drive_stats[/green]  Drive usage statistics")
+    console.print("  [green]share[/green]        Upload a single file to Drive + get a shareable link")
     console.print("  [green]drive_clear[/green]  Clear backups from the remote drive")
     console.print()
 
diff --git a/src/aipass/backup/apps/handlers/drive/share.py b/src/aipass/backup/apps/handlers/drive/share.py
new file mode 100644
index 00000000..b1886906
--- /dev/null
+++ b/src/aipass/backup/apps/handlers/drive/share.py
@@ -0,0 +1,200 @@
+# =================== AIPass ====================
+# Name: share.py
+# Description: Drive sharing — upload + permission + shareable link retrieval
+# Version: 1.0.0
+# Created: 2026-07-01
+# Modified: 2026-07-01
+# =============================================
+
+"""Drive file sharing.
+
+Uploads a single file to Drive (under ``AIPass Backups/Shared``),
+sets a read permission, and retrieves a shareable webViewLink.
+Idempotent: reuses an existing file if one is found by name.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import TYPE_CHECKING, Any
+
+from aipass.prax import logger
+
+from ..json import json_handler
+from . import upload as upload_mod
+
+if TYPE_CHECKING:
+    from .client import DriveClient
+
+SHARE_PROJECT_NAME = "Shared"
+
+
+def _get_authenticated_email(client: DriveClient) -> str | None:
+    """Derive the authenticated user's email from Drive ``about`` API."""
+    try:
+        request = client.drive_service.about().get(fields="user")  # type: ignore[union-attr]
+        result = client._api_call(request)
+        if result and result.get("user"):
+            return result["user"].get("emailAddress")
+    except Exception as exc:
+        logger.info(f"Failed to get authenticated email: {exc}")
+    return None
+
+
+def upload_for_share(
+    client: DriveClient,
+    local_file: Path,
+    note: str = "",
+) -> str | None:
+    """Upload a file for sharing.  Returns the Drive file ID or ``None``.
+
+    Idempotent: checks the ``Shared`` project folder first and reuses an
+    existing file (matched by name) instead of re-uploading.  Falls back
+    to :func:`upload_single_file` for the actual upload.
+    """
+    folder_id = client.get_or_create_project_folder(SHARE_PROJECT_NAME)
+    if not folder_id:
+        return None
+
+    existing = client._find_existing_file(local_file.name, folder_id)
+    if existing:
+        logger.info(f"File already on Drive: {existing['id']}")
+        return existing["id"]
+
+    client.file_tracker = {}
+    success = upload_mod.upload_single_file(
+        client,
+        local_file,
+        SHARE_PROJECT_NAME,
+        local_file.parent,
+        note=note,
+    )
+    if not success:
+        return None
+
+    entry = client.file_tracker.get(local_file.name, {})
+    return entry.get("drive_id")
+
+
+def set_share_permission(
+    client: DriveClient,
+    file_id: str,
+    *,
+    public: bool = False,
+) -> str | None:
+    """Set a read permission on *file_id*.
+
+    *public* ``False`` (default): restricted to the authenticated user
+    (``type=user``, ``role=reader``).  ``True``: anyone with the link
+    (``type=anyone``, ``role=reader``).
+
+    Returns the permission ID, or ``None`` on failure.
+    """
+    if public:
+        body: dict[str, Any] = {"type": "anyone", "role": "reader"}
+    else:
+        email = _get_authenticated_email(client)
+        if not email:
+            client.last_error = "Could not determine authenticated email"
+            return None
+        body = {"type": "user", "role": "reader", "emailAddress": email}
+
+    try:
+        request = client.drive_service.permissions().create(  # type: ignore[union-attr]
+            fileId=file_id,
+            body=body,
+            fields="id",
+        )
+        result = client._api_call(request)
+        if result:
+            return result.get("id")
+    except Exception as exc:
+        client.last_error = str(exc)
+        logger.warning(f"Failed to set permission on {file_id}: {exc}")
+
+    return None
+
+
+def get_share_link(client: DriveClient, file_id: str) -> str | None:
+    """Retrieve the shareable link for *file_id*.
+
+    Prefers ``webViewLink``; falls back to ``webContentLink``.
+    """
+    try:
+        request = client.drive_service.files().get(  # type: ignore[union-attr]
+            fileId=file_id,
+            fields="webViewLink,webContentLink",
+        )
+        result = client._api_call(request)
+        if result:
+            return result.get("webViewLink") or result.get("webContentLink")
+    except Exception as exc:
+        client.last_error = str(exc)
+        logger.warning(f"Failed to get share link for {file_id}: {exc}")
+
+    return None
+
+
+def share_file(
+    client: DriveClient,
+    local_file: str | Path,
+    *,
+    public: bool = False,
+    note: str = "",
+) -> dict[str, Any]:
+    """Upload, share, and return a link — the complete pipeline.
+
+    Returns a dict with ``success``, ``link``, ``file_id``, and
+    ``error`` keys.
+    """
+    local_file = Path(local_file).resolve()
+
+    if not local_file.is_file():
+        return {
+            "success": False,
+            "link": None,
+            "file_id": None,
+            "error": f"Not a file: {local_file}",
+        }
+
+    file_id = upload_for_share(client, local_file, note=note)
+    if not file_id:
+        return {
+            "success": False,
+            "link": None,
+            "file_id": None,
+            "error": f"Upload failed: {client.last_error or 'unknown'}",
+        }
+
+    perm_id = set_share_permission(client, file_id, public=public)
+    if not perm_id:
+        return {
+            "success": False,
+            "link": None,
+            "file_id": file_id,
+            "error": f"Permission failed: {client.last_error or 'unknown'}",
+        }
+
+    link = get_share_link(client, file_id)
+    if not link:
+        return {
+            "success": False,
+            "link": None,
+            "file_id": file_id,
+            "error": f"Link retrieval failed: {client.last_error or 'unknown'}",
+        }
+
+    json_handler.log_operation(
+        "share_file",
+        {
+            "file": str(local_file),
+            "file_id": file_id,
+            "public": public,
+            "link": link,
+        },
+    )
+
+    return {"success": True, "link": link, "file_id": file_id, "error": None}
+
+
+# =============================================
diff --git a/src/aipass/backup/apps/handlers/ignore/patterns.py b/src/aipass/backup/apps/handlers/ignore/patterns.py
index f77ad88a..5e3c47f9 100644
--- a/src/aipass/backup/apps/handlers/ignore/patterns.py
+++ b/src/aipass/backup/apps/handlers/ignore/patterns.py
@@ -17,37 +17,11 @@ import pathspec
 from ..json import json_handler
 from ..path import builder
 
-BUILTIN_IGNORES = [
-    ".backup/",
-    ".git/",
-    ".svn/",
-    ".hg/",
-    "__pycache__/",
-    ".pytest_cache/",
-    "*.pyc",
-    "*.pyo",
-    "*.egg-info/",
-    ".venv/",
-    "venv/",
-    ".tox/",
-    "node_modules/",
-    ".vscode/",
-    ".idea/",
-    "*.swp",
-    "*.swo",
-    ".DS_Store",
-    "Thumbs.db",
-    "build/",
-    "dist/",
-    "*.log",
-    ".ruff_cache/",
-    ".coverage",
-]
-
 
 def load_spec(project_root: str) -> pathspec.PathSpec:
     """Load a PathSpec from .backupignore at the project root.
 
+    This is the runtime source of truth — the seed template is not consulted here.
     Reads raw lines — pathspec handles #comments, blanks, !negation,
     anchoring, dir-only trailing /, and last-match-wins natively.
 
diff --git a/src/aipass/backup/apps/handlers/project/setup.py b/src/aipass/backup/apps/handlers/project/setup.py
index e0aa3b24..e66cb890 100644
--- a/src/aipass/backup/apps/handlers/project/setup.py
+++ b/src/aipass/backup/apps/handlers/project/setup.py
@@ -15,22 +15,22 @@ inside a target project path, and a ``.backupignore`` at the project root.
 from datetime import datetime, timezone
 from pathlib import Path
 
-from ..ignore.patterns import BUILTIN_IGNORES
 from ..json import json_handler
 from ..path import builder
 
+_TEMPLATE_PATH = Path(__file__).resolve().parents[3] / "templates" / "backupignore.template"
+
 
 def _build_backupignore() -> str:
-    """Generate .backupignore content from BUILTIN_IGNORES."""
-    lines = [
-        "# 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",
-        "",
-    ]
-    for pattern in BUILTIN_IGNORES:
-        lines.append(pattern)
-    return "\n".join(lines) + "\n"
+    """Read the seed .backupignore content from the template file.
+
+    Raises:
+        FileNotFoundError: If the template is missing.
+        OSError: If the template cannot be read.
+    """
+    if not _TEMPLATE_PATH.exists():
+        raise FileNotFoundError(f"Seed template missing: {_TEMPLATE_PATH} — cannot create a safe .backupignore")
+    return _TEMPLATE_PATH.read_text(encoding="utf-8")
 
 
 DEFAULT_CONFIG = {
diff --git a/src/aipass/backup/apps/modules/share.py b/src/aipass/backup/apps/modules/share.py
new file mode 100644
index 00000000..9ce15660
--- /dev/null
+++ b/src/aipass/backup/apps/modules/share.py
@@ -0,0 +1,124 @@
+# =================== AIPass ====================
+# Name: share.py
+# Description: Share module — single-file Drive upload with shareable link
+# Version: 1.0.0
+# Created: 2026-07-01
+# Modified: 2026-07-01
+# =============================================
+
+"""Share Module — upload a single file to Drive and return a shareable link."""
+
+import sys
+
+from aipass.prax import logger
+from aipass.cli.apps.modules import console
+
+from aipass.backup.apps.handlers.json import json_handler
+
+MODULE_NAME = "share"
+PRIMARY_COMMAND = "share"
+
+
+def print_introspection():
+    """Display module info and connected handlers."""
+    console.print(f"[bold cyan]{MODULE_NAME} Module[/bold cyan]")
+    console.print(f"  Primary command: [yellow]{PRIMARY_COMMAND}[/yellow]")
+    console.print("  Status: Live — single-file Drive upload + share link")
+    console.print("  Handlers: drive/client, drive/upload, drive/share")
+
+
+def print_help():
+    """Display help for this module."""
+    print_introspection()
+    console.print()
+    console.print("[bold cyan]USAGE:[/bold cyan]")
+    console.print()
+    console.print("  [dim]drone @backup share <file_path> [--public][/dim]")
+    console.print()
+    console.print("[bold cyan]OPTIONS:[/bold cyan]")
+    console.print()
+    console.print("  [green]--public[/green]   Share with anyone (default: restricted to owner)")
+    console.print()
+    console.print("[bold cyan]OUTPUT:[/bold cyan]")
+    console.print()
+    console.print("  Final stdout line is the shareable Google Drive link.")
+    console.print()
+
+
+def run_share(file_path: str, *, public: bool = False) -> dict:
+    """Upload a single file to Drive and return a shareable link.
+
+    Authenticates via @api, uploads (or reuses existing), sets a
+    share permission, and prints the webViewLink as the last line.
+
+    Args:
+        file_path: Path to the file to share.
+        public: If True, anyone-with-link; else restricted to owner.
+
+    Returns:
+        Result dict with success, link, file_id, error.
+    """
+    from aipass.backup.apps.handlers.drive.client import DriveClient
+    from aipass.backup.apps.handlers.drive.share import share_file
+
+    client = DriveClient()
+    if not client.authenticate():
+        error = f"Drive authentication failed: {client.last_error}"
+        console.print(f"[red]{error}[/red]")
+        logger.warning(f"[backup] {error}")
+        return {"success": False, "link": None, "file_id": None, "error": error}
+
+    console.print(f"[dim]Uploading {file_path}...[/dim]")
+    result = share_file(client, file_path, public=public)
+
+    if result["success"]:
+        mode = "public" if public else "restricted"
+        console.print(f"[green]Shared ({mode}):[/green] {result['link']}")
+        logger.info(f"[backup] Shared {file_path} ({mode})")
+    else:
+        console.print(f"[red]Share failed:[/red] {result['error']}")
+        logger.warning(f"[backup] Share failed: {result['error']}")
+
+    if result.get("link"):
+        console.print(result["link"], highlight=False)
+
+    json_handler.log_operation(
+        "share_command",
+        {
+            "file": file_path,
+            "public": public,
+            "success": result["success"],
+        },
+    )
+
+    return result
+
+
+def handle_command(command: str, args: list) -> bool:
+    """Handle the share command. Returns True if handled."""
+    if command != PRIMARY_COMMAND:
+        return False
+
+    if not args:
+        print_introspection()
+        return True
+
+    if args[0] in ("--help", "-h", "help"):
+        print_help()
+        return True
+
+    file_path = args[0]
+    public = "--public" in args
+
+    run_share(file_path, public=public)
+    return True
+
+
+# =============================================
+
+if __name__ == "__main__":
+    if len(sys.argv) == 1:
+        print_introspection()
+        sys.exit(0)
+    handle_command(PRIMARY_COMMAND, sys.argv[1:])
+    sys.exit(0)
diff --git a/src/aipass/backup/templates/README.md b/src/aipass/backup/templates/README.md
index b4d52f82..5d279a05 100644
--- a/src/aipass/backup/templates/README.md
+++ b/src/aipass/backup/templates/README.md
@@ -3,3 +3,7 @@
 Branch-specific templates for `BACKUP`.
 
 Any templates this branch provides to the system or uses internally. Examples: plan templates (flow), trinity templates (memory), test templates (seedgo).
+
+## Files
+
+- **`backupignore.template`** — Seed content for a new project's `.backupignore`. Written at `register` time by `setup._build_backupignore()`. Edit this to change the default ignore patterns for newly registered projects.
diff --git a/src/aipass/backup/run/.backupignore b/src/aipass/backup/templates/backupignore.template
similarity index 78%
rename from src/aipass/backup/run/.backupignore
rename to src/aipass/backup/templates/backupignore.template
index 57595e6b..5b1c0735 100644
--- a/src/aipass/backup/run/.backupignore
+++ b/src/aipass/backup/templates/backupignore.template
@@ -1,6 +1,6 @@
 # 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
+# Edit this file to customize. Source defaults: templates/backupignore.template
 
 .backup/
 .git/
@@ -24,5 +24,6 @@ Thumbs.db
 build/
 dist/
 *.log
+logs/
 .ruff_cache/
 .coverage
diff --git a/src/aipass/backup/tests/test_ignore_pathspec.py b/src/aipass/backup/tests/test_ignore_pathspec.py
index d96b9d25..49fd36b9 100644
--- a/src/aipass/backup/tests/test_ignore_pathspec.py
+++ b/src/aipass/backup/tests/test_ignore_pathspec.py
@@ -11,7 +11,6 @@
 import pathspec
 
 from aipass.backup.apps.handlers.ignore.patterns import (
-    BUILTIN_IGNORES,
     is_ignored,
     load_spec,
 )
@@ -240,24 +239,61 @@ class TestDotfilesIncluded:
 
 
 class TestSeedTemplate:
-    """BUILTIN_IGNORES is used for seeding, not runtime merge."""
+    """Seed template (backupignore.template) provisions new projects."""
 
-    def test_builtin_has_ruff_cache(self):
-        """Seed defaults include .ruff_cache/."""
-        assert ".ruff_cache/" in BUILTIN_IGNORES
+    def test_template_has_ruff_cache(self):
+        """Seed template includes .ruff_cache/."""
+        from aipass.backup.apps.handlers.project.setup import _TEMPLATE_PATH
 
-    def test_builtin_has_coverage(self):
-        """Seed defaults include .coverage."""
-        assert ".coverage" in BUILTIN_IGNORES
+        content = _TEMPLATE_PATH.read_text(encoding="utf-8")
+        assert ".ruff_cache/" in content
 
-    def test_build_backupignore_content(self):
-        """Seed template includes ruff_cache, coverage, and pycache."""
-        from aipass.backup.apps.handlers.project.setup import _build_backupignore
+    def test_template_has_coverage(self):
+        """Seed template includes .coverage."""
+        from aipass.backup.apps.handlers.project.setup import _TEMPLATE_PATH
+
+        content = _TEMPLATE_PATH.read_text(encoding="utf-8")
+        assert ".coverage" in content
+
+    def test_template_has_logs_dir(self):
+        """Seed template excludes logs/ directories."""
+        from aipass.backup.apps.handlers.project.setup import _TEMPLATE_PATH
+
+        content = _TEMPLATE_PATH.read_text(encoding="utf-8")
+        assert "logs/" in content
+
+    def test_template_has_git(self):
+        """Seed template excludes .git/."""
+        from aipass.backup.apps.handlers.project.setup import _TEMPLATE_PATH
+
+        content = _TEMPLATE_PATH.read_text(encoding="utf-8")
+        assert ".git/" in content
+
+    def test_template_has_venv(self):
+        """Seed template excludes .venv/."""
+        from aipass.backup.apps.handlers.project.setup import _TEMPLATE_PATH
+
+        content = _TEMPLATE_PATH.read_text(encoding="utf-8")
+        assert ".venv/" in content
+
+    def test_build_backupignore_reads_template(self):
+        """_build_backupignore returns the template content."""
+        from aipass.backup.apps.handlers.project.setup import _TEMPLATE_PATH, _build_backupignore
 
         content = _build_backupignore()
-        assert ".ruff_cache/" in content
-        assert ".coverage" in content
-        assert "__pycache__/" in content
+        assert content == _TEMPLATE_PATH.read_text(encoding="utf-8")
+
+    def test_build_backupignore_raises_on_missing_template(self, tmp_path):
+        """Missing template raises FileNotFoundError, not empty content."""
+        from unittest.mock import patch
+
+        import pytest
+
+        from aipass.backup.apps.handlers.project import setup
+
+        fake_path = tmp_path / "nonexistent.template"
+        with patch.object(setup, "_TEMPLATE_PATH", fake_path), pytest.raises(FileNotFoundError):
+            setup._build_backupignore()
 
     def test_seed_writes_only_when_absent(self, tmp_path):
         """Seeding does not overwrite an existing .backupignore."""
diff --git a/src/aipass/backup/tests/test_share.py b/src/aipass/backup/tests/test_share.py
new file mode 100644
index 00000000..4cf6e46a
--- /dev/null
+++ b/src/aipass/backup/tests/test_share.py
@@ -0,0 +1,408 @@
+# =================== AIPass ====================
+# Name: test_share.py
+# Description: Tests for share module + handler (mocked Drive API)
+# Version: 1.0.0
+# Created: 2026-07-01
+# Modified: 2026-07-01
+# =============================================
+
+"""Tests for share — module routing, handler logic, permission paths."""
+
+import importlib
+import sys
+import types
+from unittest.mock import MagicMock, patch
+
+
+def _build_mocks():
+    """Build the standard mock dict for importing share modules."""
+    mocks: dict[str, object] = {}
+
+    prax = types.ModuleType("aipass.prax")
+    setattr(prax, "logger", MagicMock())
+    mocks["aipass.prax"] = prax
+
+    cli = types.ModuleType("aipass.cli")
+    cli_apps = types.ModuleType("aipass.cli.apps")
+    cli_modules = types.ModuleType("aipass.cli.apps.modules")
+    setattr(cli_modules, "console", MagicMock())
+    setattr(cli_modules, "header", MagicMock())
+    setattr(cli_modules, "success", MagicMock())
+    setattr(cli_modules, "warning", MagicMock())
+    setattr(cli_modules, "error", MagicMock())
+    mocks["aipass.cli"] = cli
+    mocks["aipass.cli.apps"] = cli_apps
+    mocks["aipass.cli.apps.modules"] = cli_modules
+
+    json_pkg = types.ModuleType("aipass.backup.apps.handlers.json")
+    json_handler = types.ModuleType(
+        "aipass.backup.apps.handlers.json.json_handler",
+    )
+    setattr(json_handler, "log_operation", MagicMock())
+    setattr(json_handler, "load_json", MagicMock(return_value={}))
+    setattr(json_handler, "save_json", MagicMock())
+    mocks["aipass.backup.apps.handlers.json"] = json_pkg
+    mocks["aipass.backup.apps.handlers.json.json_handler"] = json_handler
+
+    google_client = types.ModuleType("aipass.api.apps.modules.google_client")
+    setattr(google_client, "get_drive_service", MagicMock())
+    setattr(google_client, "api_call_with_retry", MagicMock())
+    mocks["aipass.api.apps.modules.google_client"] = google_client
+    mocks["aipass.api"] = types.ModuleType("aipass.api")
+    mocks["aipass.api.apps"] = types.ModuleType("aipass.api.apps")
+    mocks["aipass.api.apps.modules"] = types.ModuleType("aipass.api.apps.modules")
+
+    ghttp = types.ModuleType("googleapiclient.http")
+    setattr(ghttp, "MediaFileUpload", MagicMock())
+    mocks["googleapiclient"] = types.ModuleType("googleapiclient")
+    mocks["googleapiclient.http"] = ghttp
+
+    return mocks
+
+
+def _fresh_import(module_path: str, mocks: dict):
+    """Import a module with mocked dependencies, clearing stale entries."""
+    stale = [k for k in sys.modules if k.startswith(module_path.rsplit(".", 1)[0])]
+    with patch.dict(sys.modules, mocks):
+        for k in stale:
+            sys.modules.pop(k, None)
+        return importlib.import_module(module_path)
+
+
+# ── Module routing tests ─────────────────────────────────────────────
+
+
+class TestShareModuleRouting:
+    """Verify handle_command routing for the share module."""
+
+    def test_handle_command_returns_true_for_primary(self) -> None:
+        """handle_command returns True for the primary command."""
+        mocks = _build_mocks()
+        mod = _fresh_import("aipass.backup.apps.modules.share", mocks)
+        assert mod.handle_command(mod.PRIMARY_COMMAND, []) is True
+
+    def test_handle_command_returns_false_for_unknown(self) -> None:
+        """handle_command returns False for unknown commands."""
+        mocks = _build_mocks()
+        mod = _fresh_import("aipass.backup.apps.modules.share", mocks)
+        assert mod.handle_command("nonexistent", []) is False
+
+    def test_handle_command_help(self) -> None:
+        """--help flag returns True early."""
+        mocks = _build_mocks()
+        mod = _fresh_import("aipass.backup.apps.modules.share", mocks)
+        assert mod.handle_command(mod.PRIMARY_COMMAND, ["--help"]) is True
+
+    def test_handle_command_help_short(self) -> None:
+        """-h flag returns True early."""
+        mocks = _build_mocks()
+        mod = _fresh_import("aipass.backup.apps.modules.share", mocks)
+        assert mod.handle_command(mod.PRIMARY_COMMAND, ["-h"]) is True
+
+    def test_handle_command_help_word(self) -> None:
+        """help word returns True early."""
+        mocks = _build_mocks()
+        mod = _fresh_import("aipass.backup.apps.modules.share", mocks)
+        assert mod.handle_command(mod.PRIMARY_COMMAND, ["help"]) is True
+
+    def test_module_constants(self) -> None:
+        """MODULE_NAME and PRIMARY_COMMAND are correct."""
+        mocks = _build_mocks()
+        mod = _fresh_import("aipass.backup.apps.modules.share", mocks)
+        assert mod.MODULE_NAME == "share"
+        assert mod.PRIMARY_COMMAND == "share"
+
+
+# ── Handler tests ────────────────────────────────────────────────────
+
+
+def _make_mock_client():
+    """Build a mock DriveClient with chainable Drive API methods."""
+    client = MagicMock()
+    client.last_error = None
+    client.file_tracker = {}
+    client.backup_folder_id = None
+    client.project_folder_cache = {}
+
+    client.get_or_create_project_folder.return_value = "folder-shared-123"
+    client._find_existing_file.return_value = None
+
+    service = MagicMock()
+    client.drive_service = service
+
+    service.permissions.return_value.create.return_value = MagicMock()
+    service.files.return_value.get.return_value = MagicMock()
+    service.files.return_value.create.return_value = MagicMock()
+    service.files.return_value.update.return_value = MagicMock()
+    service.files.return_value.list.return_value = MagicMock()
+    service.about.return_value.get.return_value = MagicMock()
+
+    return client
+
+
+class TestShareHandler:
+    """Test the share handler functions with mocked Drive API."""
+
+    def test_share_file_success_public(self, tmp_path) -> None:
+        """Public share uploads, sets permission, returns webViewLink."""
+        mocks = _build_mocks()
+        handler = _fresh_import("aipass.backup.apps.handlers.drive.share", mocks)
+
+        client = _make_mock_client()
+        test_file = tmp_path / "report.pdf"
+        test_file.write_bytes(b"PDF content")
+
+        client._api_call.side_effect = [
+            {"id": "file-abc-123"},
+            {"id": "perm-xyz-789"},
+            {"webViewLink": "https://drive.google.com/file/d/file-abc-123/view"},
+        ]
+
+        result = handler.share_file(client, str(test_file), public=True)
+
+        assert result["success"] is True
+        assert result["link"] == "https://drive.google.com/file/d/file-abc-123/view"
+        assert result["file_id"] is not None
+        assert result["error"] is None
+
+    def test_share_file_success_restricted(self, tmp_path) -> None:
+        """Restricted share uses authenticated email for permission."""
+        mocks = _build_mocks()
+        handler = _fresh_import("aipass.backup.apps.handlers.drive.share", mocks)
+
+        client = _make_mock_client()
+        test_file = tmp_path / "data.csv"
+        test_file.write_text("a,b,c")
+
+        client._api_call.side_effect = [
+            {"id": "file-def-456"},
+            {"user": {"emailAddress": "test@gmail.com"}},
+            {"id": "perm-abc-123"},
+            {"webViewLink": "https://drive.google.com/file/d/file-def-456/view"},
+        ]
+
+        result = handler.share_file(client, str(test_file), public=False)
+
+        assert result["success"] is True
+        assert result["link"] is not None
+        assert result["error"] is None
+
+    def test_share_file_not_a_file(self, tmp_path) -> None:
+        """Nonexistent path returns error."""
+        mocks = _build_mocks()
+        handler = _fresh_import("aipass.backup.apps.handlers.drive.share", mocks)
+
+        client = _make_mock_client()
+        result = handler.share_file(client, str(tmp_path / "nonexistent.txt"))
+
+        assert result["success"] is False
+        assert "Not a file" in result["error"]
+
+    def test_share_file_directory_rejected(self, tmp_path) -> None:
+        """Directory path returns error."""
+        mocks = _build_mocks()
+        handler = _fresh_import("aipass.backup.apps.handlers.drive.share", mocks)
+
+        client = _make_mock_client()
+        result = handler.share_file(client, str(tmp_path))
+
+        assert result["success"] is False
+        assert "Not a file" in result["error"]
+
+    def test_share_file_upload_failure(self, tmp_path) -> None:
+        """Upload failure surfaces error."""
+        mocks = _build_mocks()
+        handler = _fresh_import("aipass.backup.apps.handlers.drive.share", mocks)
+
+        client = _make_mock_client()
+        client.get_or_create_project_folder.return_value = None
+        client.last_error = "Folder creation failed"
+
+        test_file = tmp_path / "fail.txt"
+        test_file.write_text("content")
+
+        result = handler.share_file(client, str(test_file))
+
+        assert result["success"] is False
+        assert "Upload failed" in result["error"]
+
+    def test_share_file_permission_failure(self, tmp_path) -> None:
+        """Permission failure after upload surfaces error."""
+        mocks = _build_mocks()
+        handler = _fresh_import("aipass.backup.apps.handlers.drive.share", mocks)
+
+        client = _make_mock_client()
+        client._find_existing_file.return_value = {"id": "existing-file-id"}
+
+        client._api_call.side_effect = [
+            {"user": {"emailAddress": "test@gmail.com"}},
+            None,
+        ]
+        client.last_error = "Permission denied"
+
+        test_file = tmp_path / "secret.txt"
+        test_file.write_text("restricted")
+
+        result = handler.share_file(client, str(test_file))
+
+        assert result["success"] is False
+        assert "Permission failed" in result["error"]
+
+    def test_share_file_link_retrieval_failure(self, tmp_path) -> None:
+        """Link retrieval failure after permission surfaces error."""
+        mocks = _build_mocks()
+        handler = _fresh_import("aipass.backup.apps.handlers.drive.share", mocks)
+
+        client = _make_mock_client()
+        client._find_existing_file.return_value = {"id": "file-id"}
+
+        client._api_call.side_effect = [
+            {"id": "perm-id"},
+            None,
+        ]
+        client.last_error = "API error"
+
+        test_file = tmp_path / "doc.txt"
+        test_file.write_text("document")
+
+        result = handler.share_file(client, str(test_file), public=True)
+
+        assert result["success"] is False
+        assert "Link retrieval failed" in result["error"]
+
+    def test_idempotent_reuses_existing(self, tmp_path) -> None:
+        """Existing file on Drive is reused, not re-uploaded."""
+        mocks = _build_mocks()
+        handler = _fresh_import("aipass.backup.apps.handlers.drive.share", mocks)
+
+        client = _make_mock_client()
+        client._find_existing_file.return_value = {"id": "already-on-drive"}
+
+        client._api_call.side_effect = [
+            {"id": "perm-id"},
+            {"webViewLink": "https://drive.google.com/file/d/already-on-drive/view"},
+        ]
+
+        test_file = tmp_path / "existing.txt"
+        test_file.write_text("already uploaded")
+
+        result = handler.share_file(client, str(test_file), public=True)
+
+        assert result["success"] is True
+        assert result["file_id"] == "already-on-drive"
+        client.get_or_create_project_folder.assert_called_once_with("Shared")
+
+    def test_webcontentlink_fallback(self, tmp_path) -> None:
+        """Falls back to webContentLink when webViewLink is absent."""
+        mocks = _build_mocks()
+        handler = _fresh_import("aipass.backup.apps.handlers.drive.share", mocks)
+
+        client = _make_mock_client()
+        client._find_existing_file.return_value = {"id": "file-id"}
+
+        client._api_call.side_effect = [
+            {"id": "perm-id"},
+            {"webContentLink": "https://drive.google.com/uc?id=file-id"},
+        ]
+
+        test_file = tmp_path / "download.bin"
+        test_file.write_bytes(b"\x00\x01")
+
+        result = handler.share_file(client, str(test_file), public=True)
+
+        assert result["success"] is True
+        assert "uc?id=file-id" in result["link"]
+
+
+class TestSetSharePermission:
+    """Test permission-setting specifically."""
+
+    def test_public_permission_body(self, tmp_path) -> None:
+        """Public permission uses type=anyone, role=reader."""
+        mocks = _build_mocks()
+        handler = _fresh_import("aipass.backup.apps.handlers.drive.share", mocks)
+
+        client = _make_mock_client()
+        client._api_call.return_value = {"id": "perm-id"}
+
+        handler.set_share_permission(client, "file-123", public=True)
+
+        call_args = client.drive_service.permissions().create.call_args
+        assert call_args.kwargs["body"]["type"] == "anyone"
+        assert call_args.kwargs["body"]["role"] == "reader"
+
+    def test_restricted_permission_body(self, tmp_path) -> None:
+        """Restricted permission uses type=user with authenticated email."""
+        mocks = _build_mocks()
+        handler = _fresh_import("aipass.backup.apps.handlers.drive.share", mocks)
+
+        client = _make_mock_client()
+        client._api_call.side_effect = [
+            {"user": {"emailAddress": "user@example.com"}},
+            {"id": "perm-id"},
+        ]
+
+        handler.set_share_permission(client, "file-123", public=False)
+
+        call_args = client.drive_service.permissions().create.call_args
+        assert call_args.kwargs["body"]["type"] == "user"
+        assert call_args.kwargs["body"]["emailAddress"] == "user@example.com"
+
+    def test_restricted_fails_without_email(self) -> None:
+        """Restricted permission fails when email lookup returns None."""
+        mocks = _build_mocks()
+        handler = _fresh_import("aipass.backup.apps.handlers.drive.share", mocks)
+
+        client = _make_mock_client()
+        client._api_call.return_value = None
+
+        result = handler.set_share_permission(client, "file-123", public=False)
+
+        assert result is None
+        assert "email" in client.last_error.lower()
+
+
+class TestGetShareLink:
+    """Test link retrieval."""
+
+    def test_prefers_webviewlink(self) -> None:
+        """webViewLink is preferred over webContentLink."""
+        mocks = _build_mocks()
+        handler = _fresh_import("aipass.backup.apps.handlers.drive.share", mocks)
+
+        client = _make_mock_client()
+        client._api_call.return_value = {
+            "webViewLink": "https://view-link",
+            "webContentLink": "https://content-link",
+        }
+
+        link = handler.get_share_link(client, "file-id")
+        assert link == "https://view-link"
+
+    def test_falls_back_to_webcontentlink(self) -> None:
+        """Falls back to webContentLink when webViewLink is None."""
+        mocks = _build_mocks()
+        handler = _fresh_import("aipass.backup.apps.handlers.drive.share", mocks)
+
+        client = _make_mock_client()
+        client._api_call.return_value = {
+            "webViewLink": None,
+            "webContentLink": "https://content-link",
+        }
+
+        link = handler.get_share_link(client, "file-id")
+        assert link == "https://content-link"
+
+    def test_returns_none_on_api_failure(self) -> None:
+        """Returns None when API call fails."""
+        mocks = _build_mocks()
+        handler = _fresh_import("aipass.backup.apps.handlers.drive.share", mocks)
+
+        client = _make_mock_client()
+        client._api_call.return_value = None
+
+        link = handler.get_share_link(client, "file-id")
+        assert link is None
+
+
+# =============================================
diff --git a/src/aipass/cli/.daemon/schedule.json b/src/aipass/cli/.daemon/schedule.json
new file mode 100644
index 00000000..4a960c65
--- /dev/null
+++ b/src/aipass/cli/.daemon/schedule.json
@@ -0,0 +1,18 @@
+{
+  "version": 1,
+  "branch": "@cli",
+  "jobs": [
+    {
+      "id": "wake-test",
+      "enabled": false,
+      "schedule": {
+        "type": "interval",
+        "interval_minutes": 5
+      },
+      "wake": {
+        "fresh": true
+      },
+      "prompt": "AUTOMATED DAEMON TEST. Do ONLY this: run drone @ai_mail email @devpulse \"DAEMON TEST \u2014 cli\" \"Woke via @daemon systemd timer. No memory touched.\" then STOP. Do NOT run startup, do NOT update memory, do NOT do anything else."
+    }
+  ]
+}
diff --git a/src/aipass/commons/.daemon/schedule.json b/src/aipass/commons/.daemon/schedule.json
index 431c2f02..723521bf 100644
--- a/src/aipass/commons/.daemon/schedule.json
+++ b/src/aipass/commons/.daemon/schedule.json
@@ -7,10 +7,11 @@
       "enabled": false,
       "schedule": {
         "type": "interval",
-        "interval_minutes": 1
+        "interval_minutes": 5
       },
       "wake": {
-        "fresh": true
+        "fresh": true,
+        "model": "haiku"
       },
       "prompt": "AUTOMATED DAEMON TEST. Do ONLY this: run drone @ai_mail email @devpulse \"DAEMON TEST FIRED\" \"Wake received from @daemon scheduler. No memory updated.\" then STOP. Do NOT run startup, do NOT update memory, do NOT do anything else."
     }
diff --git a/src/aipass/daemon/.seedgo/bypass.json b/src/aipass/daemon/.seedgo/bypass.json
index e2973693..2e08e887 100644
--- a/src/aipass/daemon/.seedgo/bypass.json
+++ b/src/aipass/daemon/.seedgo/bypass.json
@@ -5,18 +5,6 @@
     "description": "Standards bypass configuration for this branch"
   },
   "bypass": [
-    {
-      "file": "apps/scheduler_cron.py",
-      "standard": "naming",
-      "reason": "False positive: get_due_tasks, mark_dispatching, mark_completed are function references assigned at module level from task_registry imports, not constants",
-      "pattern": "get_due_tasks|mark_dispatching|mark_completed"
-    },
-    {
-      "file": "apps/modules/scheduler_ops.py",
-      "standard": "naming",
-      "reason": "False positive: get_due_tasks, mark_dispatching, mark_completed are function re-exports from task_registry, not constants",
-      "pattern": "get_due_tasks|mark_dispatching|mark_completed"
-    },
     {
       "file": "apps/modules/schedule.py",
       "standard": "naming",
@@ -47,30 +35,12 @@
       "reason": "False positive: red_flags, activity, health_data are local variables inside functions, not module-level constants",
       "pattern": "red_flags|activity|health_data"
     },
-    {
-      "file": "apps/handlers/schedule/task_registry.py",
-      "standard": "naming",
-      "reason": "False positive: task_result, email_body, to_branch are local variables inside functions, not module-level constants",
-      "pattern": "task_result|email_body|to_branch"
-    },
-    {
-      "file": "apps/handlers/actions/actions_registry.py",
-      "standard": "naming",
-      "reason": "False positive: action is a local variable inside functions, not a module-level constant. File name matches its domain (actions/actions_registry.py) — renaming would lose specificity",
-      "pattern": "action|actions_registry"
-    },
     {
       "file": "apps/handlers/actions/action_processor.py",
       "standard": "naming",
       "reason": "False positive: load_registry, is_action_due, update_last_run are function references from try/except import fallback, not constants",
       "pattern": "load_registry|is_action_due|update_last_run"
     },
-    {
-      "file": "apps/scheduler_cron.py",
-      "standard": "architecture",
-      "reason": "Entry point script — lives in apps/ root by design, not a module or handler",
-      "pattern": "File not in standard 3-layer structure"
-    },
     {
       "file": "apps/daemon_wakeup.py",
       "standard": "architecture",
@@ -83,18 +53,6 @@
       "reason": "Branch entry point — lives in apps/ root by design per AIPass convention",
       "pattern": "File not in standard 3-layer structure"
     },
-    {
-      "file": "apps/scheduler_cron.py",
-      "standard": "encapsulation",
-      "reason": "scheduler_cron.py is itself an entry point script that directly uses handler functions — not a module violating encapsulation",
-      "pattern": "Handler imported directly"
-    },
-    {
-      "file": "apps/handlers/schedule/task_registry.py",
-      "standard": "unused_function",
-      "reason": "Public API functions used by tests (test_task_registry.py) and available for external callers",
-      "pattern": "get_task_by_id|get_pending_tasks"
-    },
     {
       "file": "apps/plugins/__init__.py",
       "standard": "unused_function",
@@ -107,6 +65,18 @@
       "reason": "Authorized cross-branch wake_branch import (DPLAN-0204 §2.8 path A). ai_mail exposes wake_branch only via its handler — ai_mail's own modules and @trigger import it identically; no module entry point exists to use. Root fix (an ai_mail module wrapper) is tracked separately.",
       "pattern": "Handler imported directly"
     },
+    {
+      "file": "apps/handlers/schedule/telegram_notifier.py",
+      "standard": "encapsulation",
+      "reason": "Authorized cross-branch import (TDPLAN-0008 contract). daemon emits lifecycle pings via skills telegram notifier — the only send path; no module wrapper exists.",
+      "pattern": "Handler imported directly"
+    },
+    {
+      "file": "apps/handlers/schedule/telegram_notifier.py",
+      "standard": "handlers",
+      "reason": "Authorized cross-branch import (TDPLAN-0008 contract). send_telegram_notification lives in @skills handler — daemon's notifier wraps it fail-soft.",
+      "pattern": "Cross-handler imports"
+    },
     {
       "file": "apps/modules/run.py",
       "standard": "introspection",
@@ -142,6 +112,54 @@
       "standard": "architecture",
       "reason": "Scheduler plugin — autodiscovered by plugins/__init__.py discover_plugins(). Lives in apps/plugins/ by design, not a module or handler.",
       "pattern": "File not in standard 3-layer structure"
+    },
+    {
+      "file": "tests/test_timer_install.py",
+      "standard": "architecture",
+      "reason": "Test file — lives in tests/ by convention, not in 3-layer apps/ structure",
+      "pattern": "File not in standard 3-layer structure"
+    },
+    {
+      "file": "tests/test_run_module.py",
+      "standard": "architecture",
+      "reason": "Test file — lives in tests/ by convention, not in 3-layer apps/ structure",
+      "pattern": "File not in standard 3-layer structure"
+    },
+    {
+      "file": "tests/test_run_module.py",
+      "standard": "documentation",
+      "reason": "Test methods are self-documenting via descriptive names — pytest convention",
+      "pattern": "missing docstrings"
+    },
+    {
+      "file": "tests/test_scheduler_bot.py",
+      "standard": "architecture",
+      "reason": "Test file — lives in tests/ by convention, not in 3-layer apps/ structure",
+      "pattern": "File not in standard 3-layer structure"
+    },
+    {
+      "file": "tests/test_scheduler_bot.py",
+      "standard": "encapsulation",
+      "reason": "Test file imports handlers directly to unit-test them — standard pytest pattern",
+      "pattern": "Handler imported directly"
+    },
+    {
+      "file": "apps/modules/queue.py",
+      "standard": "introspection",
+      "reason": "Bare 'queue' renders the operational Rich table (td-47). Introspection gate would break the primary use case — users expect the job table, not module metadata.",
+      "pattern": "no-args gate"
+    },
+    {
+      "file": "apps/modules/timer_install.py",
+      "standard": "introspection",
+      "reason": "install-timer/uninstall-timer are action commands — no-args IS the action (install). Introspection gate would break primary use case (same pattern as run.py).",
+      "pattern": "no-args gate"
+    },
+    {
+      "file": "apps/modules/timer_install.py",
+      "standard": "modules",
+      "reason": "Installer module — mkdir for ~/.config/systemd/user/ is the core purpose. Direct file ops are inherent to the install function.",
+      "pattern": "direct file operations"
     }
   ],
   "notes": {
diff --git a/src/aipass/daemon/README.md b/src/aipass/daemon/README.md
index 6c1a6395..a17379fd 100644
--- a/src/aipass/daemon/README.md
+++ b/src/aipass/daemon/README.md
@@ -94,6 +94,8 @@ drone @daemon actions list          # Action registry
 drone @daemon actions <id> on/off   # Toggle action
 drone @daemon actions set reminder 7d "msg" --to @branch
 drone @daemon actions set schedule @branch "prompt" daily 04:00
+drone @daemon install-timer           # Install + enable systemd user timer
+drone @daemon uninstall-timer         # Stop + remove systemd user timer
 ```
 
 Each module accepts `--help` for module-specific usage:
@@ -108,11 +110,56 @@ drone @daemon <command> --help
 | Module | Description | Status |
 |--------|-------------|--------|
 | `update` | Status digest of DAEMON activity | *(partial)* — reads inbox/sessions but data_loader paths return empty |
-| `schedule` | Fire-and-forget scheduled follow-ups and task management | Operational |
+| `queue` | Unified job queue view — Rich table or `--json` (frozen schema for @skills bot) | Operational |
+| `schedule` | *(retired)* Fire-and-forget follow-ups — superseded by `.daemon/schedule.json` | Retired |
 | `activity_report` | Branch activity reports: `activity`, `activity-report`, `branch-health` | Operational |
-| `actions` | Action registry CLI — list, toggle, info, set reminder, set schedule, migrate | Operational |
+| `actions` | *(retired)* Action registry — superseded by `.daemon/schedule.json` | Retired |
 | `scheduler_ops` | Scheduler cron operations facade for scheduler_cron.py | Operational |
 | `wakeup_ops` | Wake-up cron operations facade for daemon_wakeup.py | Operational |
+| `timer_install` | Idempotent systemd user timer installer for daemon scheduler | Operational |
+| `run` | Decentralized scheduler tick: discover .daemon/ jobs, fire due ones | Operational |
+
+---
+
+## Scheduling Jobs
+
+Each branch owns its schedule at `src/aipass/<branch>/.daemon/schedule.json`. The daemon discovers and fires — branches define their own jobs.
+
+### Job file schema
+
+```json
+{
+  "version": 1,
+  "branch": "@<branch>",
+  "jobs": [
+    {
+      "id": "my-job",
+      "enabled": true,
+      "schedule": { "type": "interval", "interval_minutes": 30 },
+      "wake": { "fresh": true, "model": "haiku" },
+      "prompt": "Do something, then STOP."
+    }
+  ]
+}
+```
+
+### Schedule types
+
+| Type | Fields | Due when |
+|------|--------|----------|
+| `interval` | `interval_minutes: N` | Elapsed >= N since last_run. Fires immediately if never run. |
+| `daily` | `time: "HH:MM"` | Within +/-15 min of target time, once per day. |
+| `hourly` | `time: "M"` (minute) | Within +/-15 min of target minute, once per hour. |
+| `once` | `due_date: "YYYY-MM-DD"` | Date <= today, then marks completed. |
+
+### Wake options
+
+- `fresh` (bool) — start a fresh Claude session (true) or resume (false)
+- `model` (string, optional) — `"haiku"` or `"sonnet"` recommended for light wakes
+
+### Staggering
+
+No native offset field. To stagger jobs, seed different `last_run` values in `daemon_json/daemon_runstate.json`.
 
 ---
 
@@ -160,11 +207,11 @@ drone @daemon <command> --help
 
 ## Test Suite
 
-- **448 tests** across 19 test files
-- 8/8 modules covered, 43/51 public functions tested
+- **300 tests** across 15 test files
+- 8/8 modules covered, 30/36 public functions tested
 - Seedgo audit: **100%** across all standards
 
-*Last Updated: 2026-04-07*
+*Last Updated: 2026-06-29*
 
 ---
 [← Back to AIPass](../../../README.md)
diff --git a/src/aipass/daemon/apps/daemon.py b/src/aipass/daemon/apps/daemon.py
index 347a4072..43a17c02 100644
--- a/src/aipass/daemon/apps/daemon.py
+++ b/src/aipass/daemon/apps/daemon.py
@@ -24,7 +24,7 @@ from aipass.prax.apps.modules.logger import system_logger as logger
 # Console
 from aipass.cli.apps.modules import console, error
 from aipass.daemon.apps.handlers.json import json_handler
-from aipass.daemon.apps.modules import update, schedule, activity_report, actions, run
+from aipass.daemon.apps.modules import update, schedule, activity_report, actions, run, timer_install, queue
 
 
 def _header(text):
@@ -46,7 +46,7 @@ def get_modules() -> List[Any]:
         List of module objects with handle_command function
     """
     modules = []
-    for mod in [update, schedule, activity_report, actions, run]:
+    for mod in [update, schedule, activity_report, actions, run, timer_install, queue]:
         if hasattr(mod, "handle_command"):
             modules.append(mod)
     return modules
@@ -136,12 +136,15 @@ def print_help(modules: List[Any]):
     # Show actual routable commands, not module names
     _COMMAND_HELP = [
         ("update", "Returns digest of DAEMON activity for check-ins."),
-        ("schedule", "CLI interface for fire-and-forget scheduled follow-ups."),
+        ("queue", "Unified job queue view (--json for frozen schema)."),
         ("activity", "Quick 24-hour activity summary."),
         ("activity-report", "Full detailed activity report (--json for raw)."),
         ("branch-health", "Single branch deep dive (e.g., branch-health DAEMON)."),
-        ("actions", "CLI interface for the numbered action registry."),
         ("run", "One scheduler tick: discover .daemon/ jobs, fire due ones."),
+        ("install-timer", "Install + enable daemon-tick systemd user timer (~2 min)."),
+        ("uninstall-timer", "Stop + remove daemon-tick systemd user timer."),
+        ("schedule", "(retired) Use .daemon/schedule.json — see run --help."),
+        ("actions", "(retired) Use .daemon/schedule.json — see run --help."),
     ]
 
     for cmd_name, desc in _COMMAND_HELP:
diff --git a/src/aipass/daemon/apps/handlers/actions/actions_registry.py b/src/aipass/daemon/apps/handlers/actions/actions_registry.py
deleted file mode 100644
index 8581484d..00000000
--- a/src/aipass/daemon/apps/handlers/actions/actions_registry.py
+++ /dev/null
@@ -1,550 +0,0 @@
-# =================== AIPass ====================
-# Name: actions_registry.py
-# Description: Numbered Action Registry
-# Version: 1.0.0
-# Created: 2026-03-02
-# Modified: 2026-03-02
-# =============================================
-
-"""
-Numbered Action Registry — DPLAN-043
-
-Central registry for all scheduled actions. Each action gets a sequential
-numeric ID (0001, 0002, ...) and can be individually toggled on/off.
-
-Replaces the old all-or-nothing daemon + kill switch model with granular
-per-action control.
-
-Action types:
-  - plugin: Backed by a plugin file in apps/plugins/ (migrated from existing system)
-  - schedule: Custom recurring action (dispatches via wake.py)
-  - reminder: One-shot action that auto-completes after firing
-"""
-
-import json
-from datetime import datetime, timedelta
-from pathlib import Path
-from typing import Optional
-
-from aipass.prax import logger
-from aipass.daemon.apps.handlers.json import json_handler
-
-# logger imported from aipass.prax
-
-# Paths
-_DAEMON_ROOT = Path(__file__).resolve().parents[3]  # src/aipass/daemon/
-REGISTRY_FILE = _DAEMON_ROOT / "daemon_json" / "actions_registry.json"
-PLUGINS_DIR = _DAEMON_ROOT / "apps" / "plugins"
-
-
-def _empty_registry() -> dict:
-    """Return a fresh empty registry structure (avoids shared mutable state)."""
-    return {"version": 1, "next_id": 1, "actions": []}
-
-
-# =============================================
-# STORAGE
-# =============================================
-
-
-def load_registry() -> dict:
-    """Load the actions registry from disk. Returns empty registry if missing."""
-    if not REGISTRY_FILE.exists():
-        return _empty_registry().copy()
-    try:
-        with open(REGISTRY_FILE, "r", encoding="utf-8") as f:
-            data = json.load(f)
-        if "actions" not in data:
-            data["actions"] = []
-        if "next_id" not in data:
-            data["next_id"] = 1
-        return data
-    except (json.JSONDecodeError, OSError) as e:
-        logger.error("[actions_registry] Failed to load: %s", e)
-        return _empty_registry().copy()
-
-
-def save_registry(data: dict) -> bool:
-    """Save the actions registry to disk. Returns True on success."""
-    try:
-        REGISTRY_FILE.parent.mkdir(parents=True, exist_ok=True)
-        with open(REGISTRY_FILE, "w", encoding="utf-8") as f:
-            json.dump(data, f, indent=2)
-            f.write("\n")
-        return True
-    except OSError as e:
-        logger.error("[actions_registry] Failed to save: %s", e)
-        return False
-
-
-# =============================================
-# ID GENERATION
-# =============================================
-
-
-def _get_next_id(registry: dict) -> str:
-    """Get next sequential ID as 4-digit string. Advances next_id."""
-    next_num = registry.get("next_id", 1)
-    action_id = f"{next_num:04d}"
-    registry["next_id"] = next_num + 1
-    return action_id
-
-
-# =============================================
-# CRUD OPERATIONS
-# =============================================
-
-
-def create_action(
-    name: str,
-    action_type: str,
-    schedule_type: str,
-    target_branch: str = "",
-    prompt: str = "",
-    time: Optional[str] = None,
-    interval_minutes: Optional[int] = None,
-    due_date: Optional[str] = None,
-    fresh: bool = True,
-    max_turns: int = 50,
-    enabled: bool = True,
-    self_dispatch: bool = False,
-    plugin_file: Optional[str] = None,
-) -> dict:
-    """
-    Create a new action and save to registry.
-
-    Args:
-        name: Human-readable action name (e.g., "daily_audit")
-        action_type: "plugin" | "schedule" | "reminder"
-        schedule_type: "daily" | "hourly" | "interval" | "once"
-        target_branch: Target branch email (e.g., "@seedgo")
-        prompt: What the dispatched agent should do
-        time: For daily: "HH:MM", for hourly: "MM"
-        interval_minutes: For interval schedule type
-        due_date: For reminder (once) type, ISO date string
-        fresh: Start fresh session (True) or resume (False)
-        max_turns: Max agent turns
-        enabled: Active by default
-        self_dispatch: Plugin handles its own dispatch
-        plugin_file: Plugin filename (without .py) for plugin-backed actions
-
-    Returns:
-        The created action dict
-    """
-    registry = load_registry()
-    action_id = _get_next_id(registry)
-
-    action = {
-        "id": action_id,
-        "name": name,
-        "type": action_type,
-        "schedule_type": schedule_type,
-        "time": time,
-        "interval_minutes": interval_minutes,
-        "due_date": due_date,
-        "target_branch": target_branch,
-        "prompt": prompt,
-        "fresh": fresh,
-        "max_turns": max_turns,
-        "enabled": enabled,
-        "self_dispatch": self_dispatch,
-        "plugin_file": plugin_file,
-        "last_run": None,
-        "next_run": None,
-        "created": datetime.now().isoformat(),
-        "completed": None,
-    }
-
-    registry["actions"].append(action)
-    save_registry(registry)
-
-    json_handler.log_operation("action_registry_modified", {"action": name})
-    logger.info("[actions_registry] Created action %s: %s (%s)", action_id, name, action_type)
-    return action
-
-
-def get_action(action_id: str) -> Optional[dict]:
-    """Get a single action by ID. Returns None if not found."""
-    registry = load_registry()
-    for action in registry["actions"]:
-        if action["id"] == action_id:
-            return action
-    return None
-
-
-def list_actions(include_completed: bool = False) -> list:
-    """
-    List all actions.
-
-    Args:
-        include_completed: If True, include completed reminders.
-
-    Returns:
-        List of action dicts.
-    """
-    registry = load_registry()
-    actions = registry["actions"]
-    if not include_completed:
-        actions = [a for a in actions if a.get("completed") is None]
-    return actions
-
-
-def toggle_action(action_id: str, enabled: bool) -> bool:
-    """Toggle an action on or off. Returns True if found and updated."""
-    registry = load_registry()
-    for action in registry["actions"]:
-        if action["id"] == action_id:
-            action["enabled"] = enabled
-            save_registry(registry)
-            state = "enabled" if enabled else "disabled"
-            logger.info("[actions_registry] Action %s %s: %s", action_id, state, action["name"])
-            return True
-    return False
-
-
-def delete_action(action_id: str) -> bool:
-    """Delete an action by ID. Returns True if found and removed."""
-    registry = load_registry()
-    original_len = len(registry["actions"])
-    registry["actions"] = [a for a in registry["actions"] if a["id"] != action_id]
-    if len(registry["actions"]) < original_len:
-        save_registry(registry)
-        logger.info("[actions_registry] Deleted action %s", action_id)
-        return True
-    return False
-
-
-def update_last_run(action_id: str, timestamp: Optional[str] = None) -> bool:
-    """Update last_run timestamp for an action. Returns True if found."""
-    if timestamp is None:
-        timestamp = datetime.now().isoformat()
-    registry = load_registry()
-    for action in registry["actions"]:
-        if action["id"] == action_id:
-            action["last_run"] = timestamp
-            action["next_run"] = calc_next_run(action)
-            save_registry(registry)
-            return True
-    return False
-
-
-def mark_reminder_completed(action_id: str) -> bool:
-    """Mark a reminder as completed (one-shot). Returns True if found."""
-    registry = load_registry()
-    for action in registry["actions"]:
-        if action["id"] == action_id:
-            action["completed"] = datetime.now().isoformat()
-            action["enabled"] = False
-            save_registry(registry)
-            logger.info("[actions_registry] Reminder %s completed: %s", action_id, action["name"])
-            return True
-    return False
-
-
-# =============================================
-# DUE CHECKING
-# =============================================
-
-
-def _already_ran_today(action: dict, now: datetime) -> bool:
-    """Check if a daily action already ran today."""
-    last_run = action.get("last_run")
-    if not last_run:
-        return False
-    try:
-        last_dt = datetime.fromisoformat(last_run)
-        return last_dt.date() == now.date()
-    except (ValueError, TypeError) as e:
-        logger.info("[actions_registry] Daily last_run parse failed: %s", e)
-        return False
-
-
-def _already_ran_this_hour(action: dict, now: datetime) -> bool:
-    """Check if an hourly action already ran this hour."""
-    last_run = action.get("last_run")
-    if not last_run:
-        return False
-    try:
-        last_dt = datetime.fromisoformat(last_run)
-        return last_dt.hour == now.hour and last_dt.date() == now.date()
-    except (ValueError, TypeError) as e:
-        logger.info("[actions_registry] Hourly last_run parse failed: %s", e)
-        return False
-
-
-def _is_daily_due(action: dict, now: datetime) -> bool:
-    """Check if a daily action is due."""
-    target_time = action.get("time", "00:00")
-    try:
-        target_h, target_m = map(int, target_time.split(":"))
-    except (ValueError, AttributeError) as e:
-        logger.info("[actions_registry] Daily time parse failed for %r: %s", target_time, e)
-        return False
-    current_minutes = now.hour * 60 + now.minute
-    target_minutes = target_h * 60 + target_m
-    minutes_diff = abs(current_minutes - target_minutes)
-    minutes_diff = min(minutes_diff, 1440 - minutes_diff)
-    if minutes_diff > 15:
-        return False
-    return not _already_ran_today(action, now)
-
-
-def _is_hourly_due(action: dict, now: datetime) -> bool:
-    """Check if an hourly action is due."""
-    target_m_str = action.get("time", "0")
-    try:
-        target_m = int(target_m_str)
-    except (ValueError, TypeError) as e:
-        logger.info("[actions_registry] Hourly time parse failed for %r: %s", target_m_str, e)
-        return False
-    minutes_diff = abs(now.minute - target_m)
-    minutes_diff = min(minutes_diff, 60 - minutes_diff)
-    if minutes_diff > 15:
-        return False
-    return not _already_ran_this_hour(action, now)
-
-
-def _is_interval_due(action: dict, now: datetime) -> bool:
-    """Check if an interval action is due."""
-    interval = action.get("interval_minutes", 60)
-    last_run = action.get("last_run")
-    if not last_run:
-        return True
-    try:
-        last_dt = datetime.fromisoformat(last_run)
-        elapsed = (now - last_dt).total_seconds() / 60
-        return elapsed >= interval
-    except (ValueError, TypeError) as e:
-        logger.info("[actions_registry] Interval last_run parse failed: %s", e)
-        return True
-
-
-def _is_once_due(action: dict, now: datetime) -> bool:
-    """Check if a one-shot reminder action is due."""
-    due_date = action.get("due_date")
-    if not due_date:
-        return False
-    try:
-        due_dt = (
-            datetime.fromisoformat(due_date).date()
-            if "T" in due_date
-            else datetime.strptime(due_date, "%Y-%m-%d").date()
-        )
-        return now.date() >= due_dt
-    except (ValueError, TypeError) as e:
-        logger.info("[actions_registry] Once due_date parse failed for %r: %s", due_date, e)
-        return False
-
-
-def is_action_due(action: dict) -> bool:
-    """
-    Check if an action should run now.
-
-    For daily: matches current hour:minute, hasn't run today
-    For hourly: matches current minute, hasn't run this hour
-    For interval: enough time has elapsed since last run
-    For once (reminder): due_date <= today, not completed
-    """
-    if not action.get("enabled", False):
-        return False
-
-    if action.get("completed"):
-        return False
-
-    now = datetime.now()
-    schedule_type = action.get("schedule_type", "")
-
-    _due_checkers = {
-        "daily": _is_daily_due,
-        "hourly": _is_hourly_due,
-        "interval": _is_interval_due,
-        "once": _is_once_due,
-    }
-    checker = _due_checkers.get(schedule_type)
-    if checker is None:
-        return False
-    return checker(action, now)
-
-
-def _calc_next_daily(action: dict, now: datetime) -> Optional[str]:
-    """Calculate next run for a daily action."""
-    target_time = action.get("time", "00:00")
-    try:
-        target_h, target_m = map(int, target_time.split(":"))
-    except (ValueError, AttributeError) as e:
-        logger.info("[actions_registry] calc_next_run daily time parse failed: %s", e)
-        return None
-    next_dt = now.replace(hour=target_h, minute=target_m, second=0, microsecond=0)
-    if next_dt <= now:
-        next_dt += timedelta(days=1)
-    return next_dt.isoformat()
-
-
-def _calc_next_hourly(action: dict, now: datetime) -> Optional[str]:
-    """Calculate next run for an hourly action."""
-    target_m_str = action.get("time", "0")
-    try:
-        target_m = int(target_m_str)
-    except (ValueError, TypeError) as e:
-        logger.info("[actions_registry] calc_next_run hourly time parse failed: %s", e)
-        return None
-    next_dt = now.replace(minute=target_m, second=0, microsecond=0)
-    if next_dt <= now:
-        next_dt += timedelta(hours=1)
-    return next_dt.isoformat()
-
-
-def _calc_next_interval(action: dict, now: datetime) -> Optional[str]:
-    """Calculate next run for an interval action."""
-    interval = action.get("interval_minutes", 60)
-    last_run = action.get("last_run")
-    if not last_run:
-        return now.isoformat()
-    try:
-        last_dt = datetime.fromisoformat(last_run)
-        return (last_dt + timedelta(minutes=interval)).isoformat()
-    except (ValueError, TypeError) as e:
-        logger.info("[actions_registry] calc_next_run interval last_run parse failed: %s", e)
-        return now.isoformat()
-
-
-def calc_next_run(action: dict) -> Optional[str]:
-    """Calculate the next run time for an action. Returns ISO string or None."""
-    now = datetime.now()
-    schedule_type = action.get("schedule_type", "")
-
-    if schedule_type == "daily":
-        return _calc_next_daily(action, now)
-    if schedule_type == "hourly":
-        return _calc_next_hourly(action, now)
-    if schedule_type == "interval":
-        return _calc_next_interval(action, now)
-    if schedule_type == "once":
-        due_date = action.get("due_date")
-        if due_date and not action.get("completed"):
-            return due_date
-        return None
-    return None
-
-
-def _next_due_interval(action: dict) -> str:
-    """Human-readable next due string for interval actions."""
-    interval = action.get("interval_minutes", 60)
-    last_run = action.get("last_run")
-    if not last_run:
-        return "now"
-    try:
-        last_dt = datetime.fromisoformat(last_run)
-        next_dt = last_dt + timedelta(minutes=interval)
-        if next_dt <= datetime.now():
-            return "now"
-        return next_dt.strftime("%H:%M")
-    except (ValueError, TypeError) as e:
-        logger.info("[actions_registry] next_due_str interval last_run parse failed: %s", e)
-        return "now"
-
-
-def next_due_str(action: dict) -> str:
-    """Human-readable next due string for display."""
-    schedule_type = action.get("schedule_type", "")
-
-    if schedule_type == "daily":
-        return f"daily @ {action.get('time', '00:00')}"
-    if schedule_type == "hourly":
-        m = action.get("time", "0")
-        return f"hourly @ :{int(m):02d}"
-    if schedule_type == "interval":
-        return _next_due_interval(action)
-    if schedule_type == "once":
-        return action.get("due_date", "unknown")
-    return "unknown"
-
-
-# =============================================
-# PLUGIN MIGRATION
-# =============================================
-
-
-def migrate_plugins() -> int:
-    """
-    Scan plugins/ directory and auto-register any plugins not yet in the registry.
-
-    Maps PLUGIN_CONFIG fields to action fields. Preserves last_run timestamps
-    from .last_run.json.
-
-    Returns:
-        Number of newly migrated plugins.
-    """
-    registry = load_registry()
-    existing_plugins = {a["plugin_file"] for a in registry["actions"] if a.get("plugin_file")}
-
-    # Load last_run data for timestamp preservation
-    last_run_file = PLUGINS_DIR / ".last_run.json"
-    last_run_map = {}
-    if last_run_file.exists():
-        try:
-            last_run_map = json.loads(last_run_file.read_text(encoding="utf-8"))
-        except (json.JSONDecodeError, OSError) as e:
-            logger.warning("[actions_registry] Failed to load last_run.json: %s", e)
-
-    # Discover plugins
-    migrated = 0
-    for plugin_path in sorted(PLUGINS_DIR.glob("*.py")):
-        if plugin_path.name.startswith("_"):
-            continue
-
-        plugin_name = plugin_path.stem
-        if plugin_name in existing_plugins:
-            continue
-
-        # Import plugin to read PLUGIN_CONFIG
-        try:
-            import importlib
-
-            # Use absolute package path for plugin import
-            spec_name = f"aipass.daemon.apps.plugins.{plugin_name}"
-            module = importlib.import_module(spec_name)
-
-            if not hasattr(module, "PLUGIN_CONFIG"):
-                continue
-
-            config = module.PLUGIN_CONFIG
-        except Exception as e:
-            logger.warning("[actions_registry] Failed to import plugin %s: %s", plugin_name, e)
-            continue
-
-        # Map PLUGIN_CONFIG to action fields
-        action_id = _get_next_id(registry)
-        action = {
-            "id": action_id,
-            "name": config.get("name", plugin_name),
-            "type": "plugin",
-            "schedule_type": config.get("schedule", "interval"),
-            "time": config.get("time"),
-            "interval_minutes": config.get("interval_minutes"),
-            "due_date": None,
-            "target_branch": config.get("branch", ""),
-            "prompt": config.get("prompt", ""),
-            "fresh": config.get("fresh", True),
-            "max_turns": config.get("max_turns", 50),
-            "enabled": config.get("enabled", False),
-            "self_dispatch": config.get("self_dispatch", False),
-            "plugin_file": plugin_name,
-            "last_run": last_run_map.get(config.get("name", plugin_name)),
-            "next_run": None,
-            "created": datetime.now().isoformat(),
-            "completed": None,
-        }
-
-        # Calculate next_run from last_run
-        action["next_run"] = calc_next_run(action)
-
-        registry["actions"].append(action)
-        migrated += 1
-        logger.info("[actions_registry] Migrated plugin: %s -> action %s", plugin_name, action_id)
-
-    if migrated > 0:
-        save_registry(registry)
-        logger.info("[actions_registry] Migration complete: %d plugin(s) migrated", migrated)
-
-    return migrated
diff --git a/src/aipass/daemon/apps/handlers/schedule/__init__.py b/src/aipass/daemon/apps/handlers/schedule/__init__.py
index 4a7d5be6..137cbc2f 100644
--- a/src/aipass/daemon/apps/handlers/schedule/__init__.py
+++ b/src/aipass/daemon/apps/handlers/schedule/__init__.py
@@ -2,10 +2,12 @@
 # META DATA HEADER
 # Name: __init__.py - Schedule Handlers Package
 # Date: 2026-02-04
-# Version: 1.0.0
+# Version: 2.0.0
 # Category: daemon/handlers/schedule
 #
 # CHANGELOG (Max 5 entries):
+#   - v2.0.0 (2026-06-25): task_registry archived (TDPLAN-0008); package
+#     now exposes runstate + discovery for the live .daemon/ scheduler.
 #   - v1.0.0 (2026-02-04): Initial package setup
 #
 # CODE STANDARDS:
@@ -14,25 +16,26 @@
 # =============================================
 
 """
-Schedule handlers for daemon's scheduled follow-ups system.
+Schedule handlers for daemon's decentralized .daemon/ scheduler.
+
+task_registry (fire-and-forget follow-ups) has been archived — superseded
+by the per-branch .daemon/schedule.json model (DPLAN-0204).
 """
 
-from aipass.daemon.apps.handlers.schedule.task_registry import (
-    load_tasks,
-    save_tasks,
-    create_task,
-    delete_task,
-    get_due_tasks,
-    mark_completed,
-    parse_due_date,
+from aipass.daemon.apps.handlers.schedule.runstate import (
+    load_runstate,
+    save_runstate,
+    update_job_runstate,
+    is_job_due,
+    job_key,
 )
+from aipass.daemon.apps.handlers.schedule.discovery import discover_jobs
 
 __all__ = [
-    "load_tasks",
-    "save_tasks",
-    "create_task",
-    "delete_task",
-    "get_due_tasks",
-    "mark_completed",
-    "parse_due_date",
+    "load_runstate",
+    "save_runstate",
+    "update_job_runstate",
+    "is_job_due",
+    "job_key",
+    "discover_jobs",
 ]
diff --git a/src/aipass/daemon/apps/handlers/schedule/runstate.py b/src/aipass/daemon/apps/handlers/schedule/runstate.py
index bc5be838..85353f3a 100644
--- a/src/aipass/daemon/apps/handlers/schedule/runstate.py
+++ b/src/aipass/daemon/apps/handlers/schedule/runstate.py
@@ -250,7 +250,7 @@ def update_job_runstate(
     schedule: dict,
     timestamp: Optional[str] = None,
 ) -> None:
-    """Update last_run and next_run for a job after firing."""
+    """Update runstate for a job after successful firing."""
     if timestamp is None:
         timestamp = datetime.now().isoformat()
 
@@ -258,6 +258,9 @@ def update_job_runstate(
     entry = runstate.setdefault("jobs", {}).setdefault(key, {})
     entry["last_run"] = timestamp
     entry["next_run"] = _calc_next_run(schedule, timestamp)
+    entry["last_status"] = "success"
+    entry["last_success_at"] = timestamp
+    entry["last_error"] = None
 
     if schedule.get("type") == "once":
         entry["completed"] = timestamp
@@ -265,6 +268,28 @@ def update_job_runstate(
     json_handler.log_operation("update_job_runstate", {"key": key})
 
 
+def record_job_failure(
+    runstate: dict,
+    owner: str,
+    job_id: str,
+    error_msg: str,
+    status: str = "failed",
+    timestamp: Optional[str] = None,
+) -> None:
+    """Record a failed job firing in runstate."""
+    if timestamp is None:
+        timestamp = datetime.now().isoformat()
+
+    key = job_key(owner, job_id)
+    entry = runstate.setdefault("jobs", {}).setdefault(key, {})
+    entry["last_run"] = timestamp
+    entry["last_status"] = status
+    entry["last_failure_at"] = timestamp
+    entry["last_error"] = error_msg[:500]
+
+    json_handler.log_operation("record_job_failure", {"key": key, "status": status})
+
+
 def prune_orphans(runstate: dict, active_keys: set) -> int:
     """Remove runstate entries for jobs that no longer exist. Returns count pruned."""
     jobs = runstate.get("jobs", {})
diff --git a/src/aipass/daemon/apps/handlers/schedule/task_registry.py b/src/aipass/daemon/apps/handlers/schedule/task_registry.py
deleted file mode 100644
index 6dd70815..00000000
--- a/src/aipass/daemon/apps/handlers/schedule/task_registry.py
+++ /dev/null
@@ -1,588 +0,0 @@
-# =================== AIPass ====================
-# Name: task_registry.py
-# Description: DAEMON Scheduled Tasks Registry
-# Version: 1.0.0
-# Created: 2026-02-04
-# Modified: 2026-02-04
-# =============================================
-
-"""
-Handler for scheduled task storage and operations.
-
-Fire-and-forget follow-up system for DAEMON.
-Tasks are stored in daemon_json/schedule.json and processed
-when their due date arrives.
-"""
-
-import json
-import uuid
-from pathlib import Path
-from datetime import datetime, timedelta
-from typing import Dict, List, Any, Optional
-import re
-
-from aipass.prax import logger
-from aipass.daemon.apps.handlers.json import json_handler
-
-# =============================================
-# CONSTANTS
-# =============================================
-
-_DAEMON_ROOT = Path(__file__).resolve().parents[3]  # src/aipass/daemon/
-SCHEDULE_JSON_PATH = _DAEMON_ROOT / "daemon_json" / "schedule.json"
-
-DEFAULT_SCHEDULE_DATA: Dict[str, Any] = {"tasks": []}
-
-# =============================================
-# JSON FILE OPERATIONS
-# =============================================
-
-
-def _ensure_json_exists() -> None:
-    """Ensure schedule.json exists, create with defaults if missing."""
-    SCHEDULE_JSON_PATH.parent.mkdir(parents=True, exist_ok=True)
-
-    if not SCHEDULE_JSON_PATH.exists():
-        with open(SCHEDULE_JSON_PATH, "w", encoding="utf-8") as f:
-            json.dump(DEFAULT_SCHEDULE_DATA, f, indent=2, ensure_ascii=False)
-
-
-def ensure_lock_dir() -> Dict[str, Any]:
-    """Ensure the daemon_json directory exists for lock files.
-
-    Returns:
-        Dict with 'path' (str) of the lock file directory.
-    """
-    lock_dir = SCHEDULE_JSON_PATH.parent
-    lock_dir.mkdir(parents=True, exist_ok=True)
-    return {"path": str(lock_dir)}
-
-
-def load_tasks() -> List[Dict[str, Any]]:
-    """
-    Load all tasks from schedule.json.
-
-    Returns:
-        List of task dictionaries
-    """
-    _ensure_json_exists()
-
-    try:
-        with open(SCHEDULE_JSON_PATH, "r", encoding="utf-8") as f:
-            data = json.load(f)
-        return data.get("tasks", [])
-    except (json.JSONDecodeError, IOError) as e:
-        logger.error("[task_registry] Failed to load schedule.json: %s", e)
-        return []
-
-
-def save_tasks(tasks: List[Dict[str, Any]]) -> bool:
-    """
-    Save tasks to schedule.json.
-
-    Args:
-        tasks: List of task dictionaries to save
-
-    Returns:
-        True if successful, False otherwise
-    """
-    _ensure_json_exists()
-
-    try:
-        data = {"tasks": tasks}
-        with open(SCHEDULE_JSON_PATH, "w", encoding="utf-8") as f:
-            json.dump(data, f, indent=2, ensure_ascii=False)
-        return True
-    except IOError as e:
-        logger.error("[task_registry] Failed to save schedule.json: %s", e)
-        return False
-
-
-# =============================================
-# DATE PARSING
-# =============================================
-
-
-def parse_due_date(date_str: str) -> str:
-    """
-    Parse various date formats to ISO 8601 date string.
-
-    Supports:
-        - "7d" -> 7 days from now
-        - "1w" -> 1 week from now
-        - "2w" -> 2 weeks from now
-        - "2026-02-11" -> exact date (ISO 8601)
-
-    Args:
-        date_str: Date string in supported format
-
-    Returns:
-        ISO 8601 date string (YYYY-MM-DD)
-
-    Raises:
-        ValueError: If date format is invalid
-    """
-    date_str = date_str.strip()
-    today = datetime.now().date()
-
-    # Check for relative day format: "7d", "14d", etc.
-    day_match = re.match(r"^(\d+)d$", date_str, re.IGNORECASE)
-    if day_match:
-        days = int(day_match.group(1))
-        future_date = today + timedelta(days=days)
-        return future_date.isoformat()
-
-    # Check for relative week format: "1w", "2w", etc.
-    week_match = re.match(r"^(\d+)w$", date_str, re.IGNORECASE)
-    if week_match:
-        weeks = int(week_match.group(1))
-        future_date = today + timedelta(weeks=weeks)
-        return future_date.isoformat()
-
-    # Check for ISO 8601 date format: "2026-02-11"
-    iso_match = re.match(r"^(\d{4})-(\d{2})-(\d{2})$", date_str)
-    if iso_match:
-        try:
-            # Validate it's a real date
-            year = int(iso_match.group(1))
-            month = int(iso_match.group(2))
-            day = int(iso_match.group(3))
-            parsed_date = datetime(year, month, day).date()
-            return parsed_date.isoformat()
-        except ValueError as e:
-            raise ValueError(f"Invalid date: {date_str}") from e
-
-    raise ValueError(f"Invalid date format: '{date_str}'. Use '7d' (days), '1w' (weeks), or 'YYYY-MM-DD' (ISO date)")
-
-
-# =============================================
-# TASK OPERATIONS
-# =============================================
-
-
-def _generate_task_id() -> str:
-    """Generate 16-character UUID for task ID."""
-    return uuid.uuid4().hex[:16]
-
-
-def create_task(task: str, due_date: str, recipient: str, message: str) -> Dict[str, Any]:
-    """
-    Create a new scheduled task.
-
-    Args:
-        task: Brief description of the task/follow-up
-        due_date: When to trigger (supports "7d", "1w", "YYYY-MM-DD")
-        recipient: Target branch (e.g., "@devpulse")
-        message: Message to deliver when due
-
-    Returns:
-        Created task dictionary
-
-    Raises:
-        ValueError: If due_date format is invalid
-    """
-    json_handler.log_operation("task_created")
-    parsed_due = parse_due_date(due_date)
-
-    new_task: Dict[str, Any] = {
-        "id": _generate_task_id(),
-        "created": datetime.now().date().isoformat(),
-        "due_date": parsed_due,
-        "task": task,
-        "recipient": recipient,
-        "message": message,
-        "status": "pending",
-    }
-
-    tasks = load_tasks()
-    tasks.append(new_task)
-    save_tasks(tasks)
-
-    return new_task
-
-
-def delete_task(task_id: str) -> bool:
-    """
-    Delete a task by ID.
-
-    Args:
-        task_id: 8-character task ID
-
-    Returns:
-        True if task was found and deleted, False otherwise
-    """
-    tasks = load_tasks()
-    original_count = len(tasks)
-
-    tasks = [t for t in tasks if t.get("id") != task_id]
-
-    if len(tasks) < original_count:
-        save_tasks(tasks)
-        return True
-
-    return False
-
-
-def get_due_tasks() -> List[Dict[str, Any]]:
-    """
-    Get all tasks that are due (due_date <= today).
-
-    Only returns tasks with status 'pending' - excludes 'dispatching' and 'completed'.
-
-    Returns:
-        List of tasks that are due for processing
-    """
-    tasks = load_tasks()
-    today = datetime.now().date().isoformat()
-
-    due_tasks = [t for t in tasks if t.get("status") == "pending" and t.get("due_date", "") <= today]
-
-    return due_tasks
-
-
-def mark_dispatching(task_id: str) -> bool:
-    """
-    Mark a task as currently being dispatched.
-
-    Prevents re-dispatch while email is being sent.
-
-    Args:
-        task_id: 8-character task ID
-
-    Returns:
-        True if task was found and marked, False otherwise
-    """
-    tasks = load_tasks()
-
-    for task in tasks:
-        if task.get("id") == task_id:
-            task["status"] = "dispatching"
-            task["dispatch_started"] = datetime.now().isoformat()
-            save_tasks(tasks)
-            return True
-
-    return False
-
-
-def mark_pending(task_id: str) -> bool:
-    """
-    Reset a task to pending status (for retry after failed dispatch).
-
-    Args:
-        task_id: 8-character task ID
-
-    Returns:
-        True if task was found and reset, False otherwise
-    """
-    tasks = load_tasks()
-
-    for task in tasks:
-        if task.get("id") == task_id:
-            task["status"] = "pending"
-            task.pop("dispatch_started", None)
-            save_tasks(tasks)
-            return True
-
-    return False
-
-
-def _is_stale_dispatch(started: str, cutoff: datetime) -> bool:
-    """Check if a dispatch_started timestamp is older than the cutoff."""
-    try:
-        start_time = datetime.fromisoformat(started)
-        return start_time < cutoff
-    except ValueError as e:
-        logger.warning("[task_registry] Invalid dispatch_started timestamp, resetting task: %s", e)
-        return True
-
-
-def recover_stale_dispatches(max_age_minutes: int = 5) -> int:
-    """
-    Reset tasks stuck in 'dispatching' status for too long.
-
-    Called before processing to recover from crashed dispatches.
-
-    Args:
-        max_age_minutes: Maximum time a task can be in dispatching status
-
-    Returns:
-        Number of tasks recovered
-    """
-    tasks = load_tasks()
-    recovered = 0
-    cutoff = datetime.now() - timedelta(minutes=max_age_minutes)
-
-    for task in tasks:
-        if task.get("status") != "dispatching":
-            continue
-        started = task.get("dispatch_started")
-        if not started:
-            continue
-        if _is_stale_dispatch(started, cutoff):
-            task["status"] = "pending"
-            task.pop("dispatch_started", None)
-            recovered += 1
-
-    if recovered:
-        save_tasks(tasks)
-
-    return recovered
-
-
-def mark_completed(task_id: str) -> bool:
-    """
-    Mark a task as completed.
-
-    Args:
-        task_id: 8-character task ID
-
-    Returns:
-        True if task was found and marked, False otherwise
-    """
-    tasks = load_tasks()
-
-    for task in tasks:
-        if task.get("id") == task_id:
-            task["status"] = "completed"
-            task["completed_date"] = datetime.now().date().isoformat()
-            save_tasks(tasks)
-            return True
-
-    return False
-
-
-def get_task_by_id(task_id: str) -> Optional[Dict[str, Any]]:
-    """
-    Get a single task by ID.
-
-    Args:
-        task_id: 8-character task ID
-
-    Returns:
-        Task dictionary if found, None otherwise
-    """
-    tasks = load_tasks()
-
-    for task in tasks:
-        if task.get("id") == task_id:
-            return task
-
-    return None
-
-
-def get_pending_tasks() -> List[Dict[str, Any]]:
-    """
-    Get all pending tasks (not yet due or completed).
-
-    Returns:
-        List of pending tasks
-    """
-    tasks = load_tasks()
-    return [t for t in tasks if t.get("status") == "pending"]
-
-
-# =============================================
-# BATCH PROCESSING
-# =============================================
-
-
-def _safe_mark_pending(task_id: str) -> None:
-    """Best-effort reset a task to pending, logging on failure."""
-    try:
-        mark_pending(task_id)
-    except Exception as pending_err:
-        logger.error("[task_registry] Failed to reset task %s to pending: %s", task_id[:8], pending_err)
-
-
-def process_due_tasks_batch(
-    send_email_fn=None,
-    stale_max_age: int = 5,
-) -> Dict[str, Any]:
-    """
-    Process all due tasks: recover stale, dispatch emails, track results.
-
-    This is the implementation logic for batch task processing.
-    The module layer handles display; this handler returns raw data.
-
-    Args:
-        send_email_fn: Callable to send email (to_branch, subject, message, ...).
-                       If None, email dispatch is skipped.
-        stale_max_age: Maximum minutes before a dispatching task is considered stale.
-
-    Returns:
-        Dict with keys: due, success, failed, recovered, errors (list of str),
-        processed_tasks (list of dicts with id, recipient, task, status).
-    """
-    import time
-
-    results: Dict[str, Any] = {
-        "due": 0,
-        "success": 0,
-        "failed": 0,
-        "recovered": 0,
-        "errors": [],
-        "processed_tasks": [],
-    }
-
-    # Recover any stale dispatches
-    try:
-        recovered = recover_stale_dispatches(max_age_minutes=stale_max_age)
-        results["recovered"] = recovered
-    except Exception as e:
-        logger.warning("[task_registry] Stale dispatch recovery failed: %s", e)
-        results["errors"].append(f"Stale recovery: {e}")
-
-    # Get due tasks
-    try:
-        due_tasks = get_due_tasks()
-    except Exception as e:
-        logger.error("[task_registry] Failed to load due tasks: %s", e)
-        results["errors"].append(f"Load tasks: {e}")
-        return results
-
-    results["due"] = len(due_tasks)
-
-    if not due_tasks:
-        return results
-
-    for task in due_tasks:
-        task_id = task.get("id", "")
-        recipient = task.get("recipient", "")
-        task_desc = task.get("task", "")
-        message = task.get("message", "")
-
-        task_result = {
-            "id": task_id,
-            "recipient": recipient,
-            "task": task_desc,
-            "status": "pending",
-        }
-
-        # Mark as dispatching (prevents re-dispatch)
-        try:
-            mark_dispatching(task_id)
-        except Exception as e:
-            logger.error("[task_registry] Failed to mark task %s as dispatching: %s", task_id[:8], e)
-            results["errors"].append(f"Mark dispatching {task_id[:8]}: {e}")
-            results["failed"] += 1
-            task_result["status"] = "error"
-            task_result["error"] = str(e)
-            results["processed_tasks"].append(task_result)
-            continue
-
-        # Build email body
-        email_body = f"{task_desc}"
-        if message:
-            email_body += f"\n\nDetails:\n{message}"
-
-        # Send the email
-        if send_email_fn is None:
-            mark_pending(task_id)
-            results["failed"] += 1
-            task_result["status"] = "skipped"
-            task_result["error"] = "email function not available"
-            results["errors"].append(f"Email unavailable for {task_id[:8]}")
-            results["processed_tasks"].append(task_result)
-            continue
-
-        try:
-            email_sent = send_email_fn(
-                to_branch=recipient,
-                subject=f"[SCHEDULED] {task_desc}",
-                message=email_body,
-                from_branch="@daemon",
-                auto_execute=True,
-                reply_to="@devpulse",
-            )
-
-            if email_sent:
-                mark_completed(task_id)
-                results["success"] += 1
-                task_result["status"] = "sent"
-            else:
-                mark_pending(task_id)
-                results["failed"] += 1
-                task_result["status"] = "failed"
-                task_result["error"] = "email send returned False"
-                results["errors"].append(f"Email failed: {task_id[:8]} -> {recipient}")
-
-        except Exception as e:
-            logger.error("[task_registry] Email dispatch error for task %s: %s", task_id[:8], e)
-            _safe_mark_pending(task_id)
-            results["failed"] += 1
-            task_result["status"] = "error"
-            task_result["error"] = str(e)
-            results["errors"].append(f"Email error {task_id[:8]}: {e}")
-
-        results["processed_tasks"].append(task_result)
-
-        # Small delay between dispatches (prevents thundering herd)
-        time.sleep(1.0)
-
-    return results
-
-
-# =============================================
-# MAIN - Testing
-# =============================================
-
-if __name__ == "__main__":
-    from rich.console import Console
-    from rich.panel import Panel
-    from rich.table import Table
-
-    console = Console()
-
-    console.print()
-    console.print(Panel.fit("[bold cyan]TASK REGISTRY - Handler Test[/bold cyan]", border_style="bright_blue"))
-    console.print()
-
-    # Test date parsing
-    console.print("[yellow]Testing date parsing:[/yellow]")
-    test_dates = ["7d", "1w", "2w", "2026-03-15"]
-    for d in test_dates:
-        try:
-            result = parse_due_date(d)
-            console.print(f"  {d} -> {result}")
-        except ValueError as e:
-            logger.warning("Date parse test failed for %s: %s", d, e)
-            console.print(f"  {d} -> [red]ERROR: {e}[/red]")
-
-    # Test invalid date
-    try:
-        parse_due_date("invalid")
-    except ValueError as e:
-        logger.info("Expected parse failure for 'invalid': %s", e)
-        console.print(f"  invalid -> [green]Correctly raised: {e}[/green]")
-
-    console.print()
-    console.print("[yellow]Testing task creation:[/yellow]")
-
-    # Create a test task
-    test_task = create_task(
-        task="Test backup health check",
-        due_date="7d",
-        recipient="@devpulse",
-        message="Please verify backup systems are healthy",
-    )
-    console.print(f"  Created task: {test_task['id']}")
-    console.print(f"  Due: {test_task['due_date']}")
-
-    # Show all tasks
-    console.print()
-    console.print("[yellow]Current tasks:[/yellow]")
-    all_tasks = load_tasks()
-
-    table = Table(show_header=True)
-    table.add_column("ID", style="cyan")
-    table.add_column("Task", style="white")
-    table.add_column("Due", style="yellow")
-    table.add_column("Status", style="green")
-
-    for t in all_tasks:
-        table.add_row(t.get("id", "?"), t.get("task", "?")[:30], t.get("due_date", "?"), t.get("status", "?"))
-
-    console.print(table)
-    console.print()
-    console.print(f"[dim]Schedule file: {SCHEDULE_JSON_PATH}[/dim]")
-    console.print()
diff --git a/src/aipass/daemon/apps/handlers/schedule/telegram_notifier.py b/src/aipass/daemon/apps/handlers/schedule/telegram_notifier.py
new file mode 100644
index 00000000..1b8485c4
--- /dev/null
+++ b/src/aipass/daemon/apps/handlers/schedule/telegram_notifier.py
@@ -0,0 +1,53 @@
+# =================== AIPass ====================
+# Name: telegram_notifier.py
+# Description: Scheduler lifecycle notifications via Telegram
+# Version: 3.0.0
+# Created: 2026-02-15
+# Modified: 2026-06-25
+# =============================================
+
+"""
+Scheduler lifecycle notifications — emit running/complete/failed pings
+via the @skills telegram notifier (secret slug: telegram/scheduler).
+
+Fail-soft: if the secret is missing or the send fails, returns False
+and never raises. The tick MUST keep firing jobs regardless.
+"""
+
+from aipass.prax import logger
+from aipass.daemon.apps.handlers.json import json_handler  # noqa: F401
+
+
+def _send(message: str) -> bool:
+    """Send via skills notifier, fail-soft.
+
+    Cross-branch import authorized by TDPLAN-0008 contract —
+    daemon emits lifecycle pings through the skills telegram notifier.
+    """
+    try:
+        from aipass.skills.lib.telegram.apps.handlers.notifier import (  # noqa: E501
+            send_telegram_notification,
+        )
+
+        return send_telegram_notification(message)
+    except Exception as e:
+        logger.info("[telegram_notifier] Send failed (non-fatal): %s", e)
+        return False
+
+
+def notify_triggered(owner: str, job_id: str) -> bool:
+    """Emit 'running' ping when a job fires."""
+    json_handler.log_operation("notify_triggered", {"owner": owner, "job_id": job_id})
+    return _send(f"\U0001f535 {owner}/{job_id} running")
+
+
+def notify_complete(owner: str, job_id: str, summary: str) -> bool:
+    """Emit 'complete' ping after successful dispatch."""
+    json_handler.log_operation("notify_complete", {"owner": owner, "job_id": job_id})
+    return _send(f"✅ {owner}/{job_id} dispatched\n{summary}")
+
+
+def notify_error(owner: str, job_id: str, error: str) -> bool:
+    """Emit 'failed' ping on dispatch failure."""
+    json_handler.log_operation("notify_error", {"owner": owner, "job_id": job_id})
+    return _send(f"❌ {owner}/{job_id} FAILED\n{error}")
diff --git a/src/aipass/daemon/apps/modules/actions.py b/src/aipass/daemon/apps/modules/actions.py
index dcb13576..65cf2457 100644
--- a/src/aipass/daemon/apps/modules/actions.py
+++ b/src/aipass/daemon/apps/modules/actions.py
@@ -1,560 +1,51 @@
 # =================== AIPass ====================
 # Name: actions.py
-# Description: Action Registry CLI Module
-# Version: 1.0.0
+# Description: Action Registry CLI Module (RETIRED)
+# Version: 2.0.0
 # Created: 2026-03-02
-# Modified: 2026-03-02
+# Modified: 2026-06-25
 # =============================================
 
 """
-CLI interface for the numbered action registry.
+RETIRED — the numbered action registry CLI.
+
+Superseded by the decentralized .daemon/schedule.json model (DPLAN-0204).
+Author jobs directly in a branch's .daemon/schedule.json file.
+See: drone @daemon run --help (full schema + schedule types)
 """
 
-# =============================================
-# IMPORTS
-# =============================================
-
-import sys
 from typing import List
 
 from aipass.prax import logger
-
-from aipass.cli.apps.modules import console, error as cli_error
-from aipass.daemon.apps.handlers.actions.actions_registry import (
-    list_actions,
-    get_action,
-    toggle_action,
-    delete_action,
-    create_action,
-    migrate_plugins,
-    next_due_str,
-)
+from aipass.cli.apps.modules import console
 from aipass.daemon.apps.handlers.json import json_handler
 
 
-def _header(text):
-    console.print(f"\n[bold cyan]{'=' * 70}[/bold cyan]")
-    console.print(f"[bold cyan]  {text}[/bold cyan]")
-    console.print(f"[bold cyan]{'=' * 70}[/bold cyan]")
-
-
-def _success(text):
-    console.print(f"[green]OK:[/green] {text}")
-
-
-def _error(text):
-    cli_error(text)
-
-
-# =============================================
-# CONSTANTS
-# =============================================
-
-MODULE_NAME = "actions"
-
-
-# =============================================
-# INTROSPECTION
-# =============================================
-
-
 def print_introspection():
-    """Display module introspection info."""
+    """Display retirement notice."""
     console.print()
-    console.print("[bold cyan]actions Module[/bold cyan]")
+    console.print("[bold cyan]actions Module[/bold cyan] [yellow](RETIRED)[/yellow]")
     console.print()
-    console.print("[dim]CLI interface for the numbered action registry (DPLAN-043)[/dim]")
+    console.print("[dim]This CLI has been retired. Jobs now live in per-branch .daemon/schedule.json files.[/dim]")
+    console.print("[dim]Run [bold]drone @daemon run --help[/bold] for the schema and schedule types.[/dim]")
+    console.print("[dim]Run [bold]drone @daemon queue[/bold] to see the unified job queue.[/dim]")
     console.print()
-    console.print("[yellow]Connected Handlers:[/yellow]")
-    console.print("  handlers/actions/")
-    console.print(
-        "  [cyan]*[/cyan] actions_registry.py"
-        " [dim](list_actions, get_action,"
-        " toggle_action, delete_action, create_action,"
-        " migrate_plugins, next_due_str — registry CRUD)[/dim]"
-    )
-    console.print()
-
-
-# =============================================
-# OUTPUT FORMATTING
-# =============================================
-
-
-def _format_schedule(action: dict) -> str:
-    """Build schedule display string for an action."""
-    schedule_type = action.get("schedule_type", "")
-    if schedule_type == "daily":
-        return f"daily @ {action.get('time', '??:??')}"
-    if schedule_type == "hourly":
-        m = action.get("time", "0")
-        return f"hourly @ :{int(m):02d}"
-    if schedule_type == "interval":
-        mins = action.get("interval_minutes", 0)
-        if mins >= 60:
-            return f"every {mins // 60}h"
-        return f"every {mins}m"
-    if schedule_type == "once":
-        return f"once: {action.get('due_date', '?')}"
-    return schedule_type
-
-
-def _print_actions_table(actions: list) -> None:
-    """Display formatted action list as a table."""
-    console.print()
-    _header("Action Registry")
-    console.print()
-
-    if not actions:
-        console.print("[dim]No actions registered. Run 'actions migrate' to import plugins.[/dim]")
-        console.print()
-        return
-
-    # Header row
-    console.print(f"  {'ID':<6} {'ON':<4} {'NAME':<24} {'TYPE':<10} {'TARGET':<16} {'SCHEDULE':<20} {'NEXT DUE':<16}")
-    console.print("  " + "-" * 96)
-
-    for action in actions:
-        action_id = action.get("id", "????")
-        enabled = "[green]ON[/green] " if action.get("enabled") else "[red]OFF[/red]"
-        name = action.get("name", "")[:22]
-        action_type = action.get("type", "")[:8]
-        target = action.get("target_branch", "")[:14]
-
-        schedule_str = _format_schedule(action)
-        next_due = next_due_str(action)
-
-        console.print(
-            f"  {action_id:<6} {enabled:<4} {name:<24} {action_type:<10} "
-            f"  {target:<16} {schedule_str:<20} {next_due:<16}"
-        )
-
-    console.print()
-    enabled_count = sum(1 for a in actions if a.get("enabled"))
-    console.print(f"  [dim]Total: {len(actions)} actions ({enabled_count} enabled)[/dim]")
-    console.print()
-
-
-def _print_action_detail(action: dict) -> None:
-    """Display detailed view of a single action."""
-    console.print()
-    _header(f"Action {action['id']}: {action['name']}")
-    console.print()
-
-    fields = [
-        ("ID", action.get("id")),
-        ("Name", action.get("name")),
-        ("Type", action.get("type")),
-        ("Enabled", "[green]ON[/green]" if action.get("enabled") else "[red]OFF[/red]"),
-        ("Schedule", action.get("schedule_type")),
-        ("Time", action.get("time")),
-        ("Interval", f"{action.get('interval_minutes')}m" if action.get("interval_minutes") else None),
-        ("Due Date", action.get("due_date")),
-        ("Target", action.get("target_branch")),
-        ("Fresh", action.get("fresh")),
-        ("Max Turns", action.get("max_turns")),
-        ("Self Dispatch", action.get("self_dispatch")),
-        ("Plugin File", action.get("plugin_file")),
-        ("Last Run", action.get("last_run", "never")[:19] if action.get("last_run") else "never"),
-        ("Next Run", next_due_str(action)),
-        ("Created", action.get("created", "")[:19]),
-        ("Completed", action.get("completed")),
-    ]
-
-    for label, value in fields:
-        if value is None:
-            continue
-        console.print(f"  [cyan]{label:<16}[/cyan] {value}")
-
-    # Show prompt (truncated for readability)
-    prompt = action.get("prompt", "")
-    if prompt:
-        console.print()
-        console.print("  [cyan]Prompt:[/cyan]")
-        # Show first 200 chars
-        display_prompt = prompt[:200]
-        if len(prompt) > 200:
-            display_prompt += "..."
-        for line in display_prompt.split("\n"):
-            console.print(f"    [dim]{line}[/dim]")
-
-    console.print()
-
-
-def print_help() -> None:
-    """Display help using Rich formatted output."""
-    console.print()
-    _header("Actions -- Numbered Action Registry")
-    console.print()
-
-    console.print("[yellow]USAGE:[/yellow]")
-    console.print("  drone @daemon actions list")
-    console.print("  drone @daemon actions <id> info")
-    console.print("  drone @daemon actions <id> on")
-    console.print("  drone @daemon actions <id> off")
-    console.print('  drone @daemon actions set reminder <date> "message" [--to @branch]')
-    console.print('  drone @daemon actions set schedule @branch "prompt" <type> [time]')
-    console.print("  drone @daemon actions migrate")
-    console.print("  drone @daemon actions delete <id>")
-    console.print()
-
-    console.print("[yellow]COMMANDS:[/yellow]")
-    console.print("  list         List all registered actions with status")
-    console.print("  <id> info    Show detailed view of a single action")
-    console.print("  <id> on      Enable an action")
-    console.print("  <id> off     Disable an action")
-    console.print("  set          Create a new reminder or schedule")
-    console.print("  migrate      Import existing plugins into registry")
-    console.print("  delete <id>  Remove an action from the registry")
-    console.print()
-
-    console.print("[yellow]SET REMINDER:[/yellow]")
-    console.print('  set reminder 2026-03-11 "Check VERA progress"')
-    console.print('  set reminder 7d "Follow up on PR review" --to @flow')
-    console.print("  [dim]Date formats: YYYY-MM-DD, 1d, 7d, 1w, 2w[/dim]")
-    console.print()
-
-    console.print("[yellow]SET SCHEDULE:[/yellow]")
-    console.print('  set schedule @seedgo "Run audit" daily 04:00')
-    console.print('  set schedule @daemon "Heartbeat" interval 240')
-    console.print('  set schedule @flow "Check plans" hourly 30')
-    console.print("  [dim]Types: daily HH:MM, hourly MM, interval MINUTES[/dim]")
-    console.print()
-
-    console.print("[yellow]EXAMPLES:[/yellow]")
-    console.print("  actions list                                    # See all actions")
-    console.print("  actions 0003 off                                # Disable action 3")
-    console.print("  actions 0003 on                                 # Re-enable it")
-    console.print('  actions set reminder 2026-03-11 "check VERA"    # One-shot reminder')
-    console.print()
-
-
-# =============================================
-# SUBCOMMAND HANDLERS
-# =============================================
-
-
-def _handle_list(_args: List[str]) -> bool:
-    """Handle 'actions list' subcommand."""
-    actions = list_actions()
-    _print_actions_table(actions)
-    logger.info("[DAEMON] actions: Action list displayed")
-    return True
-
-
-def _handle_toggle(action_id: str, enable: bool) -> bool:
-    """Handle 'actions <id> on/off' subcommand."""
-    action = get_action(action_id)
-    if action is None:
-        _error(f"Action not found: {action_id}")
-        return True  # Error displayed
-
-    toggle_action(action_id, enable)
-    state = "enabled" if enable else "disabled"
-    _success(f"Action {action_id} ({action['name']}) {state}")
-    logger.info("[DAEMON] actions: Action toggled")
-    return True
-
-
-def _handle_info(action_id: str) -> bool:
-    """Handle 'actions <id> info' subcommand."""
-    action = get_action(action_id)
-    if action is None:
-        _error(f"Action not found: {action_id}")
-        return True  # Error displayed
-
-    _print_action_detail(action)
-    logger.info("[DAEMON] actions: Action info displayed")
-    return True
-
-
-def _handle_set_reminder(args: List[str]) -> bool:
-    """Handle 'actions set reminder <date> "message" [--to @branch]'."""
-    if len(args) < 2:
-        _error('Usage: actions set reminder <date> "message" [--to @branch]')
-        return True  # Error displayed
-
-    date_str = args[0]
-    message = args[1]
-    target_branch = "@devpulse"  # Default reminder target
-
-    # Parse --to flag
-    if "--to" in args:
-        to_idx = args.index("--to")
-        if to_idx + 1 < len(args):
-            target_branch = args[to_idx + 1]
-
-    # Parse date
-    due_date = _parse_date(date_str)
-    if not due_date:
-        _error(f"Invalid date format: {date_str}")
-        console.print("[dim]Valid formats: YYYY-MM-DD, 1d, 7d, 1w, 2w[/dim]")
-        return True  # Error displayed
-
-    action = create_action(
-        name=message[:50],
-        action_type="reminder",
-        schedule_type="once",
-        target_branch=target_branch,
-        prompt=message,
-        due_date=due_date,
-        fresh=True,
-        max_turns=10,
-        enabled=True,
-    )
-
-    _success(f"Reminder created: {action['id']}")
-    console.print(f"  [dim]Due:[/dim]    {due_date}")
-    console.print(f"  [dim]To:[/dim]     {target_branch}")
-    console.print(f"  [dim]Message:[/dim] {message[:60]}")
-    console.print()
-    logger.info("[DAEMON] actions: Reminder set")
-    return True
-
-
-def _handle_set_schedule(args: List[str]) -> bool:
-    """Handle 'actions set schedule @branch "prompt" <type> [time_spec]'."""
-    if len(args) < 3:
-        _error('Usage: actions set schedule @branch "prompt" <daily|hourly|interval> [time_spec]')
-        return True  # Error displayed
-
-    target_branch = args[0]
-    prompt = args[1]
-    schedule_type = args[2]
-
-    time_val = None
-    interval_minutes = None
-
-    if schedule_type not in ("daily", "hourly", "interval"):
-        _error(f"Unknown schedule type: {schedule_type}")
-        console.print("[dim]Valid types: daily, hourly, interval[/dim]")
-        return True  # Error displayed
-
-    if len(args) < 4:
-        _error(f"{schedule_type.title()} schedule requires a time/value argument")
-        return True  # Error displayed
-
-    if schedule_type in ("daily", "hourly"):
-        time_val = args[3]
-    else:
-        try:
-            interval_minutes = int(args[3])
-        except ValueError:
-            logger.warning("Invalid interval minutes value: %s", args[3])
-            _error(f"Invalid interval minutes: {args[3]}")
-            return True  # Error displayed
-
-    # Generate a name from the prompt
-    name = prompt[:50].replace(" ", "_").lower()
-
-    action = create_action(
-        name=name,
-        action_type="schedule",
-        schedule_type=schedule_type,
-        target_branch=target_branch,
-        prompt=prompt,
-        time=time_val,
-        interval_minutes=interval_minutes,
-        fresh=True,
-        max_turns=50,
-        enabled=True,
-    )
-
-    _success(f"Schedule created: {action['id']}")
-    console.print(f"  [dim]Name:[/dim]   {action['name']}")
-    console.print(f"  [dim]Target:[/dim] {target_branch}")
-    console.print(f"  [dim]Type:[/dim]   {schedule_type}")
-    if time_val:
-        console.print(f"  [dim]Time:[/dim]   {time_val}")
-    if interval_minutes:
-        console.print(f"  [dim]Every:[/dim]  {interval_minutes} minutes")
-    console.print()
-    logger.info("[DAEMON] actions: Schedule set")
-    return True
-
-
-def _handle_migrate(_args: List[str]) -> bool:
-    """Handle 'actions migrate' -- import plugins into registry."""
-    console.print()
-    console.print("[dim]Scanning plugins/ for unregistered plugins...[/dim]")
-
-    count = migrate_plugins()
-
-    if count > 0:
-        _success(f"Migrated {count} plugin(s) into the action registry")
-    else:
-        console.print("[dim]All plugins already registered (or none found).[/dim]")
-
-    # Show the updated list
-    actions = list_actions()
-    _print_actions_table(actions)
-    logger.info("[DAEMON] actions: Plugin migration completed")
-    return True
-
-
-def _handle_delete(args: List[str]) -> bool:
-    """Handle 'actions delete <id>'."""
-    if not args:
-        _error("Action ID required: actions delete <id>")
-        return True  # Error displayed
-
-    action_id = args[0]
-    action = get_action(action_id)
-    if action is None:
-        _error(f"Action not found: {action_id}")
-        return True  # Error displayed
-
-    delete_action(action_id)
-    _success(f"Deleted action {action_id}: {action['name']}")
-    logger.info("[DAEMON] actions: Action deleted")
-    return True
-
-
-# =============================================
-# DATE PARSING
-# =============================================
-
-
-def _parse_date(date_str: str) -> str:
-    """
-    Parse a date string into ISO format.
-
-    Supports: YYYY-MM-DD, 1d, 7d, 1w, 2w
-
-    Returns:
-        ISO date string or empty string on failure.
-    """
-    from datetime import datetime, timedelta
-
-    date_str = date_str.strip()
-
-    # Relative dates
-    if date_str.endswith("d"):
-        try:
-            days = int(date_str[:-1])
-            return (datetime.now() + timedelta(days=days)).strftime("%Y-%m-%d")
-        except ValueError:
-            logger.warning("Invalid relative day format: %s", date_str)
-            return ""
-    elif date_str.endswith("w"):
-        try:
-            weeks = int(date_str[:-1])
-            return (datetime.now() + timedelta(weeks=weeks)).strftime("%Y-%m-%d")
-        except ValueError:
-            logger.warning("Invalid relative week format: %s", date_str)
-            return ""
-
-    # ISO date
-    try:
-        datetime.strptime(date_str, "%Y-%m-%d")
-        return date_str
-    except ValueError:
-        logger.warning("Invalid ISO date format: %s", date_str)
-        return ""
-
-
-# =============================================
-# ORCHESTRATION
-# =============================================
-
-
-def _route_set_subcommand(args: List[str]) -> bool:
-    """Route 'actions set reminder ...' / 'actions set schedule ...'."""
-    if len(args) < 2:
-        _error("Usage: actions set <reminder|schedule> ...")
-        return True  # Error displayed
-    set_type = args[1]
-    if set_type == "reminder":
-        return _handle_set_reminder(args[2:])
-    if set_type == "schedule":
-        return _handle_set_schedule(args[2:])
-    _error(f"Unknown set type: {set_type}. Use 'reminder' or 'schedule'.")
-    return True  # Error displayed
-
-
-def _route_action_id(action_id: str, args: List[str]) -> bool:
-    """Route 'actions <4-digit-id> [on|off|info]'."""
-    if len(args) < 2:
-        return _handle_info(action_id)
-    sub_action = args[1]
-    if sub_action == "on":
-        return _handle_toggle(action_id, True)
-    if sub_action == "off":
-        return _handle_toggle(action_id, False)
-    if sub_action == "info":
-        return _handle_info(action_id)
-    _error(f"Unknown action command: {sub_action}. Use 'on', 'off', or 'info'.")
-    return True  # Error displayed
 
 
 def handle_command(command: str, args: List[str]) -> bool:
-    """
-    Handle 'actions' command and route to subcommands.
-
-    Args:
-        command: Command name (should be 'actions')
-        args: Command arguments
-
-    Returns:
-        True if handled, False otherwise
-    """
+    """Handle 'actions' command — retired, shows migration notice."""
     if command != "actions":
         return False
 
-    try:
-        # No args -- introspection gate
-        if not args:
-            print_introspection()
-            return True
+    if not args:
+        print_introspection()
+        return True
 
-        # Help flag
-        if args[0] in ["--help", "-h", "help"]:
-            print_help()
-            return True
+    if args[0] in ("--help", "-h", "help"):
+        print_introspection()
+        return True
 
-        subcommand = args[0]
-
-        json_handler.log_operation("actions_command", {"subcommand": args[0] if args else "introspection"})
-
-        # Named subcommands
-        if subcommand == "list":
-            return _handle_list(args[1:])
-        if subcommand == "migrate":
-            return _handle_migrate(args[1:])
-        if subcommand == "delete":
-            return _handle_delete(args[1:])
-        if subcommand == "set":
-            return _route_set_subcommand(args)
-
-        # Check if first arg is an action ID (4-digit numeric)
-        if subcommand.isdigit() and len(subcommand) == 4:
-            return _route_action_id(subcommand, args)
-
-        _error(f"Unknown subcommand: {subcommand}")
-        console.print("[dim]Run 'actions --help' for available commands[/dim]")
-        return True  # Command was handled (error displayed)
-
-    except Exception as e:
-        logger.error("[actions] Error in actions command: %s", e, exc_info=True)
-        _error(f"Error: {e}")
-        return True  # Error displayed
-
-
-# =============================================
-# MAIN ENTRY
-# =============================================
-
-
-def main() -> None:
-    """Main entry point for direct execution."""
-    args = sys.argv[1:]
-
-    if not args or args[0] in ["--help", "-h", "help"]:
-        print_help()
-        return
-
-    handle_command("actions", args)
-
-
-if __name__ == "__main__":
-    main()
+    json_handler.log_operation("actions_command_retired", {"args": args[:2]})
+    logger.info("[actions] Retired CLI invoked")
+    print_introspection()
+    return True
diff --git a/src/aipass/daemon/apps/modules/queue.py b/src/aipass/daemon/apps/modules/queue.py
new file mode 100644
index 00000000..31e814ef
--- /dev/null
+++ b/src/aipass/daemon/apps/modules/queue.py
@@ -0,0 +1,200 @@
+# =================== AIPass ====================
+# Name: queue.py
+# Description: Unified job queue view (drone @daemon queue)
+# Version: 1.0.0
+# Created: 2026-06-25
+# Modified: 2026-06-25
+# =============================================
+
+"""
+Unified queue view — aggregates .daemon/schedule.json jobs joined to runstate.
+
+Human-readable Rich table (default) or --json matching the frozen contract
+consumed by @skills' scheduler bot.
+"""
+
+import json
+from datetime import datetime, timezone
+from typing import List, Optional
+
+from aipass.prax import logger
+from aipass.cli.apps.modules import console
+from aipass.daemon.apps.handlers.json import json_handler
+from aipass.daemon.apps.handlers.schedule.discovery import discover_jobs
+from aipass.daemon.apps.handlers.schedule.runstate import (
+    load_runstate,
+    get_job_state,
+)
+
+HANDLED_COMMANDS = {"queue"}
+
+
+def print_introspection():
+    """Display module introspection info."""
+    console.print()
+    console.print("[bold cyan]queue Module[/bold cyan]")
+    console.print()
+    console.print("[dim]Unified job queue view — .daemon/ jobs joined to runstate[/dim]")
+    console.print()
+    console.print("[yellow]Reads:[/yellow]")
+    console.print("  [cyan]*[/cyan] src/aipass/*/.daemon/*.json [dim](per-branch schedule files)[/dim]")
+    console.print("  [cyan]*[/cyan] daemon_json/daemon_runstate.json [dim](last_run/status state)[/dim]")
+    console.print()
+
+
+def print_help():
+    """Display usage information."""
+    console.print("\n[bold cyan]queue — Unified Job Queue View[/bold cyan]")
+    console.print("\n[yellow]USAGE:[/yellow]")
+    console.print("  drone @daemon queue           Show job queue (Rich table)")
+    console.print("  drone @daemon queue --json     Machine-readable JSON (frozen schema)")
+    console.print("  drone @daemon queue --help     Show this help message")
+    console.print()
+
+
+def _schedule_human(job: dict) -> str:
+    """Build human-readable schedule string."""
+    sched = job.get("schedule", {})
+    sched_type = sched.get("type", "")
+    if sched_type == "once":
+        return sched.get("due_date", "?")
+    if sched_type == "daily":
+        return f"daily @ {sched.get('time', '??:??')}"
+    if sched_type == "hourly":
+        m = sched.get("time", "0")
+        return f"hourly @ :{int(m):02d}"
+    if sched_type == "interval":
+        mins = sched.get("interval_minutes", 0)
+        if mins >= 60:
+            return f"every {mins // 60}h"
+        return f"every {mins}m"
+    return sched_type
+
+
+def _compute_next_run(job: dict, state: dict) -> Optional[str]:
+    """Determine next_run from runstate or schedule."""
+    if state.get("completed"):
+        return None
+    next_run = state.get("next_run")
+    if next_run:
+        return next_run
+    sched = job.get("schedule", {})
+    if sched.get("type") == "once":
+        due = sched.get("due_date")
+        if due and "T" not in due:
+            return f"{due}T09:00:00"
+        return due
+    return None
+
+
+def _build_queue(jobs: list, runstate: dict) -> list:
+    """Build unified queue entries from discovered jobs + runstate."""
+    entries = []
+    for job in jobs:
+        state = get_job_state(runstate, job["owner"], job["id"])
+        if state.get("completed"):
+            continue
+
+        owner = job["owner"]
+        if owner.startswith("@"):
+            pass
+        elif "@" in owner:
+            owner = f"@{owner.split('@')[0]}"
+
+        prompt = job.get("prompt", "")
+        flat = " ".join(prompt.split())  # collapse newlines/whitespace → single-line preview
+        preview = flat[:80] + "..." if len(flat) > 80 else flat
+
+        entries.append(
+            {
+                "owner": owner,
+                "id": job["id"],
+                "enabled": job.get("enabled", True),
+                "type": job["schedule"].get("type", ""),
+                "schedule_human": _schedule_human(job),
+                "next_run": _compute_next_run(job, state),
+                "last_run": state.get("last_run"),
+                "last_status": state.get("last_status"),
+                "last_error": state.get("last_error"),
+                "prompt_preview": preview,
+                "wake": job.get("wake", {}),
+            }
+        )
+    return entries
+
+
+def _print_rich_table(entries: list) -> None:
+    """Print queue as a Rich table."""
+    console.print()
+    console.print("[bold cyan]Job Queue[/bold cyan]")
+    console.print()
+
+    if not entries:
+        console.print("[dim]No jobs in queue.[/dim]")
+        console.print()
+        return
+
+    console.print(
+        f"  {'OWNER':<14} {'ID':<20} {'ON':<4} {'TYPE':<9} {'SCHEDULE':<18} {'LAST STATUS':<12} {'NEXT RUN':<20}"
+    )
+    console.print("  " + "-" * 97)
+
+    for e in entries:
+        enabled = "[green]ON[/green] " if e["enabled"] else "[red]OFF[/red]"
+        last_status = e.get("last_status") or "-"
+        next_run = (e.get("next_run") or "-")[:19]
+        console.print(
+            f"  {e['owner']:<14} {e['id']:<20} {enabled:<4} {e['type']:<9} "
+            f"{e['schedule_human']:<18} {last_status:<12} {next_run:<20}"
+        )
+
+    console.print()
+    enabled_count = sum(1 for e in entries if e["enabled"])
+    console.print(f"  [dim]Total: {len(entries)} job(s) ({enabled_count} enabled)[/dim]")
+    console.print()
+
+
+def _build_json_output(entries: list) -> dict:
+    """Build frozen-schema JSON output for @skills consumption."""
+    return {
+        "generated_at": datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ"),
+        "count": len(entries),
+        "jobs": entries,
+    }
+
+
+def handle_command(command: str, args: List[str]) -> bool:
+    """Handle 'queue' command from daemon CLI router."""
+    if command not in HANDLED_COMMANDS:
+        return False
+
+    if not args:
+        json_handler.log_operation("queue_command", {"json": False})
+        jobs = discover_jobs()
+        runstate = load_runstate()
+        entries = _build_queue(jobs, runstate)
+        _print_rich_table(entries)
+        logger.info("[queue] Queue displayed (%d jobs)", len(entries))
+        return True
+
+    if args[0] in ("--help", "-h"):
+        print_help()
+        return True
+
+    json_handler.log_operation("queue_command", {"json": "--json" in args})
+
+    jobs = discover_jobs()
+    runstate = load_runstate()
+    entries = _build_queue(jobs, runstate)
+
+    if "--json" in args:
+        output = _build_json_output(entries)
+        # soft_wrap=True + markup=False — default console.print forces width-80
+        # wrapping on non-TTY and parses [] markup, injecting newlines mid-string
+        # that corrupt machine output. These flags emit clean, parseable JSON.
+        console.print(json.dumps(output, indent=2), soft_wrap=True, markup=False)
+    else:
+        _print_rich_table(entries)
+
+    logger.info("[queue] Queue displayed (%d jobs)", len(entries))
+    return True
diff --git a/src/aipass/daemon/apps/modules/run.py b/src/aipass/daemon/apps/modules/run.py
index fb606463..1101fd26 100644
--- a/src/aipass/daemon/apps/modules/run.py
+++ b/src/aipass/daemon/apps/modules/run.py
@@ -27,6 +27,7 @@ from aipass.daemon.apps.handlers.schedule.runstate import (
     save_runstate,
     is_job_due,
     update_job_runstate,
+    record_job_failure,
     job_key,
     prune_orphans,
 )
@@ -69,6 +70,38 @@ def print_help():
     console.print("\n[yellow]DESCRIPTION:[/yellow]")
     console.print("  Sweeps src/aipass/*/.daemon/*.json for scheduled jobs,")
     console.print("  evaluates due-ness, and wakes each due branch via wake_branch().")
+    console.print("\n[bold cyan]SCHEDULING — How to author a job:[/bold cyan]")
+    console.print("  [bold]File:[/bold] src/aipass/<branch>/.daemon/schedule.json")
+    console.print()
+    console.print("  [bold]Schema:[/bold]")
+    console.print("    {")
+    console.print('      "version": 1,')
+    console.print('      "branch": "@<branch>",')
+    console.print('      "jobs": [')
+    console.print("        {")
+    console.print('          "id": "my-job",')
+    console.print('          "enabled": true,')
+    console.print('          "schedule": { "type": "interval", "interval_minutes": 30 },')
+    console.print('          "wake": { "fresh": true, "model": "haiku" },')
+    console.print('          "prompt": "Do something, then STOP."')
+    console.print("        }")
+    console.print("      ]")
+    console.print("    }")
+    console.print()
+    console.print("  [bold]Schedule types:[/bold]")
+    console.print("    [cyan]interval[/cyan]  interval_minutes: N")
+    console.print("              [dim]Fires when elapsed >= N since last_run. Fires immediately if never run.[/dim]")
+    console.print("    [cyan]daily[/cyan]     time: HH:MM")
+    console.print("              [dim]+/-15 min window, once per day.[/dim]")
+    console.print("    [cyan]hourly[/cyan]    time: M  [dim](minute of hour)[/dim]")
+    console.print("              [dim]+/-15 min window, once per hour.[/dim]")
+    console.print("    [cyan]once[/cyan]      due_date: YYYY-MM-DD")
+    console.print("              [dim]Fires when date <= today, then marks completed.[/dim]")
+    console.print()
+    console.print("  [bold]wake options:[/bold]  fresh (bool), model (haiku/sonnet — use light models)")
+    console.print()
+    console.print("  [bold]Staggering:[/bold] No native offset field. Seed different last_run values")
+    console.print("  in daemon_json/daemon_runstate.json to offset first-fire timing.")
     console.print()
 
 
@@ -80,18 +113,36 @@ def _log(message: str) -> None:
     console.print(f"[{timestamp}] {message}")
 
 
-def _fire_job(job: dict) -> bool:
-    """Fire a single job via direct wake_branch import (DPLAN-0204 path A)."""
+def _should_notify(job: dict) -> bool:
+    """Check if this job should emit telegram notifications."""
+    return job.get("notify", True)
+
+
+def _fire_job(job: dict) -> tuple:
+    """Fire a single job via direct wake_branch import (DPLAN-0204 path A).
+
+    Returns (ok: bool, error_msg: str).
+    """
     # Cross-branch handler import authorized by DPLAN-0204 §2.8
     from aipass.ai_mail.apps.handlers.dispatch.wake import wake_branch  # noqa: E402
+    from aipass.daemon.apps.handlers.schedule.telegram_notifier import (
+        notify_triggered,
+        notify_complete,
+        notify_error,
+    )
 
     owner = job["owner"]
+    job_id = job["id"]
     prompt = job["prompt"]
     wake = job.get("wake", {})
     fresh = wake.get("fresh", True)
     model = wake.get("model")
+    notify = _should_notify(job)
 
-    _log(f"FIRE: {owner}/{job['id']} -> wake_branch({owner}, fresh={fresh}, model={model})")
+    _log(f"FIRE: {owner}/{job_id} -> wake_branch({owner}, fresh={fresh}, model={model})")
+
+    if notify:
+        notify_triggered(owner, job_id)
 
     try:
         status, ok = wake_branch(
@@ -103,16 +154,24 @@ def _fire_job(job: dict) -> bool:
             model=model,
         )
         if ok:
-            _log(f"OK: {owner}/{job['id']} — {status.summary}")
-            logger.info("[run] Fired %s/%s successfully", owner, job["id"])
+            _log(f"OK: {owner}/{job_id} — {status.summary}")
+            logger.info("[run] Fired %s/%s successfully", owner, job_id)
+            if notify:
+                notify_complete(owner, job_id, status.summary)
+            return True, ""
         else:
-            _log(f"FAIL: {owner}/{job['id']} — {status.summary}")
-            logger.warning("[run] Failed to fire %s/%s: %s", owner, job["id"], status.summary)
-        return ok
+            msg = status.summary
+            _log(f"FAIL: {owner}/{job_id} — {msg}")
+            logger.warning("[run] Failed to fire %s/%s: %s", owner, job_id, msg)
+            if notify:
+                notify_error(owner, job_id, msg)
+            return False, msg
     except Exception as e:
-        logger.error("[run] Exception firing %s/%s: %s", owner, job["id"], e)
-        _log(f"ERROR: {owner}/{job['id']} — {e}")
-        return False
+        logger.error("[run] Exception firing %s/%s: %s", owner, job_id, e)
+        _log(f"ERROR: {owner}/{job_id} — {e}")
+        if notify:
+            notify_error(owner, job_id, str(e))
+        return False, str(e)
 
 
 def run_tick(dry_run: bool = False) -> dict:
@@ -177,13 +236,14 @@ def run_tick(dry_run: bool = False) -> dict:
 
     # Step 4: Fire due jobs
     for job in due_jobs:
-        ok = _fire_job(job)
+        ok, error_msg = _fire_job(job)
         if ok:
             results["fired"] += 1
             update_job_runstate(runstate, job["owner"], job["id"], job["schedule"])
-            save_runstate(runstate)
         else:
             results["failed"] += 1
+            record_job_failure(runstate, job["owner"], job["id"], error_msg)
+        save_runstate(runstate)
 
         if job != due_jobs[-1]:
             time.sleep(1.0)
diff --git a/src/aipass/daemon/apps/modules/schedule.py b/src/aipass/daemon/apps/modules/schedule.py
index c3020771..924d6d3c 100644
--- a/src/aipass/daemon/apps/modules/schedule.py
+++ b/src/aipass/daemon/apps/modules/schedule.py
@@ -1,436 +1,51 @@
 # =================== AIPass ====================
 # Name: schedule.py
-# Description: DAEMON Scheduled Follow-ups Module
-# Version: 1.0.0
+# Description: DAEMON Scheduled Follow-ups Module (RETIRED)
+# Version: 2.0.0
 # Created: 2026-02-04
-# Modified: 2026-02-04
+# Modified: 2026-06-25
 # =============================================
 
 """
-CLI interface for fire-and-forget scheduled follow-ups.
+RETIRED — the old fire-and-forget follow-up CLI.
+
+Superseded by the decentralized .daemon/schedule.json model (DPLAN-0204).
+Author jobs directly in a branch's .daemon/schedule.json file.
+See: drone @daemon run --help (full schema + schedule types)
 """
 
-# =============================================
-# IMPORTS
-# =============================================
-
-import sys
-import argparse
-import subprocess
-from pathlib import Path
 from typing import List
 
 from aipass.prax import logger
-
-from aipass.cli.apps.modules import console, error as cli_error
+from aipass.cli.apps.modules import console
 from aipass.daemon.apps.handlers.json import json_handler
-from aipass.daemon.apps.handlers.schedule.task_registry import (
-    load_tasks,
-    create_task,
-    delete_task,
-    parse_due_date,
-    process_due_tasks_batch,
-    ensure_lock_dir,
-)
-
-# File lock for single-instance execution
-try:
-    from filelock import FileLock, Timeout
-
-    FILELOCK_AVAILABLE = True
-except ImportError:
-    FILELOCK_AVAILABLE = False
-    FileLock = None  # type: ignore[assignment,misc]
-    Timeout = None  # type: ignore[assignment,misc]
-    logger.info("Optional: filelock not available")
-
-
-def _header(text):
-    console.print(f"\n[bold cyan]{'=' * 70}[/bold cyan]")
-    console.print(f"[bold cyan]  {text}[/bold cyan]")
-    console.print(f"[bold cyan]{'=' * 70}[/bold cyan]")
-
-
-def _success(text):
-    console.print(f"[green]OK:[/green] {text}")
-
-
-def _error(text):
-    cli_error(text)
-
-
-def _send_email_via_drone(
-    to_branch, subject, message, from_branch="@daemon", auto_execute=True, reply_to=None, **kwargs
-):
-    """Send email via drone @ai_mail send subprocess."""
-    cmd = ["drone", "@ai_mail", "send", to_branch, subject, message]
-    if auto_execute:
-        cmd.append("--dispatch")
-    try:
-        result = subprocess.run(cmd, capture_output=True, text=True, timeout=DRONE_SUBPROCESS_TIMEOUT)
-        return result.returncode == 0
-    except (subprocess.SubprocessError, OSError) as e:
-        logger.warning("Drone email subprocess failed: %s", e)
-        return False
-
-
-AI_MAIL_AVAILABLE = True
-send_email_direct = _send_email_via_drone
-
-# =============================================
-# CONSTANTS
-# =============================================
-
-MODULE_NAME = "schedule"
-
-# Constants
-DRONE_SUBPROCESS_TIMEOUT = 15  # seconds
-STALE_DISPATCH_MAX_AGE = 5  # minutes
-LOCK_ACQUIRE_TIMEOUT = 0  # seconds (non-blocking)
-
-
-# =============================================
-# INTROSPECTION
-# =============================================
 
 
 def print_introspection():
-    """Display module introspection info."""
+    """Display retirement notice."""
     console.print()
-    console.print("[bold cyan]schedule Module[/bold cyan]")
+    console.print("[bold cyan]schedule Module[/bold cyan] [yellow](RETIRED)[/yellow]")
     console.print()
-    console.print("[dim]CLI interface for fire-and-forget scheduled follow-ups[/dim]")
+    console.print("[dim]This CLI has been retired. Jobs now live in per-branch .daemon/schedule.json files.[/dim]")
+    console.print("[dim]Run [bold]drone @daemon run --help[/bold] for the schema and schedule types.[/dim]")
+    console.print("[dim]Run [bold]drone @daemon queue[/bold] to see the unified job queue.[/dim]")
     console.print()
-    console.print("[yellow]Connected Handlers:[/yellow]")
-    console.print("  handlers/schedule/")
-    console.print(
-        "  [cyan]*[/cyan] task_registry.py"
-        " [dim](load_tasks, create_task, delete_task,"
-        " get_due_tasks, mark_completed, parse_due_date,"
-        " mark_dispatching, mark_pending, recover_stale_dispatches,"
-        " process_due_tasks_batch, ensure_lock_dir"
-        " — task CRUD and processing)[/dim]"
-    )
-    console.print()
-
-
-_DAEMON_ROOT = Path(__file__).resolve().parents[3]  # src/aipass/daemon/
-JSON_DIR = _DAEMON_ROOT / "daemon_json"
-
-# =============================================
-# OUTPUT FORMATTING
-# =============================================
-
-
-def _print_task_list(tasks: List[dict]) -> None:
-    """Print formatted task list to console."""
-    console.print()
-    _header("Scheduled Tasks")
-    console.print()
-
-    pending_tasks = [t for t in tasks if t.get("status") == "pending"]
-    completed_tasks = [t for t in tasks if t.get("status") == "completed"]
-
-    if not pending_tasks:
-        console.print("[dim]No pending scheduled tasks.[/dim]")
-    else:
-        console.print("[bold cyan]PENDING TASKS[/bold cyan]")
-        console.print(f"{'ID':<10} {'DUE':<20} {'TO':<15} {'TASK':<40}")
-        console.print("-" * 85)
-
-        for task in pending_tasks:
-            task_id = task.get("id", "")[:8]
-            due = task.get("due_date", "")
-            recipient = task.get("recipient", "")
-            task_text = task.get("task", "")[:38]
-            console.print(f"{task_id:<10} {due:<20} {recipient:<15} {task_text:<40}")
-
-    console.print()
-    console.print(f"[dim]Total: {len(pending_tasks)} pending, {len(completed_tasks)} completed[/dim]")
-    console.print()
-
-
-def _print_help() -> None:
-    """Display help using Rich formatted output."""
-    console.print()
-    _header("Schedule Module - Fire-and-Forget Follow-ups")
-    console.print()
-
-    console.print("[yellow]USAGE:[/yellow]")
-    console.print('  drone @daemon schedule create "task" --due 7d --to @branch --message "details"')
-    console.print("  drone @daemon schedule list")
-    console.print("  drone @daemon schedule delete <id>")
-    console.print("  drone @daemon schedule run-due")
-    console.print()
-
-    console.print("[yellow]COMMANDS:[/yellow]")
-    console.print("  create    Create a new scheduled task")
-    console.print("  list      List all pending scheduled tasks")
-    console.print("  delete    Delete a scheduled task by ID")
-    console.print("  run-due   Execute all due tasks (sends emails, marks complete)")
-    console.print()
-
-    console.print("[yellow]CREATE OPTIONS:[/yellow]")
-    console.print("  --due     (Required) Due date: 1d, 7d, 2w, 1m, or ISO date (2026-02-15)")
-    console.print("  --to      (Required) Recipient branch (e.g., @flow, @seedgo)")
-    console.print("  --message (Optional) Additional details for the follow-up")
-    console.print()
-
-    console.print("[yellow]EXAMPLES:[/yellow]")
-    console.print("  # Remind Flow to check on a plan in 7 days")
-    console.print('  schedule create "Check FPLAN-0290 status" --due 7d --to @flow')
-    console.print()
-    console.print("  # Follow up with Seedgo about code review in 2 weeks")
-    console.print('  schedule create "Code review follow-up" --due 2w --to @seedgo --message "Review PR #45"')
-    console.print()
-    console.print("  # Check all due tasks and send reminder emails")
-    console.print("  schedule run-due")
-    console.print()
-
-
-# =============================================
-# SUBCOMMAND HANDLERS
-# =============================================
-
-
-def _handle_create(args: List[str]) -> bool:
-    """Handle schedule create subcommand."""
-    parser = argparse.ArgumentParser(prog="schedule create", add_help=False)
-    parser.add_argument("task", nargs="?", help="Task description")
-    parser.add_argument("--due", required=True, help="Due date (1d, 7d, 2w, 1m, or ISO date)")
-    parser.add_argument("--to", required=True, dest="recipient", help="Recipient branch")
-    parser.add_argument("--message", default="", help="Additional message details")
-
-    try:
-        parsed = parser.parse_args(args)
-    except SystemExit:
-        logger.warning("Invalid arguments for schedule create")
-        _error('Usage: schedule create "task" --due <date> --to @branch [--message "details"]')
-        return False
-
-    if not parsed.task:
-        _error("Task description is required")
-        console.print('[dim]Usage: schedule create "task" --due <date> --to @branch[/dim]')
-        return False
-
-    # Parse and validate due date
-    due_date = parse_due_date(parsed.due)
-    if not due_date:
-        _error(f"Invalid due date format: {parsed.due}")
-        console.print("[dim]Valid formats: 1d, 7d, 2w, 1m, or ISO date (2026-02-15)[/dim]")
-        return False
-
-    # Create the task
-    try:
-        new_task = create_task(task=parsed.task, due_date=due_date, recipient=parsed.recipient, message=parsed.message)
-        task_id = new_task.get("id", "")
-
-        _success(f"Scheduled task created: {task_id[:8]}")
-        console.print(f"  [dim]Task:[/dim] {parsed.task}")
-        console.print(f"  [dim]Due:[/dim]  {due_date}")
-        console.print(f"  [dim]To:[/dim]   {parsed.recipient}")
-        if parsed.message:
-            console.print(f"  [dim]Msg:[/dim]  {parsed.message[:50]}...")
-        console.print()
-
-        logger.info(f"[DAEMON] Scheduled task created: {task_id[:8]} -> {parsed.recipient}")
-        return True
-
-    except Exception as e:
-        _error(f"Failed to create task: {e}")
-        logger.error(f"[DAEMON] Failed to create scheduled task: {e}", exc_info=True)
-        return False
-
-
-def _handle_list(_args: List[str]) -> bool:
-    """Handle schedule list subcommand."""
-    try:
-        tasks = load_tasks()
-        _print_task_list(tasks)
-        logger.info("[DAEMON] schedule: Task list displayed")
-        return True
-
-    except Exception as e:
-        _error(f"Failed to load tasks: {e}")
-        logger.error(f"[DAEMON] Failed to load scheduled tasks: {e}", exc_info=True)
-        return False
-
-
-def _handle_delete(args: List[str]) -> bool:
-    """Handle schedule delete subcommand."""
-    if not args:
-        _error("Task ID is required")
-        console.print("[dim]Usage: schedule delete <task_id>[/dim]")
-        return False
-
-    task_id = args[0]
-
-    try:
-        deleted = delete_task(task_id)
-        if deleted:
-            _success(f"Task deleted: {task_id[:8]}")
-            logger.info(f"[DAEMON] Scheduled task deleted: {task_id[:8]}")
-            return True
-        else:
-            _error(f"Task not found: {task_id[:8]}")
-            return False
-
-    except Exception as e:
-        _error(f"Failed to delete task: {e}")
-        logger.error(f"[DAEMON] Failed to delete scheduled task: {e}", exc_info=True)
-        return False
-
-
-def _handle_run_due(_args: List[str]) -> bool:
-    """Handle schedule run-due subcommand with single-instance lock."""
-    if not FILELOCK_AVAILABLE:
-        console.print("[dim]filelock not available, running without lock.[/dim]")
-        return _process_due_tasks()
-
-    lock_file = JSON_DIR / "schedule.lock"
-    ensure_lock_dir()
-
-    # Try to acquire lock (non-blocking)
-    # FILELOCK_AVAILABLE guard above ensures these are not None
-    lock = FileLock(lock_file, timeout=LOCK_ACQUIRE_TIMEOUT)  # type: ignore[misc]
-    try:
-        with lock.acquire(timeout=LOCK_ACQUIRE_TIMEOUT):
-            return _process_due_tasks()
-    except Timeout:  # type: ignore[misc]
-        logger.warning("Schedule run-due already in progress, skipping")
-        console.print("[dim]Schedule run-due already in progress, skipping.[/dim]")
-        return True
-
-
-def _display_task_result(task_result: dict) -> None:
-    """Display a single processed task result."""
-    task_id = task_result.get("id", "")[:8]
-    recipient = task_result.get("recipient", "")
-    task_desc = task_result.get("task", "")[:40]
-    status = task_result.get("status", "")
-
-    if status == "sent":
-        _success(f"Sent to {recipient}: {task_desc}")
-        logger.info(f"[DAEMON] Scheduled email sent: {task_id} -> {recipient}")
-    elif status == "skipped":
-        _error(f"ai_mail not available, cannot send to {recipient}")
-    elif status == "failed":
-        _error(f"Failed to send to {recipient}: {task_desc}")
-        logger.error(f"[DAEMON] Scheduled email failed: {task_id} -> {recipient}")
-    elif status == "error":
-        _error(f"Error sending to {recipient}: {task_result.get('error', '')}")
-        logger.error(f"[DAEMON] Scheduled email error: {task_id} -> {recipient}: {task_result.get('error', '')}")
-
-
-def _process_due_tasks() -> bool:
-    """Process due tasks -- delegates to handler, formats output."""
-    try:
-        # Delegate to handler for all implementation logic
-        email_fn = send_email_direct if AI_MAIL_AVAILABLE else None
-        results = process_due_tasks_batch(send_email_fn=email_fn, stale_max_age=STALE_DISPATCH_MAX_AGE)
-
-        # Display results (module responsibility)
-        if results["recovered"]:
-            console.print(f"[dim]Recovered {results['recovered']} stale dispatch(es)[/dim]")
-
-        if results["due"] == 0:
-            console.print("[dim]No tasks due at this time.[/dim]")
-            return True
-
-        console.print()
-        _header(f"Running {results['due']} Due Task(s)")
-        console.print()
-
-        for task_result in results.get("processed_tasks", []):
-            _display_task_result(task_result)
-
-        console.print()
-        console.print(f"[bold]Results:[/bold] {results['success']} sent, {results['failed']} failed")
-        console.print()
-
-        if results["failed"] > 0:
-            logger.warning("[DAEMON] %d scheduled task(s) failed to send", results["failed"])
-        else:
-            logger.info("[DAEMON] schedule: Processed due tasks")
-        return True  # Command was handled (failures are logged, not routing errors)
-
-    except Exception as e:
-        _error(f"Failed to run due tasks: {e}")
-        logger.error(f"[DAEMON] Failed to run due tasks: {e}", exc_info=True)
-        return False
-
-
-# =============================================
-# ORCHESTRATION
-# =============================================
 
 
 def handle_command(command: str, args: List[str]) -> bool:
-    """
-    Handle 'schedule' command.
-
-    Args:
-        command: Command name (should be 'schedule')
-        args: Command arguments (subcommand + subcommand args)
-
-    Returns:
-        True if handled, False otherwise
-    """
+    """Handle 'schedule' command — retired, shows migration notice."""
     if command != "schedule":
         return False
 
-    try:
-        # No args -- introspection gate
-        if not args:
-            print_introspection()
-            return True
+    if not args:
+        print_introspection()
+        return True
 
-        # Handle help flag
-        if args[0] in ["--help", "-h", "help"]:
-            _print_help()
-            return True
+    if args[0] in ("--help", "-h", "help"):
+        print_introspection()
+        return True
 
-        subcommand = args[0]
-        subargs = args[1:]
-
-        json_handler.log_operation("schedule_command", {"subcommand": args[0] if args else "list"})
-
-        # Route to subcommand handlers
-        if subcommand == "create":
-            return _handle_create(subargs)
-        if subcommand == "list":
-            return _handle_list(subargs)
-        if subcommand == "delete":
-            return _handle_delete(subargs)
-        if subcommand == "run-due":
-            return _handle_run_due(subargs)
-
-        _error(f"Unknown subcommand: {subcommand}")
-        console.print("[dim]Run 'schedule --help' for available commands[/dim]")
-        return False
-
-    except Exception as e:
-        logger.error(f"[DAEMON] Error in schedule command: {e}", exc_info=True)
-        _error(f"Error: {e}")
-        return False
-
-
-# =============================================
-# MAIN ENTRY
-# =============================================
-
-
-def main() -> None:
-    """Main entry point for direct execution."""
-    args = sys.argv[1:]
-
-    if len(args) == 0 or args[0] in ["--help", "-h", "help"]:
-        _print_help()
-        return
-
-    # First arg is subcommand when called directly
-    handle_command("schedule", args)
-
-
-if __name__ == "__main__":
-    main()
+    json_handler.log_operation("schedule_command_retired", {"args": args[:2]})
+    logger.info("[schedule] Retired CLI invoked")
+    print_introspection()
+    return True
diff --git a/src/aipass/daemon/apps/modules/scheduler_ops.py b/src/aipass/daemon/apps/modules/scheduler_ops.py
deleted file mode 100644
index 0a0ce246..00000000
--- a/src/aipass/daemon/apps/modules/scheduler_ops.py
+++ /dev/null
@@ -1,133 +0,0 @@
-# =================== AIPass ====================
-# Name: scheduler_ops.py
-# Description: Scheduler Cron Operations Module
-# Version: 2.0.0
-# Created: 2026-03-08
-# Modified: 2026-03-10
-# =============================================
-
-"""
-Scheduler operations module -- facade for cron entry point.
-
-Provides a clean module-layer interface over handler functions
-used by scheduler_cron.py.
-"""
-
-from aipass.prax import logger
-
-from aipass.daemon.apps.handlers.json import json_handler
-
-try:
-    from aipass.cli.apps.modules.display import console
-except ImportError:
-    from rich.console import Console
-
-    console = Console()
-    logger.info("Optional: aipass.cli.apps.modules.display not available, using rich.console fallback")
-
-# =============================================
-# TASK REGISTRY
-# =============================================
-
-try:
-    from aipass.daemon.apps.handlers.schedule.task_registry import (
-        get_due_tasks as get_due_tasks,
-        mark_dispatching as mark_dispatching,
-        mark_completed as mark_completed,
-        mark_pending as mark_pending,
-        recover_stale_dispatches as recover_stale_dispatches,
-    )
-
-    TASK_REGISTRY_AVAILABLE = True
-except ImportError:
-    TASK_REGISTRY_AVAILABLE = False
-    get_due_tasks = None  # type: ignore[assignment]
-    mark_dispatching = None  # type: ignore[assignment]
-    mark_completed = None  # type: ignore[assignment]
-    mark_pending = None  # type: ignore[assignment]
-    recover_stale_dispatches = None  # type: ignore[assignment]
-    logger.info("Optional: task_registry not available")
-
-# =============================================
-# ACTION REGISTRY (DPLAN-043)
-# =============================================
-
-try:
-    from aipass.daemon.apps.handlers.actions.actions_registry import (
-        load_registry as load_registry,
-        is_action_due as is_action_due,
-        update_last_run as update_last_run,
-        mark_reminder_completed as mark_reminder_completed,
-        migrate_plugins as migrate_plugins,
-        next_due_str as next_due_str,
-    )
-
-    ACTION_REGISTRY_AVAILABLE = True
-except ImportError:
-    ACTION_REGISTRY_AVAILABLE = False
-    load_registry = None  # type: ignore[assignment]
-    is_action_due = None  # type: ignore[assignment]
-    update_last_run = None  # type: ignore[assignment]
-    mark_reminder_completed = None  # type: ignore[assignment]
-    migrate_plugins = None  # type: ignore[assignment]
-    next_due_str = None  # type: ignore[assignment]
-    logger.info("Optional: actions_registry not available")
-
-
-# =============================================
-# INTROSPECTION
-# =============================================
-
-
-def print_introspection():
-    """Display module introspection info."""
-    console.print()
-    console.print("[bold cyan]scheduler_ops Module[/bold cyan]")
-    console.print()
-    console.print("[dim]Facade for scheduler_cron.py — re-exports handler functions for cron entry point[/dim]")
-    console.print()
-    console.print("[yellow]Connected Handlers:[/yellow]")
-    console.print("  handlers/schedule/")
-    console.print(
-        "  [cyan]*[/cyan] task_registry.py"
-        " [dim](get_due_tasks, mark_dispatching,"
-        " mark_completed, mark_pending,"
-        " recover_stale_dispatches — task lifecycle)[/dim]"
-    )
-    console.print()
-    console.print("  handlers/actions/")
-    console.print(
-        "  [cyan]*[/cyan] actions_registry.py"
-        " [dim](load_registry, is_action_due,"
-        " update_last_run, mark_reminder_completed,"
-        " migrate_plugins, next_due_str — action registry)[/dim]"
-    )
-    console.print()
-
-
-# =============================================
-# DRONE ROUTING
-# =============================================
-
-
-def handle_command(command: str, args: list) -> bool:
-    """Handle commands routed by the entry point."""
-    if command == "scheduler-ops":
-        if not args:
-            print_introspection()
-            return True
-        if args[0] in ("--help", "-h", "help"):
-            print_introspection()
-            return True
-        json_handler.log_operation("scheduler_ops_status")
-        console.print()
-        console.print("[bold cyan]Scheduler Ops[/bold cyan] - Cron operations facade")
-        console.print()
-        console.print("  [dim]Notifications:[/dim]    archived (Telegram removed)")
-        console.print(f"  [dim]Task registry:[/dim]    {TASK_REGISTRY_AVAILABLE}")
-        console.print(f"  [dim]Action registry:[/dim]  {ACTION_REGISTRY_AVAILABLE}")
-        console.print()
-        console.print("[dim]This module is a facade used by scheduler_cron.py.[/dim]")
-        console.print()
-        return True
-    return False
diff --git a/src/aipass/daemon/apps/modules/timer_install.py b/src/aipass/daemon/apps/modules/timer_install.py
new file mode 100644
index 00000000..0b1041a4
--- /dev/null
+++ b/src/aipass/daemon/apps/modules/timer_install.py
@@ -0,0 +1,183 @@
+# =================== AIPass ====================
+# Name: timer_install.py
+# Description: Idempotent systemd user timer installer for daemon scheduler
+# Version: 1.0.0
+# Created: 2026-06-25
+# Modified: 2026-06-25
+# =============================================
+
+"""
+Timer installer — idempotent install/uninstall of daemon-tick systemd user units.
+
+Handles 'drone @daemon install-timer' and 'drone @daemon uninstall-timer'.
+Copies daemon-tick.service + daemon-tick.timer to ~/.config/systemd/user/,
+reloads systemd, and enables/starts the timer.
+"""
+
+import shutil
+import subprocess
+import sys
+from pathlib import Path
+from typing import List
+
+from aipass.prax import logger
+from aipass.cli.apps.modules import console, error
+from aipass.daemon.apps.handlers.json import json_handler
+
+_DAEMON_ROOT = Path(__file__).resolve().parents[2]
+_UNIT_DIR = Path.home() / ".config" / "systemd" / "user"
+_SERVICE_NAME = "daemon-tick.service"
+_TIMER_NAME = "daemon-tick.timer"
+
+HANDLED_COMMANDS = {"install-timer", "uninstall-timer"}
+
+
+def print_introspection():
+    """Display module introspection info."""
+    console.print()
+    console.print("[bold cyan]timer_install Module[/bold cyan]")
+    console.print()
+    console.print("[dim]Idempotent systemd user timer installer for daemon scheduler[/dim]")
+    console.print()
+    console.print("[yellow]Unit files:[/yellow]")
+    console.print(f"  [cyan]*[/cyan] {_DAEMON_ROOT / _SERVICE_NAME}")
+    console.print(f"  [cyan]*[/cyan] {_DAEMON_ROOT / _TIMER_NAME}")
+    console.print(f"  [cyan]*[/cyan] Installs to: {_UNIT_DIR}/")
+    console.print()
+
+
+def print_help():
+    """Display usage information."""
+    console.print("\n[bold cyan]install-timer / uninstall-timer — Daemon Scheduler Timer[/bold cyan]")
+    console.print("\n[yellow]USAGE:[/yellow]")
+    console.print("  drone @daemon install-timer     Install + enable daemon-tick timer")
+    console.print("  drone @daemon uninstall-timer   Stop + remove daemon-tick timer")
+    console.print("  drone @daemon install-timer --help")
+    console.print("\n[yellow]DESCRIPTION:[/yellow]")
+    console.print("  Copies daemon-tick.service and daemon-tick.timer to")
+    console.print("  ~/.config/systemd/user/")
+    console.print("  Then reloads systemd and enables+starts the timer.")
+    console.print("  Idempotent — safe to run multiple times.")
+    console.print()
+
+
+def _run_systemctl(*args: str) -> bool:
+    """Run a systemctl --user command. Returns True on success."""
+    cmd = ["systemctl", "--user", *args]
+    try:
+        result = subprocess.run(cmd, capture_output=True, text=True, timeout=15)
+        if result.returncode != 0:
+            logger.warning("[timer_install] systemctl --user %s failed: %s", " ".join(args), result.stderr.strip())
+            console.print(f"  [red]FAIL:[/red] systemctl --user {' '.join(args)}")
+            if result.stderr.strip():
+                console.print(f"  [dim]{result.stderr.strip()}[/dim]")
+            return False
+        return True
+    except FileNotFoundError:
+        logger.error("[timer_install] systemctl not found — systemd not available")
+        error("systemctl not found — systemd not available")
+        return False
+    except subprocess.TimeoutExpired:
+        logger.error("[timer_install] systemctl --user %s timed out", " ".join(args))
+        console.print("  [red]systemctl timed out[/red]")
+        return False
+
+
+def _install() -> int:
+    """Install and enable the daemon-tick timer."""
+    service_src = _DAEMON_ROOT / _SERVICE_NAME
+    timer_src = _DAEMON_ROOT / _TIMER_NAME
+
+    for src in (service_src, timer_src):
+        if not src.exists():
+            logger.error("[timer_install] Missing unit file: %s", src)
+            return 1
+
+    _UNIT_DIR.mkdir(parents=True, exist_ok=True)
+
+    json_handler.log_operation("install_timer", {"target": str(_UNIT_DIR)})
+
+    console.print("[bold cyan]Installing daemon-tick units...[/bold cyan]")
+    console.print()
+
+    for src in (service_src, timer_src):
+        dst = _UNIT_DIR / src.name
+        shutil.copy2(src, dst)
+        console.print(f"  [green]Copied:[/green] {src.name} -> {dst}")
+
+    console.print()
+
+    console.print("  Reloading systemd user daemon...")
+    if not _run_systemctl("daemon-reload"):
+        return 1
+
+    console.print("  Enabling daemon-tick.timer...")
+    if not _run_systemctl("enable", _TIMER_NAME):
+        return 1
+
+    console.print("  Starting daemon-tick.timer...")
+    if not _run_systemctl("start", _TIMER_NAME):
+        return 1
+
+    console.print()
+    console.print("[bold green]daemon-tick.timer installed and active.[/bold green]")
+    console.print("[dim]Verify: systemctl --user list-timers | grep daemon[/dim]")
+    console.print()
+
+    Path.home().joinpath(".aipass").mkdir(parents=True, exist_ok=True)
+
+    logger.info("[timer_install] daemon-tick timer installed and started")
+    return 0
+
+
+def _uninstall() -> int:
+    """Stop, disable, and remove the daemon-tick timer."""
+    console.print("[bold cyan]Uninstalling daemon-tick units...[/bold cyan]")
+    console.print()
+
+    _run_systemctl("stop", _TIMER_NAME)
+    _run_systemctl("disable", _TIMER_NAME)
+
+    for name in (_SERVICE_NAME, _TIMER_NAME):
+        dst = _UNIT_DIR / name
+        if dst.exists():
+            dst.unlink()
+            try:
+                from aipass.trigger.apps.modules.core import trigger
+
+                trigger.fire("file_deleted", path=str(dst), source="timer_install")
+            except ImportError:
+                logger.info("[timer_install] Trigger module not available, skipping event fire")
+            except Exception as e:
+                logger.warning("[timer_install] Trigger fire failed (non-critical): %s", e)
+            console.print(f"  [yellow]Removed:[/yellow] {dst}")
+        else:
+            console.print(f"  [dim]Not found:[/dim] {dst}")
+
+    _run_systemctl("daemon-reload")
+
+    console.print()
+    console.print("[bold green]daemon-tick units removed.[/bold green]")
+    console.print()
+
+    logger.info("[timer_install] daemon-tick timer uninstalled")
+    return 0
+
+
+def handle_command(command: str, args: List[str]) -> bool:
+    """Handle install-timer / uninstall-timer commands."""
+    if command not in HANDLED_COMMANDS:
+        return False
+
+    if args and args[0] in ("--help", "-h"):
+        print_help()
+        return True
+
+    if command == "install-timer":
+        exit_code = _install()
+    else:
+        exit_code = _uninstall()
+
+    if exit_code != 0:
+        sys.exit(exit_code)
+    return True
diff --git a/src/aipass/daemon/apps/scheduler_cron.py b/src/aipass/daemon/apps/scheduler_cron.py
deleted file mode 100755
index ecb6a209..00000000
--- a/src/aipass/daemon/apps/scheduler_cron.py
+++ /dev/null
@@ -1,402 +0,0 @@
-# =================== AIPass ====================
-# Name: scheduler_cron.py
-# Description: DAEMON Scheduler Cron Trigger
-# Version: 2.0.0
-# Created: 2026-02-15
-# Modified: 2026-03-24
-# =============================================
-
-"""
-Cron trigger script for the DAEMON scheduled task system.
-
-Called periodically by cron. Standalone script -- not imported as a module.
-
-Flow:
-  1. Acquire single-instance lock
-  2. Recover stale dispatches
-  3. Process all due tasks (send emails, mark complete)
-  4. Process actions from registry
-  5. Log summary
-"""
-
-# =============================================
-# IMPORTS
-# =============================================
-
-import sys
-import time
-import subprocess
-from pathlib import Path
-from datetime import datetime
-
-from aipass.prax.apps.modules.logger import system_logger as logger
-from aipass.cli.apps.modules import console
-from aipass.daemon.apps.handlers.json import json_handler
-
-# action_processor retired — new tick uses .daemon/ discovery (DPLAN-0204)
-from aipass.daemon.apps.modules.run import run_tick
-
-try:
-    import fcntl
-except ImportError:
-    fcntl = None  # type: ignore[assignment]
-    logger.info("[DAEMON] scheduler_cron: fcntl unavailable (Windows)")
-
-# =============================================
-# OPTIONAL IMPORTS (via module layer)
-# =============================================
-
-# Task registry (via module layer)
-try:
-    from aipass.daemon.apps.modules.scheduler_ops import (
-        get_due_tasks,
-        mark_dispatching,
-        mark_completed,
-        mark_pending,
-        recover_stale_dispatches,
-        TASK_REGISTRY_AVAILABLE,
-    )
-except ImportError as e:
-    logger.info(f"Optional dependency not available: scheduler_ops task registry ({e})")
-    TASK_REGISTRY_AVAILABLE = False
-    get_due_tasks = None
-    mark_dispatching = None
-    mark_completed = None
-    mark_pending = None
-    recover_stale_dispatches = None
-
-
-# Email integration via drone subprocess
-def _send_email_via_drone(
-    to_branch, subject, message, from_branch="@daemon", auto_execute=True, reply_to=None, **kwargs
-):
-    """Send email via drone @ai_mail send subprocess."""
-    cmd = ["drone", "@ai_mail", "send", to_branch, subject, message]
-    if auto_execute:
-        cmd.append("--dispatch")
-    try:
-        result = subprocess.run(cmd, capture_output=True, text=True, timeout=15)
-        return result.returncode == 0
-    except (subprocess.SubprocessError, OSError) as e:
-        logger.warning(f"Drone email subprocess failed: {e}")
-        return False
-
-
-AI_MAIL_AVAILABLE = True
-send_email_direct = _send_email_via_drone
-
-
-# =============================================
-# CONSTANTS
-# =============================================
-
-_DAEMON_ROOT = Path(__file__).resolve().parents[2]  # src/aipass/daemon/
-JSON_DIR = _DAEMON_ROOT / "daemon_json"
-
-EVENT_NAME = "cron-run"
-LOCK_FILE = JSON_DIR / "schedule.lock"
-STALE_DISPATCH_MAX_AGE = 5  # minutes
-
-
-# =============================================
-# LOGGING
-# =============================================
-
-
-def print_introspection():
-    """Display module introspection info."""
-    console.print()
-    console.print("[bold cyan]scheduler_cron Module[/bold cyan]")
-    console.print()
-    console.print("[dim]Cron trigger for scheduled tasks and action registry processing[/dim]")
-    console.print()
-    console.print("[yellow]Connected Handlers:[/yellow]")
-    console.print("  modules/")
-    console.print(
-        "  [cyan]*[/cyan] scheduler_ops.py [dim](task registry ops + action registry ops, notifications archived)[/dim]"
-    )
-    console.print()
-    console.print("  plugins/")
-    console.print("  [cyan]*[/cyan] discover_plugins [dim](plugin discovery and scheduled execution)[/dim]")
-    console.print()
-
-
-def print_help() -> None:
-    """Display usage information for scheduler_cron."""
-    console.print("\n[bold cyan]scheduler_cron.py - DAEMON Scheduler Cron Trigger[/bold cyan]")
-    console.print("\n[yellow]USAGE:[/yellow]")
-    console.print("  drone @daemon scheduler_cron          Run the cron scheduler")
-    console.print("  drone @daemon scheduler_cron --help   Show this help message")
-    console.print("\n[yellow]DESCRIPTION:[/yellow]")
-    console.print("  Processes due scheduled tasks and actions from the registry.")
-    console.print("  Intended to be called periodically by cron.")
-    console.print()
-
-
-def log(message: str) -> None:
-    """Print timestamped log line to stdout (captured by cron redirect)."""
-    timestamp = datetime.now().strftime("%Y-%m-%d %H:%M:%S")
-    console.print(f"[{timestamp}] {message}")
-
-
-# =============================================
-# TASK PROCESSING
-# =============================================
-
-
-def process_due_tasks() -> dict:
-    """
-    Process all due scheduled tasks.
-
-    Recovers stale dispatches, then iterates due tasks:
-    mark dispatching -> send email -> mark completed or reset to pending.
-
-    Returns:
-        Dict with keys: due, success, failed, errors (list of error strings)
-    """
-    results = {
-        "due": 0,
-        "success": 0,
-        "failed": 0,
-        "recovered": 0,
-        "errors": [],
-    }
-
-    if not TASK_REGISTRY_AVAILABLE:
-        log("WARNING: Task registry not available, skipping task processing")
-        return results
-
-    # Recover any stale dispatches (stuck > 5 minutes)
-    try:
-        recovered = recover_stale_dispatches(max_age_minutes=STALE_DISPATCH_MAX_AGE)  # type: ignore[misc]
-        results["recovered"] = recovered
-        if recovered:
-            log(f"Recovered {recovered} stale dispatch(es)")
-    except Exception as e:
-        logger.warning(f"Failed to recover stale dispatches: {e}")
-        log(f"WARNING: Failed to recover stale dispatches: {e}")
-        results["errors"].append(f"Stale recovery: {e}")
-
-    # Get due tasks
-    try:
-        due_tasks = get_due_tasks()  # type: ignore[misc]
-    except Exception as e:
-        logger.error(f"Failed to load due tasks: {e}")
-        log(f"ERROR: Failed to load due tasks: {e}")
-        results["errors"].append(f"Load tasks: {e}")
-        return results
-
-    results["due"] = len(due_tasks)
-
-    if not due_tasks:
-        log("No tasks due at this time.")
-        return results
-
-    log(f"Found {len(due_tasks)} due task(s)")
-
-    # Process each due task
-    for task in due_tasks:
-        _process_single_task(task, results)
-        # Small delay between dispatches (prevents thundering herd)
-        time.sleep(1.0)
-
-    return results
-
-
-def _process_single_task(task: dict, results: dict) -> None:
-    """Process a single due task: mark dispatching, send email, update results."""
-    task_id = task.get("id", "")
-    recipient = task.get("recipient", "")
-    task_desc = task.get("task", "")
-    message = task.get("message", "")
-
-    log(f"Processing: {task_id[:8]} -> {recipient}: {task_desc[:50]}")
-
-    # Mark as dispatching (prevents re-dispatch)
-    try:
-        mark_dispatching(task_id)  # type: ignore[misc]
-    except Exception as e:
-        logger.warning(f"Failed to mark dispatching {task_id[:8]}: {e}")
-        log(f"WARNING: Failed to mark dispatching {task_id[:8]}: {e}")
-        results["errors"].append(f"Mark dispatching {task_id[:8]}: {e}")
-        results["failed"] += 1
-        return
-
-    # Build email body
-    email_body = f"{task_desc}"
-    if message:
-        email_body += f"\n\nDetails:\n{message}"
-
-    # Send the email
-    if not AI_MAIL_AVAILABLE:
-        log(f"SKIP: ai_mail not available, cannot send to {recipient}")
-        mark_pending(task_id)  # type: ignore[misc]
-        results["failed"] += 1
-        results["errors"].append(f"ai_mail unavailable for {task_id[:8]}")
-        return
-
-    try:
-        email_sent = send_email_direct(
-            to_branch=recipient,
-            subject=f"[SCHEDULED] {task_desc}",
-            message=email_body,
-            from_branch="@daemon",
-            auto_execute=True,
-            reply_to="@devpulse",
-        )
-
-        if email_sent:
-            mark_completed(task_id)  # type: ignore[misc]
-            log(f"OK: Sent to {recipient}: {task_desc[:40]}")
-            results["success"] += 1
-        else:
-            mark_pending(task_id)  # type: ignore[misc]
-            log(f"FAIL: Email returned False for {recipient}: {task_desc[:40]}")
-            results["failed"] += 1
-            results["errors"].append(f"Email failed: {task_id[:8]} -> {recipient}")
-
-    except Exception as e:
-        # Reset to pending for retry on next run
-        try:
-            mark_pending(task_id)  # type: ignore[misc]
-        except Exception as reset_err:
-            logger.warning(f"Best-effort reset to pending failed for {task_id[:8]}: {reset_err}")
-        logger.error(f"Exception sending to {recipient}: {e}")
-        log(f"ERROR: Exception sending to {recipient}: {e}")
-        results["failed"] += 1
-        results["errors"].append(f"Email error {task_id[:8]}: {e}")
-
-
-def _next_cron_run() -> str:
-    """Calculate approximate next scheduler cron run time."""
-    now = datetime.now()
-    if now.minute < 30:
-        next_min = 30
-        next_hour = now.hour
-    else:
-        next_min = 0
-        next_hour = (now.hour + 1) % 24
-    return f"{next_hour:02d}:{next_min:02d}"
-
-
-# =============================================
-# MAIN
-# =============================================
-
-
-def main() -> int:
-    """
-    Main cron entry point.
-
-    Returns:
-        0 on success, 1 on error
-    """
-    args = sys.argv[1:]
-
-    if not args:
-        print_introspection()
-        return 0
-
-    if args[0] in ["--version", "-V"]:
-        console.print("scheduler_cron v2.0.0")
-        return 0
-
-    if args[0] in ["--help", "-h"]:
-        print_help()
-        sys.exit(0)
-
-    json_handler.log_operation("cron_run")
-    log("=" * 60)
-    log("Scheduler cron triggered")
-
-    # Ensure lock directory exists
-    LOCK_FILE.parent.mkdir(parents=True, exist_ok=True)
-
-    # Acquire single-instance lock (non-blocking, stdlib fcntl)
-    if fcntl is None:
-        log("fcntl not available (non-Unix platform), skipping lock.")
-        return _run_locked()
-
-    lock_fd = open(LOCK_FILE, "w", encoding="utf-8")  # noqa: SIM115
-    try:
-        fcntl.flock(lock_fd, fcntl.LOCK_EX | fcntl.LOCK_NB)
-    except OSError as e:
-        logger.warning(f"Scheduler lock acquisition failed (another instance running): {e}")
-        log("Another instance already running, skipping.")
-        lock_fd.close()
-        return 0
-
-    try:
-        return _run_locked()
-    finally:
-        fcntl.flock(lock_fd, fcntl.LOCK_UN)
-        lock_fd.close()
-
-
-def _run_locked() -> int:
-    """Execute the cron job while holding the lock."""
-    exit_code = 0
-
-    # Step 1: Process due tasks
-    try:
-        results = process_due_tasks()
-    except Exception as e:
-        logger.error(f"Unhandled error in process_due_tasks: {e}", exc_info=True)
-        log(f"CRITICAL: Unhandled error in process_due_tasks: {e}")
-        return 1
-
-    # Step 2: Run decentralized .daemon/ scheduler tick
-    tick_results = {"fired": 0, "failed": 0}
-    try:
-        tick_results = run_tick()
-    except Exception as e:
-        logger.warning(f"Unhandled error in run_tick: {e}")
-        log(f"WARNING: Unhandled error in scheduler tick: {e}")
-
-    # Step 3: Build summary
-    lines = []
-
-    # Tasks section
-    if results["recovered"]:
-        lines.append(f"Recovered {results['recovered']} stale dispatch(es)")
-    if results["due"] or results["success"]:
-        task_line = f"Tasks: {results['due']} due | {results['success']} sent"
-        if results["failed"]:
-            task_line += f" | {results['failed']} failed"
-        lines.append(task_line)
-    else:
-        lines.append("Tasks: none due")
-
-    # Scheduler tick section
-    if tick_results.get("fired") or tick_results.get("failed"):
-        lines.append(f"Scheduler: {tick_results.get('fired', 0)} fired, {tick_results.get('failed', 0)} failed")
-    else:
-        lines.append(f"Scheduler: {tick_results.get('discovered', 0)} discovered, none due")
-
-    # Next run
-    lines.append(f"Next: ~{_next_cron_run()}")
-
-    summary = "\n".join(lines)
-
-    log(f"Results: {summary}")
-
-    # Step 4: Determine exit code
-    if results["failed"] > 0 or results["errors"] or tick_results.get("failed", 0) > 0:
-        exit_code = 1
-
-    log("Scheduler cron finished")
-    if exit_code == 0:
-        logger.info("[DAEMON] scheduler_cron: Cron cycle completed successfully")
-    log("=" * 60)
-    return exit_code
-
-
-if __name__ == "__main__":
-    try:
-        sys.exit(main())
-    except Exception as e:
-        # Last-resort catch -- never crash silently
-        logger.error(f"FATAL scheduler_cron exception: {e}", exc_info=True)
-        timestamp = datetime.now().strftime("%Y-%m-%d %H:%M:%S")
-        console.print(f"[{timestamp}] FATAL: Unhandled exception: {e}")
-        sys.exit(1)
diff --git a/src/aipass/daemon/daemon-tick.service b/src/aipass/daemon/daemon-tick.service
new file mode 100644
index 00000000..ded38baf
--- /dev/null
+++ b/src/aipass/daemon/daemon-tick.service
@@ -0,0 +1,22 @@
+# Systemd user service for the daemon scheduler tick (oneshot).
+#
+# Install:
+#   cp daemon-tick.service daemon-tick.timer ~/.config/systemd/user/
+#   systemctl --user daemon-reload
+#   systemctl --user enable --now daemon-tick.timer
+#
+# Usage:
+#   systemctl --user start daemon-tick      # manual single tick
+#   systemctl --user list-timers            # check timer schedule
+#   systemctl --user status daemon-tick     # last tick result
+#   journalctl --user -u daemon-tick        # journal entries
+
+[Unit]
+Description=AIPass Daemon Scheduler Tick — discover and fire due .daemon/ jobs
+
+[Service]
+Type=oneshot
+ExecStart=%h/Projects/AIPass/.venv/bin/python3 -m aipass.daemon.apps.daemon run
+WorkingDirectory=%h/Projects/AIPass
+StandardOutput=append:%h/.aipass/daemon-tick.log
+StandardError=append:%h/.aipass/daemon-tick.log
diff --git a/src/aipass/daemon/daemon-tick.timer b/src/aipass/daemon/daemon-tick.timer
new file mode 100644
index 00000000..30aad404
--- /dev/null
+++ b/src/aipass/daemon/daemon-tick.timer
@@ -0,0 +1,20 @@
+# Systemd user timer for the daemon scheduler tick (~2 min cadence).
+#
+# Install:
+#   cp daemon-tick.service daemon-tick.timer ~/.config/systemd/user/
+#   systemctl --user daemon-reload
+#   systemctl --user enable --now daemon-tick.timer
+#
+# Disable:
+#   systemctl --user disable --now daemon-tick.timer
+
+[Unit]
+Description=AIPass Daemon Scheduler Timer — fires daemon-tick.service every ~2 min
+
+[Timer]
+OnActiveSec=30s
+OnUnitActiveSec=2min
+Persistent=true
+
+[Install]
+WantedBy=timers.target
diff --git a/src/aipass/daemon/tests/test_actions_module.py b/src/aipass/daemon/tests/test_actions_module.py
deleted file mode 100644
index 7451f5c3..00000000
--- a/src/aipass/daemon/tests/test_actions_module.py
+++ /dev/null
@@ -1,456 +0,0 @@
-# =================== AIPass ====================
-# Name: test_actions_module.py
-# Description: Tests for the actions CLI module
-# Version: 1.0.0
-# Created: 2026-04-02
-# Modified: 2026-04-02
-# =============================================
-
-"""Tests for the actions CLI module (apps/modules/actions.py)."""
-
-from datetime import datetime, timedelta
-from unittest.mock import patch
-
-MODULE = "aipass.daemon.apps.modules.actions"
-
-
-# =============================================
-# FIXTURES
-# =============================================
-
-
-def _make_action(
-    action_id: str = "0001",
-    name: str = "test_action",
-    enabled: bool = True,
-    schedule_type: str = "daily",
-    time: str = "08:00",
-    action_type: str = "schedule",
-    target_branch: str = "@seedgo",
-    interval_minutes: int | None = None,
-    due_date: str | None = None,
-    prompt: str = "Run tests",
-) -> dict:
-    """Build a sample action dict for tests."""
-    action: dict = {
-        "id": action_id,
-        "name": name,
-        "enabled": enabled,
-        "schedule_type": schedule_type,
-        "time": time,
-        "type": action_type,
-        "target_branch": target_branch,
-        "prompt": prompt,
-        "created": "2026-03-01T00:00:00",
-        "last_run": None,
-    }
-    if interval_minutes is not None:
-        action["interval_minutes"] = interval_minutes
-    if due_date is not None:
-        action["due_date"] = due_date
-    return action
-
-
-# =============================================
-# handle_command — routing
-# =============================================
-
-
-@patch(f"{MODULE}.json_handler")
-@patch(f"{MODULE}.console")
-@patch(f"{MODULE}.cli_error")
-class TestHandleCommand:
-    """Tests for handle_command routing."""
-
-    def test_wrong_command_returns_false(self, _err, _con, _jh):
-        from aipass.daemon.apps.modules.actions import handle_command
-
-        assert handle_command("not_actions", []) is False
-
-    def test_no_args_shows_introspection(self, _err, mock_console, _jh):
-        from aipass.daemon.apps.modules.actions import handle_command
-
-        result = handle_command("actions", [])
-        assert result is True
-        # introspection prints "actions Module"
-        calls = [str(c) for c in mock_console.print.call_args_list]
-        assert any("actions Module" in c for c in calls)
-
-    def test_help_flag(self, _err, mock_console, _jh):
-        from aipass.daemon.apps.modules.actions import handle_command
-
-        assert handle_command("actions", ["--help"]) is True
-        calls = [str(c) for c in mock_console.print.call_args_list]
-        assert any("USAGE" in c for c in calls)
-
-    def test_help_word(self, _err, mock_console, _jh):
-        from aipass.daemon.apps.modules.actions import handle_command
-
-        assert handle_command("actions", ["help"]) is True
-
-    @patch(f"{MODULE}.list_actions", return_value=[])
-    @patch(f"{MODULE}.next_due_str", return_value="--")
-    def test_list_subcommand(self, _nds, _la, _err, mock_console, mock_jh):
-        from aipass.daemon.apps.modules.actions import handle_command
-
-        assert handle_command("actions", ["list"]) is True
-        mock_jh.log_operation.assert_called_once()
-
-    @patch(f"{MODULE}.migrate_plugins", return_value=2)
-    @patch(f"{MODULE}.list_actions", return_value=[])
-    @patch(f"{MODULE}.next_due_str", return_value="--")
-    def test_migrate_subcommand(self, _nds, _la, mock_migrate, _err, _con, mock_jh):
-        from aipass.daemon.apps.modules.actions import handle_command
-
-        assert handle_command("actions", ["migrate"]) is True
-        mock_migrate.assert_called_once()
-
-    @patch(f"{MODULE}.get_action")
-    @patch(f"{MODULE}.delete_action")
-    def test_delete_with_valid_id(self, mock_del, mock_get, _err, _con, _jh):
-        from aipass.daemon.apps.modules.actions import handle_command
-
-        mock_get.return_value = _make_action()
-        assert handle_command("actions", ["delete", "0001"]) is True
-        mock_del.assert_called_once_with("0001")
-
-    def test_delete_missing_id(self, mock_err, _con, _jh):
-        from aipass.daemon.apps.modules.actions import handle_command
-
-        assert handle_command("actions", ["delete"]) is True
-        mock_err.assert_called()
-
-    @patch(f"{MODULE}.create_action")
-    @patch(f"{MODULE}._parse_date", return_value="2026-04-09")
-    def test_set_reminder_valid(self, _pd, mock_create, _err, _con, _jh):
-        from aipass.daemon.apps.modules.actions import handle_command
-
-        mock_create.return_value = _make_action(action_id="0099")
-        assert handle_command("actions", ["set", "reminder", "7d", "Check PR"]) is True
-        mock_create.assert_called_once()
-
-    @patch(f"{MODULE}.create_action")
-    @patch(f"{MODULE}._parse_date", return_value="2026-04-09")
-    def test_set_schedule_valid(self, _pd, mock_create, _err, _con, _jh):
-        from aipass.daemon.apps.modules.actions import handle_command
-
-        mock_create.return_value = _make_action(action_id="0088")
-        assert handle_command("actions", ["set", "schedule", "@seedgo", "Run audit", "daily", "04:00"]) is True
-        mock_create.assert_called_once()
-
-    @patch(f"{MODULE}.get_action")
-    @patch(f"{MODULE}.next_due_str", return_value="--")
-    def test_action_id_routes(self, _nds, mock_get, _err, _con, _jh):
-        from aipass.daemon.apps.modules.actions import handle_command
-
-        mock_get.return_value = _make_action(action_id="0003")
-        assert handle_command("actions", ["0003", "info"]) is True
-        mock_get.assert_called_with("0003")
-
-    def test_unknown_subcommand(self, mock_err, mock_console, _jh):
-        from aipass.daemon.apps.modules.actions import handle_command
-
-        assert handle_command("actions", ["foobar"]) is True
-        mock_err.assert_called()
-
-
-# =============================================
-# _handle_toggle
-# =============================================
-
-
-@patch(f"{MODULE}.console")
-@patch(f"{MODULE}.cli_error")
-class TestHandleToggle:
-    @patch(f"{MODULE}.toggle_action")
-    @patch(f"{MODULE}.get_action")
-    def test_enable_success(self, mock_get, mock_toggle, _err, _con):
-        from aipass.daemon.apps.modules.actions import _handle_toggle
-
-        mock_get.return_value = _make_action()
-        assert _handle_toggle("0001", True) is True
-        mock_toggle.assert_called_once_with("0001", True)
-
-    @patch(f"{MODULE}.toggle_action")
-    @patch(f"{MODULE}.get_action")
-    def test_disable_success(self, mock_get, mock_toggle, _err, _con):
-        from aipass.daemon.apps.modules.actions import _handle_toggle
-
-        mock_get.return_value = _make_action()
-        assert _handle_toggle("0001", False) is True
-        mock_toggle.assert_called_once_with("0001", False)
-
-    @patch(f"{MODULE}.get_action", return_value=None)
-    def test_not_found(self, _get, mock_err, _con):
-        from aipass.daemon.apps.modules.actions import _handle_toggle
-
-        assert _handle_toggle("9999", True) is True
-        mock_err.assert_called()
-
-
-# =============================================
-# _handle_info
-# =============================================
-
-
-@patch(f"{MODULE}.console")
-@patch(f"{MODULE}.cli_error")
-class TestHandleInfo:
-    @patch(f"{MODULE}.next_due_str", return_value="--")
-    @patch(f"{MODULE}.get_action")
-    def test_info_success(self, mock_get, _nds, _err, mock_console):
-        from aipass.daemon.apps.modules.actions import _handle_info
-
-        mock_get.return_value = _make_action()
-        assert _handle_info("0001") is True
-        # Should print detail header containing the action name
-        calls = [str(c) for c in mock_console.print.call_args_list]
-        assert any("test_action" in c for c in calls)
-
-    @patch(f"{MODULE}.get_action", return_value=None)
-    def test_info_not_found(self, _get, mock_err, _con):
-        from aipass.daemon.apps.modules.actions import _handle_info
-
-        assert _handle_info("9999") is True
-        mock_err.assert_called()
-
-
-# =============================================
-# _handle_set_reminder
-# =============================================
-
-
-@patch(f"{MODULE}.console")
-@patch(f"{MODULE}.cli_error")
-class TestHandleSetReminder:
-    def test_missing_args(self, mock_err, _con):
-        from aipass.daemon.apps.modules.actions import _handle_set_reminder
-
-        assert _handle_set_reminder(["7d"]) is True
-        mock_err.assert_called()
-
-    @patch(f"{MODULE}.create_action")
-    @patch(f"{MODULE}._parse_date", return_value="2026-04-09")
-    def test_with_to_flag(self, _pd, mock_create, _err, _con):
-        from aipass.daemon.apps.modules.actions import _handle_set_reminder
-
-        mock_create.return_value = _make_action(action_id="0050")
-        assert _handle_set_reminder(["7d", "Follow up", "--to", "@flow"]) is True
-        call_kwargs = mock_create.call_args[1]
-        assert call_kwargs["target_branch"] == "@flow"
-
-    @patch(f"{MODULE}._parse_date", return_value="")
-    def test_invalid_date(self, _pd, mock_err, _con):
-        from aipass.daemon.apps.modules.actions import _handle_set_reminder
-
-        assert _handle_set_reminder(["xyz", "Some msg"]) is True
-        mock_err.assert_called()
-
-
-# =============================================
-# _handle_set_schedule
-# =============================================
-
-
-@patch(f"{MODULE}.console")
-@patch(f"{MODULE}.cli_error")
-@patch(f"{MODULE}.logger")
-class TestHandleSetSchedule:
-    def test_invalid_type(self, _log, mock_err, _con):
-        from aipass.daemon.apps.modules.actions import _handle_set_schedule
-
-        assert _handle_set_schedule(["@branch", "prompt", "weekly"]) is True
-        mock_err.assert_called()
-
-    def test_missing_time_arg(self, _log, mock_err, _con):
-        from aipass.daemon.apps.modules.actions import _handle_set_schedule
-
-        assert _handle_set_schedule(["@branch", "prompt", "daily"]) is True
-        mock_err.assert_called()
-
-    def test_interval_non_numeric(self, _log, mock_err, _con):
-        from aipass.daemon.apps.modules.actions import _handle_set_schedule
-
-        assert _handle_set_schedule(["@b", "prompt", "interval", "abc"]) is True
-        mock_err.assert_called()
-
-    @patch(f"{MODULE}.create_action")
-    def test_daily_success(self, mock_create, _log, _err, _con):
-        from aipass.daemon.apps.modules.actions import _handle_set_schedule
-
-        mock_create.return_value = _make_action(action_id="0070")
-        assert _handle_set_schedule(["@seedgo", "Run audit", "daily", "04:00"]) is True
-        kw = mock_create.call_args[1]
-        assert kw["schedule_type"] == "daily"
-        assert kw["time"] == "04:00"
-
-    @patch(f"{MODULE}.create_action")
-    def test_hourly_success(self, mock_create, _log, _err, _con):
-        from aipass.daemon.apps.modules.actions import _handle_set_schedule
-
-        mock_create.return_value = _make_action(action_id="0071")
-        assert _handle_set_schedule(["@flow", "Check plans", "hourly", "30"]) is True
-        kw = mock_create.call_args[1]
-        assert kw["schedule_type"] == "hourly"
-
-    @patch(f"{MODULE}.create_action")
-    def test_interval_success(self, mock_create, _log, _err, _con):
-        from aipass.daemon.apps.modules.actions import _handle_set_schedule
-
-        mock_create.return_value = _make_action(action_id="0072")
-        assert _handle_set_schedule(["@daemon", "Heartbeat", "interval", "240"]) is True
-        kw = mock_create.call_args[1]
-        assert kw["interval_minutes"] == 240
-
-
-# =============================================
-# _handle_delete
-# =============================================
-
-
-@patch(f"{MODULE}.console")
-@patch(f"{MODULE}.cli_error")
-class TestHandleDelete:
-    def test_no_args(self, mock_err, _con):
-        from aipass.daemon.apps.modules.actions import _handle_delete
-
-        assert _handle_delete([]) is True
-        mock_err.assert_called()
-
-    @patch(f"{MODULE}.get_action", return_value=None)
-    def test_not_found(self, _get, mock_err, _con):
-        from aipass.daemon.apps.modules.actions import _handle_delete
-
-        assert _handle_delete(["9999"]) is True
-        mock_err.assert_called()
-
-    @patch(f"{MODULE}.delete_action")
-    @patch(f"{MODULE}.get_action")
-    def test_success(self, mock_get, mock_del, _err, _con):
-        from aipass.daemon.apps.modules.actions import _handle_delete
-
-        mock_get.return_value = _make_action(action_id="0005")
-        assert _handle_delete(["0005"]) is True
-        mock_del.assert_called_once_with("0005")
-
-
-# =============================================
-# _parse_date
-# =============================================
-
-
-@patch(f"{MODULE}.logger")
-class TestParseDate:
-    def test_relative_days(self, _log):
-        from aipass.daemon.apps.modules.actions import _parse_date
-
-        result = _parse_date("7d")
-        expected = (datetime.now() + timedelta(days=7)).strftime("%Y-%m-%d")
-        assert result == expected
-
-    def test_relative_weeks(self, _log):
-        from aipass.daemon.apps.modules.actions import _parse_date
-
-        result = _parse_date("2w")
-        expected = (datetime.now() + timedelta(weeks=2)).strftime("%Y-%m-%d")
-        assert result == expected
-
-    def test_iso_format(self, _log):
-        from aipass.daemon.apps.modules.actions import _parse_date
-
-        assert _parse_date("2026-04-15") == "2026-04-15"
-
-    def test_invalid_format(self, _log):
-        from aipass.daemon.apps.modules.actions import _parse_date
-
-        assert _parse_date("not-a-date") == ""
-
-    def test_invalid_relative_day(self, _log):
-        from aipass.daemon.apps.modules.actions import _parse_date
-
-        assert _parse_date("xd") == ""
-
-    def test_invalid_relative_week(self, _log):
-        from aipass.daemon.apps.modules.actions import _parse_date
-
-        assert _parse_date("xw") == ""
-
-
-# =============================================
-# _format_schedule
-# =============================================
-
-
-class TestFormatSchedule:
-    def test_daily(self):
-        from aipass.daemon.apps.modules.actions import _format_schedule
-
-        assert _format_schedule({"schedule_type": "daily", "time": "08:00"}) == "daily @ 08:00"
-
-    def test_hourly(self):
-        from aipass.daemon.apps.modules.actions import _format_schedule
-
-        assert _format_schedule({"schedule_type": "hourly", "time": "30"}) == "hourly @ :30"
-
-    def test_interval_minutes(self):
-        from aipass.daemon.apps.modules.actions import _format_schedule
-
-        assert _format_schedule({"schedule_type": "interval", "interval_minutes": 45}) == "every 45m"
-
-    def test_interval_hours(self):
-        from aipass.daemon.apps.modules.actions import _format_schedule
-
-        assert _format_schedule({"schedule_type": "interval", "interval_minutes": 120}) == "every 2h"
-
-    def test_once(self):
-        from aipass.daemon.apps.modules.actions import _format_schedule
-
-        assert _format_schedule({"schedule_type": "once", "due_date": "2026-04-10"}) == "once: 2026-04-10"
-
-    def test_unknown_type(self):
-        from aipass.daemon.apps.modules.actions import _format_schedule
-
-        assert _format_schedule({"schedule_type": "custom"}) == "custom"
-
-
-# =============================================
-# _route_set_subcommand / _route_action_id
-# =============================================
-
-
-@patch(f"{MODULE}.console")
-@patch(f"{MODULE}.cli_error")
-class TestRouting:
-    def test_route_set_too_few_args(self, mock_err, _con):
-        from aipass.daemon.apps.modules.actions import _route_set_subcommand
-
-        assert _route_set_subcommand(["set"]) is True
-        mock_err.assert_called()
-
-    def test_route_set_unknown_type(self, mock_err, _con):
-        from aipass.daemon.apps.modules.actions import _route_set_subcommand
-
-        assert _route_set_subcommand(["set", "bogus"]) is True
-        mock_err.assert_called()
-
-    @patch(f"{MODULE}.get_action", return_value=None)
-    def test_route_action_id_no_sub_defaults_to_info(self, mock_get, mock_err, _con):
-        from aipass.daemon.apps.modules.actions import _route_action_id
-
-        assert _route_action_id("0001", ["0001"]) is True
-        mock_get.assert_called_with("0001")
-
-    @patch(f"{MODULE}.get_action")
-    @patch(f"{MODULE}.toggle_action")
-    def test_route_action_id_on(self, mock_toggle, mock_get, _err, _con):
-        from aipass.daemon.apps.modules.actions import _route_action_id
-
-        mock_get.return_value = _make_action()
-        assert _route_action_id("0001", ["0001", "on"]) is True
-        mock_toggle.assert_called_once_with("0001", True)
-
-    def test_route_action_id_unknown_sub(self, mock_err, _con):
-        from aipass.daemon.apps.modules.actions import _route_action_id
-
-        assert _route_action_id("0001", ["0001", "banana"]) is True
-        mock_err.assert_called()
diff --git a/src/aipass/daemon/tests/test_actions_registry.py b/src/aipass/daemon/tests/test_actions_registry.py
deleted file mode 100644
index 221ff6d1..00000000
--- a/src/aipass/daemon/tests/test_actions_registry.py
+++ /dev/null
@@ -1,360 +0,0 @@
-# ===================AIPASS====================
-# META DATA HEADER
-# Name: test_actions_registry.py - Action Registry Tests
-# Date: 2026-03-02
-# Version: 1.1.0
-# Category: daemon/tests
-#
-# CHANGELOG (Max 5 entries):
-#   - v1.1.0 (2026-03-07): Adapted for AIPass public repo
-#     * Removed sys.path manipulation, uses package imports
-#   - v1.0.0 (2026-03-02): Initial creation - DPLAN-043 tests
-#
-# CODE STANDARDS:
-#   - Pytest conventions
-#   - Temp dir isolation (no writes to real registry)
-# =============================================
-
-"""Tests for the action registry handler."""
-
-import json
-from datetime import datetime, timedelta
-
-import pytest
-
-from aipass.daemon.apps.handlers.actions import actions_registry as _reg_mod
-
-create_action = _reg_mod.create_action
-get_action = _reg_mod.get_action
-list_actions = _reg_mod.list_actions
-toggle_action = _reg_mod.toggle_action
-delete_action = _reg_mod.delete_action
-update_last_run = _reg_mod.update_last_run
-mark_reminder_completed = _reg_mod.mark_reminder_completed
-is_action_due = _reg_mod.is_action_due
-calc_next_run = _reg_mod.calc_next_run
-next_due_str = _reg_mod.next_due_str
-
-
-@pytest.fixture(autouse=True)
-def clean_registry(tmp_path):
-    """Isolate REGISTRY_FILE to a temp dir for every test."""
-    test_registry = tmp_path / "actions_registry.json"
-    original = _reg_mod.REGISTRY_FILE
-    _reg_mod.REGISTRY_FILE = test_registry
-    yield test_registry
-    _reg_mod.REGISTRY_FILE = original
-
-
-# =============================================
-# CRUD TESTS
-# =============================================
-
-
-class TestCreate:
-    def test_create_action_basic(self, clean_registry):
-        """Create a simple schedule action and verify fields."""
-        action = create_action(
-            name="test_audit",
-            action_type="schedule",
-            schedule_type="daily",
-            target_branch="@seedgo",
-            prompt="Run audit",
-            time="04:00",
-            fresh=True,
-            max_turns=20,
-        )
-        assert action["id"] == "0001"
-        assert action["name"] == "test_audit"
-        assert action["type"] == "schedule"
-        assert action["schedule_type"] == "daily"
-        assert action["time"] == "04:00"
-        assert action["target_branch"] == "@seedgo"
-        assert action["enabled"] is True
-        assert action["last_run"] is None
-        assert action["completed"] is None
-
-    def test_create_sequential_ids(self, clean_registry):
-        """IDs should be sequential: 0001, 0002, 0003..."""
-        a1 = create_action(name="first", action_type="schedule", schedule_type="daily")
-        a2 = create_action(name="second", action_type="schedule", schedule_type="daily")
-        a3 = create_action(name="third", action_type="reminder", schedule_type="once")
-        assert a1["id"] == "0001"
-        assert a2["id"] == "0002"
-        assert a3["id"] == "0003"
-
-    def test_create_reminder(self, clean_registry):
-        """Create a one-shot reminder action."""
-        action = create_action(
-            name="Check VERA progress",
-            action_type="reminder",
-            schedule_type="once",
-            target_branch="@devpulse",
-            prompt="Check VERA progress",
-            due_date="2026-03-11",
-        )
-        assert action["type"] == "reminder"
-        assert action["schedule_type"] == "once"
-        assert action["due_date"] == "2026-03-11"
-
-    def test_create_persists_to_json(self, clean_registry):
-        """Action should be persisted to the JSON file."""
-        create_action(name="persisted", action_type="schedule", schedule_type="daily")
-        data = json.loads(clean_registry.read_text())
-        assert len(data["actions"]) == 1
-        assert data["actions"][0]["name"] == "persisted"
-        assert data["next_id"] == 2
-
-
-class TestGet:
-    def test_get_existing(self, clean_registry):
-        """Get an action by ID."""
-        create_action(name="findme", action_type="schedule", schedule_type="daily")
-        action = get_action("0001")
-        assert action is not None
-        assert action["name"] == "findme"
-
-    def test_get_missing(self, clean_registry):
-        """Get returns None for nonexistent ID."""
-        assert get_action("9999") is None
-
-
-class TestList:
-    def test_list_all(self, clean_registry):
-        """List returns all non-completed actions."""
-        create_action(name="a", action_type="schedule", schedule_type="daily")
-        create_action(name="b", action_type="schedule", schedule_type="hourly")
-        actions = list_actions()
-        assert len(actions) == 2
-
-    def test_list_excludes_completed(self, clean_registry):
-        """Completed reminders should be excluded by default."""
-        create_action(name="done", action_type="reminder", schedule_type="once", due_date="2026-01-01")
-        mark_reminder_completed("0001")
-        assert len(list_actions()) == 0
-        assert len(list_actions(include_completed=True)) == 1
-
-
-class TestToggle:
-    def test_toggle_off(self, clean_registry):
-        """Toggle an action off."""
-        create_action(name="toggleme", action_type="schedule", schedule_type="daily")
-        assert toggle_action("0001", False) is True
-        action = get_action("0001")
-        assert action is not None
-        assert action["enabled"] is False
-
-    def test_toggle_on(self, clean_registry):
-        """Toggle an action back on."""
-        create_action(name="toggleme", action_type="schedule", schedule_type="daily", enabled=False)
-        assert toggle_action("0001", True) is True
-        action = get_action("0001")
-        assert action is not None
-        assert action["enabled"] is True
-
-    def test_toggle_missing(self, clean_registry):
-        """Toggle returns False for nonexistent ID."""
-        assert toggle_action("9999", True) is False
-
-
-class TestDelete:
-    def test_delete_existing(self, clean_registry):
-        """Delete an action by ID."""
-        create_action(name="deleteme", action_type="schedule", schedule_type="daily")
-        assert delete_action("0001") is True
-        assert get_action("0001") is None
-
-    def test_delete_missing(self, clean_registry):
-        """Delete returns False for nonexistent ID."""
-        assert delete_action("9999") is False
-
-
-# =============================================
-# DUE CHECKING TESTS
-# =============================================
-
-
-class TestIsDue:
-    def test_daily_due_at_correct_time(self, clean_registry):
-        """Daily action is due when current time matches."""
-        now = datetime.now()
-        action = {
-            "enabled": True,
-            "completed": None,
-            "schedule_type": "daily",
-            "time": f"{now.hour:02d}:{now.minute:02d}",
-            "last_run": None,
-        }
-        assert is_action_due(action) is True
-
-    def test_daily_not_due_wrong_time(self, clean_registry):
-        """Daily action is not due at wrong time (12 hours away from now)."""
-        from datetime import datetime
-
-        now = datetime.now()
-        # Pick a time 12 hours away — always outside the 15-min fuzzy window
-        far_hour = (now.hour + 12) % 24
-        action = {
-            "enabled": True,
-            "completed": None,
-            "schedule_type": "daily",
-            "time": f"{far_hour:02d}:00",
-            "last_run": None,
-        }
-        assert is_action_due(action) is False
-
-    def test_daily_not_due_already_ran_today(self, clean_registry):
-        """Daily action not due if already ran today."""
-        now = datetime.now()
-        action = {
-            "enabled": True,
-            "completed": None,
-            "schedule_type": "daily",
-            "time": f"{now.hour:02d}:{now.minute:02d}",
-            "last_run": now.isoformat(),
-        }
-        assert is_action_due(action) is False
-
-    def test_interval_due_never_run(self, clean_registry):
-        """Interval action is due if never run before."""
-        action = {
-            "enabled": True,
-            "completed": None,
-            "schedule_type": "interval",
-            "interval_minutes": 60,
-            "last_run": None,
-        }
-        assert is_action_due(action) is True
-
-    def test_interval_due_enough_time_elapsed(self, clean_registry):
-        """Interval action is due when enough time has passed."""
-        past = (datetime.now() - timedelta(minutes=120)).isoformat()
-        action = {
-            "enabled": True,
-            "completed": None,
-            "schedule_type": "interval",
-            "interval_minutes": 60,
-            "last_run": past,
-        }
-        assert is_action_due(action) is True
-
-    def test_interval_not_due_too_soon(self, clean_registry):
-        """Interval action is not due when too little time has passed."""
-        recent = (datetime.now() - timedelta(minutes=5)).isoformat()
-        action = {
-            "enabled": True,
-            "completed": None,
-            "schedule_type": "interval",
-            "interval_minutes": 60,
-            "last_run": recent,
-        }
-        assert is_action_due(action) is False
-
-    def test_once_due_past_date(self, clean_registry):
-        """Reminder is due when due_date is in the past."""
-        action = {
-            "enabled": True,
-            "completed": None,
-            "schedule_type": "once",
-            "due_date": "2026-01-01",
-        }
-        assert is_action_due(action) is True
-
-    def test_once_not_due_future_date(self, clean_registry):
-        """Reminder is not due when due_date is in the future."""
-        action = {
-            "enabled": True,
-            "completed": None,
-            "schedule_type": "once",
-            "due_date": "2099-12-31",
-        }
-        assert is_action_due(action) is False
-
-    def test_disabled_never_due(self, clean_registry):
-        """Disabled action is never due."""
-        action = {
-            "enabled": False,
-            "completed": None,
-            "schedule_type": "interval",
-            "interval_minutes": 1,
-            "last_run": None,
-        }
-        assert is_action_due(action) is False
-
-    def test_completed_never_due(self, clean_registry):
-        """Completed action is never due."""
-        action = {
-            "enabled": True,
-            "completed": "2026-03-01T12:00:00",
-            "schedule_type": "once",
-            "due_date": "2026-01-01",
-        }
-        assert is_action_due(action) is False
-
-
-# =============================================
-# NEXT RUN TESTS
-# =============================================
-
-
-class TestCalcNextRun:
-    def test_daily_next_run(self, clean_registry):
-        """Daily action calculates next run correctly."""
-        action = {"schedule_type": "daily", "time": "04:00", "last_run": None}
-        result = calc_next_run(action)
-        assert result is not None
-        assert "04:00:00" in result
-
-    def test_interval_next_run(self, clean_registry):
-        """Interval action calculates next run from last_run + interval."""
-        last = datetime.now().isoformat()
-        action = {"schedule_type": "interval", "interval_minutes": 60, "last_run": last}
-        result = calc_next_run(action)
-        assert result is not None
-
-    def test_once_next_run(self, clean_registry):
-        """Reminder returns due_date as next run."""
-        action = {"schedule_type": "once", "due_date": "2026-03-11", "completed": None}
-        assert calc_next_run(action) == "2026-03-11"
-
-
-class TestNextDueStr:
-    def test_daily_str(self, clean_registry):
-        action = {"schedule_type": "daily", "time": "04:00"}
-        assert next_due_str(action) == "daily @ 04:00"
-
-    def test_hourly_str(self, clean_registry):
-        action = {"schedule_type": "hourly", "time": "30"}
-        assert next_due_str(action) == "hourly @ :30"
-
-    def test_once_str(self, clean_registry):
-        action = {"schedule_type": "once", "due_date": "2026-03-11"}
-        assert next_due_str(action) == "2026-03-11"
-
-
-# =============================================
-# UPDATE TESTS
-# =============================================
-
-
-class TestUpdateLastRun:
-    def test_update_last_run(self, clean_registry):
-        """Update last_run sets timestamp and recalculates next_run."""
-        create_action(name="test", action_type="schedule", schedule_type="interval", interval_minutes=60)
-        ts = "2026-03-02T12:00:00"
-        assert update_last_run("0001", ts) is True
-        action = get_action("0001")
-        assert action is not None
-        assert action["last_run"] == ts
-        assert action["next_run"] is not None
-
-
-class TestMarkCompleted:
-    def test_mark_reminder_completed(self, clean_registry):
-        """Marking a reminder completed sets completed timestamp and disables it."""
-        create_action(name="reminder", action_type="reminder", schedule_type="once", due_date="2026-03-01")
-        assert mark_reminder_completed("0001") is True
-        action = get_action("0001")
-        assert action is not None
-        assert action["completed"] is not None
-        assert action["enabled"] is False
diff --git a/src/aipass/daemon/tests/test_contracts.py b/src/aipass/daemon/tests/test_contracts.py
index 948267c1..f305fd62 100644
--- a/src/aipass/daemon/tests/test_contracts.py
+++ b/src/aipass/daemon/tests/test_contracts.py
@@ -265,6 +265,12 @@ def test_help_preempts() -> None:
     assert result == 0, "--help must return 0 before any module routing"
 
 
+def test_invalid_mode_raises() -> None:
+    """invalid_mode_raises: save_json with invalid_type raises ValueError."""
+    with pytest.raises(ValueError):
+        json_handler.save_json("contract_mod", "invalid_type_xyz", {"bad": True})
+
+
 def test_no_args_triggers() -> None:
     """no_args_triggers: no arguments triggers introspection display."""
     from aipass.daemon.apps import daemon as _daemon_mod
diff --git a/src/aipass/daemon/tests/test_run_module.py b/src/aipass/daemon/tests/test_run_module.py
index 99e65acb..c223d7de 100644
--- a/src/aipass/daemon/tests/test_run_module.py
+++ b/src/aipass/daemon/tests/test_run_module.py
@@ -1,3 +1,11 @@
+# =================== AIPass ====================
+# Name: test_run_module.py
+# Description: Tests for the drone @daemon run module
+# Version: 1.1.0
+# Created: 2026-06-15
+# Modified: 2026-06-25
+# =============================================
+
 """Tests for the drone @daemon run module (decentralized scheduler tick)."""
 
 from unittest.mock import patch
@@ -63,7 +71,7 @@ class TestRunTick:
         assert results["due"] == 0
 
     @patch("aipass.daemon.apps.modules.run.save_runstate")
-    @patch("aipass.daemon.apps.modules.run._fire_job", return_value=True)
+    @patch("aipass.daemon.apps.modules.run._fire_job", return_value=(True, ""))
     @patch("aipass.daemon.apps.modules.run.discover_jobs")
     @patch("aipass.daemon.apps.modules.run.load_runstate", return_value={"jobs": {}})
     def test_fires_due_job(self, mock_rs, mock_discover, mock_fire, mock_save):
@@ -84,7 +92,7 @@ class TestRunTick:
         mock_save.assert_called()
 
     @patch("aipass.daemon.apps.modules.run.save_runstate")
-    @patch("aipass.daemon.apps.modules.run._fire_job", return_value=False)
+    @patch("aipass.daemon.apps.modules.run._fire_job", return_value=(False, "wake failed"))
     @patch("aipass.daemon.apps.modules.run.discover_jobs")
     @patch("aipass.daemon.apps.modules.run.load_runstate", return_value={"jobs": {}})
     def test_failed_fire_counted(self, mock_rs, mock_discover, mock_fire, mock_save):
diff --git a/src/aipass/daemon/tests/test_schedule_module.py b/src/aipass/daemon/tests/test_schedule_module.py
deleted file mode 100644
index 3f2bf336..00000000
--- a/src/aipass/daemon/tests/test_schedule_module.py
+++ /dev/null
@@ -1,352 +0,0 @@
-# =================== AIPass ====================
-# Name: test_schedule_module.py
-# Description: Tests for the schedule CLI module
-# Version: 1.0.0
-# Created: 2026-04-03
-# Modified: 2026-04-03
-# =============================================
-
-"""Tests for the schedule CLI module (apps/modules/schedule.py)."""
-
-from unittest.mock import patch, MagicMock
-
-MODULE = "aipass.daemon.apps.modules.schedule"
-
-
-# =============================================
-# handle_command -- routing basics
-# =============================================
-
-
-@patch(f"{MODULE}.json_handler")
-@patch(f"{MODULE}.console")
-@patch(f"{MODULE}.cli_error")
-@patch(f"{MODULE}.logger")
-class TestHandleCommandRouting:
-    """Tests for handle_command routing."""
-
-    def test_wrong_command_returns_false(self, _log, _err, _con, _jh):
-        from aipass.daemon.apps.modules.schedule import handle_command
-
-        assert handle_command("not_schedule", []) is False
-
-    def test_no_args_shows_introspection(self, _log, _err, mock_con, _jh):
-        from aipass.daemon.apps.modules.schedule import handle_command
-
-        result = handle_command("schedule", [])
-        assert result is True
-        calls = [str(c) for c in mock_con.print.call_args_list]
-        assert any("schedule Module" in c for c in calls)
-
-    def test_help_flag(self, _log, _err, mock_con, _jh):
-        from aipass.daemon.apps.modules.schedule import handle_command
-
-        result = handle_command("schedule", ["--help"])
-        assert result is True
-        calls = [str(c) for c in mock_con.print.call_args_list]
-        assert any("USAGE" in c for c in calls)
-
-    def test_unknown_subcommand(self, _log, mock_err, _con, _jh):
-        from aipass.daemon.apps.modules.schedule import handle_command
-
-        result = handle_command("schedule", ["foobar"])
-        assert result is False
-        mock_err.assert_called()
-
-
-# =============================================
-# handle_command -- list subcommand
-# =============================================
-
-
-@patch(f"{MODULE}.json_handler")
-@patch(f"{MODULE}.console")
-@patch(f"{MODULE}.cli_error")
-@patch(f"{MODULE}.logger")
-class TestListSubcommand:
-    """Tests for 'schedule list' subcommand."""
-
-    @patch(f"{MODULE}.load_tasks", return_value=[])
-    def test_list_success(self, mock_load, _log, _err, mock_con, mock_jh):
-        from aipass.daemon.apps.modules.schedule import handle_command
-
-        result = handle_command("schedule", ["list"])
-        assert result is True
-        mock_load.assert_called_once()
-
-    @patch(f"{MODULE}.load_tasks", side_effect=RuntimeError("disk error"))
-    def test_list_exception(self, _load, _log, mock_err, _con, _jh):
-        from aipass.daemon.apps.modules.schedule import handle_command
-
-        result = handle_command("schedule", ["list"])
-        assert result is False
-        mock_err.assert_called()
-
-
-# =============================================
-# handle_command -- delete subcommand
-# =============================================
-
-
-@patch(f"{MODULE}.json_handler")
-@patch(f"{MODULE}.console")
-@patch(f"{MODULE}.cli_error")
-@patch(f"{MODULE}.logger")
-class TestDeleteSubcommand:
-    """Tests for 'schedule delete' subcommand."""
-
-    def test_delete_no_args_shows_error(self, _log, mock_err, _con, _jh):
-        from aipass.daemon.apps.modules.schedule import handle_command
-
-        result = handle_command("schedule", ["delete"])
-        assert result is False
-        mock_err.assert_called()
-
-    @patch(f"{MODULE}.delete_task", return_value=True)
-    def test_delete_success(self, mock_del, _log, _err, _con, _jh):
-        from aipass.daemon.apps.modules.schedule import handle_command
-
-        result = handle_command("schedule", ["delete", "abc123"])
-        assert result is True
-        mock_del.assert_called_once_with("abc123")
-
-    @patch(f"{MODULE}.delete_task", return_value=False)
-    def test_delete_not_found(self, mock_del, _log, mock_err, _con, _jh):
-        from aipass.daemon.apps.modules.schedule import handle_command
-
-        result = handle_command("schedule", ["delete", "abc123"])
-        assert result is False
-        mock_err.assert_called()
-
-
-# =============================================
-# handle_command -- run-due subcommand
-# =============================================
-
-
-@patch(f"{MODULE}.json_handler")
-@patch(f"{MODULE}.console")
-@patch(f"{MODULE}.cli_error")
-@patch(f"{MODULE}.logger")
-class TestRunDueSubcommand:
-    """Tests for 'schedule run-due' subcommand."""
-
-    @patch(
-        f"{MODULE}.process_due_tasks_batch",
-        return_value={
-            "recovered": 0,
-            "due": 0,
-            "success": 0,
-            "failed": 0,
-            "processed_tasks": [],
-        },
-    )
-    @patch(f"{MODULE}.FILELOCK_AVAILABLE", False)
-    def test_run_due_without_lock(self, mock_batch, _log, _err, mock_con, _jh):
-        from aipass.daemon.apps.modules.schedule import handle_command
-
-        result = handle_command("schedule", ["run-due"])
-        assert result is True
-        mock_batch.assert_called_once()
-
-    @patch(
-        f"{MODULE}.process_due_tasks_batch",
-        return_value={
-            "recovered": 1,
-            "due": 2,
-            "success": 1,
-            "failed": 1,
-            "processed_tasks": [
-                {"id": "a1", "recipient": "@flow", "task": "Check plan", "status": "sent"},
-                {"id": "a2", "recipient": "@seedgo", "task": "Audit", "status": "failed"},
-            ],
-        },
-    )
-    @patch(f"{MODULE}.FILELOCK_AVAILABLE", False)
-    def test_run_due_processes_tasks(self, mock_batch, _log, _err, mock_con, _jh):
-        from aipass.daemon.apps.modules.schedule import handle_command
-
-        result = handle_command("schedule", ["run-due"])
-        assert result is True
-        mock_batch.assert_called_once()
-        calls = " ".join(str(c) for c in mock_con.print.call_args_list)
-        assert "1 sent" in calls
-        assert "1 failed" in calls
-
-
-# =============================================
-# _handle_create
-# =============================================
-
-
-@patch(f"{MODULE}.console")
-@patch(f"{MODULE}.cli_error")
-@patch(f"{MODULE}.logger")
-class TestHandleCreate:
-    """Tests for _handle_create."""
-
-    @patch(f"{MODULE}.create_task", return_value={"id": "task-001"})
-    @patch(f"{MODULE}.parse_due_date", return_value="2026-04-10")
-    def test_create_valid(self, _due, mock_create, _log, _err, _con):
-        from aipass.daemon.apps.modules.schedule import _handle_create
-
-        result = _handle_create(["Follow up", "--due", "7d", "--to", "@flow"])
-        assert result is True
-        mock_create.assert_called_once()
-
-    def test_create_missing_task(self, _log, mock_err, _con):
-        from aipass.daemon.apps.modules.schedule import _handle_create
-
-        result = _handle_create(["--due", "7d", "--to", "@flow"])
-        assert result is False
-        mock_err.assert_called()
-
-    @patch(f"{MODULE}.parse_due_date", return_value=None)
-    def test_create_invalid_due(self, _due, _log, mock_err, _con):
-        from aipass.daemon.apps.modules.schedule import _handle_create
-
-        result = _handle_create(["Task text", "--due", "xyz", "--to", "@flow"])
-        assert result is False
-        mock_err.assert_called()
-
-
-# =============================================
-# _process_due_tasks
-# =============================================
-
-
-@patch(f"{MODULE}.console")
-@patch(f"{MODULE}.cli_error")
-@patch(f"{MODULE}.logger")
-class TestProcessDueTasks:
-    """Tests for _process_due_tasks."""
-
-    @patch(
-        f"{MODULE}.process_due_tasks_batch",
-        return_value={
-            "recovered": 0,
-            "due": 0,
-            "success": 0,
-            "failed": 0,
-            "processed_tasks": [],
-        },
-    )
-    def test_no_tasks_due(self, mock_batch, _log, _err, mock_con):
-        from aipass.daemon.apps.modules.schedule import _process_due_tasks
-
-        result = _process_due_tasks()
-        assert result is True
-        calls = " ".join(str(c) for c in mock_con.print.call_args_list)
-        assert "No tasks due" in calls
-
-    @patch(
-        f"{MODULE}.process_due_tasks_batch",
-        return_value={
-            "recovered": 0,
-            "due": 2,
-            "success": 1,
-            "failed": 1,
-            "processed_tasks": [
-                {"id": "t1", "recipient": "@flow", "task": "Check", "status": "sent"},
-                {"id": "t2", "recipient": "@seedgo", "task": "Audit", "status": "failed"},
-            ],
-        },
-    )
-    def test_mix_sent_failed(self, mock_batch, _log, _err, mock_con):
-        from aipass.daemon.apps.modules.schedule import _process_due_tasks
-
-        result = _process_due_tasks()
-        assert result is True
-        calls = " ".join(str(c) for c in mock_con.print.call_args_list)
-        assert "1 sent" in calls
-        assert "1 failed" in calls
-
-
-# =============================================
-# _display_task_result
-# =============================================
-
-
-@patch(f"{MODULE}.console")
-@patch(f"{MODULE}.cli_error")
-@patch(f"{MODULE}.logger")
-class TestDisplayTaskResult:
-    """Tests for _display_task_result per-status output."""
-
-    def test_status_sent(self, mock_log, _err, mock_con):
-        from aipass.daemon.apps.modules.schedule import _display_task_result
-
-        _display_task_result(
-            {
-                "id": "t1",
-                "recipient": "@flow",
-                "task": "Check plan",
-                "status": "sent",
-            }
-        )
-        calls = " ".join(str(c) for c in mock_con.print.call_args_list)
-        assert "OK" in calls or "Sent" in calls or "@flow" in calls
-
-    def test_status_skipped(self, _log, mock_err, _con):
-        from aipass.daemon.apps.modules.schedule import _display_task_result
-
-        _display_task_result(
-            {
-                "id": "t2",
-                "recipient": "@seedgo",
-                "task": "Audit",
-                "status": "skipped",
-            }
-        )
-        mock_err.assert_called()
-
-    def test_status_failed(self, _log, mock_err, _con):
-        from aipass.daemon.apps.modules.schedule import _display_task_result
-
-        _display_task_result(
-            {
-                "id": "t3",
-                "recipient": "@daemon",
-                "task": "Heartbeat",
-                "status": "failed",
-            }
-        )
-        mock_err.assert_called()
-
-    def test_status_error(self, _log, mock_err, _con):
-        from aipass.daemon.apps.modules.schedule import _display_task_result
-
-        _display_task_result(
-            {
-                "id": "t4",
-                "recipient": "@drone",
-                "task": "Ping",
-                "status": "error",
-                "error": "timeout",
-            }
-        )
-        mock_err.assert_called()
-
-
-# =============================================
-# _send_email_via_drone
-# =============================================
-
-
-@patch(f"{MODULE}.logger")
-class TestSendEmailViaDrone:
-    """Tests for _send_email_via_drone subprocess wrapper."""
-
-    @patch("subprocess.run")
-    def test_success(self, mock_run, _log):
-        from aipass.daemon.apps.modules.schedule import _send_email_via_drone
-
-        mock_run.return_value = MagicMock(returncode=0)
-        assert _send_email_via_drone("@flow", "subj", "body") is True
-        mock_run.assert_called_once()
-
-    @patch("subprocess.run", side_effect=OSError("no drone"))
-    def test_failure(self, _run, _log):
-        from aipass.daemon.apps.modules.schedule import _send_email_via_drone
-
-        assert _send_email_via_drone("@flow", "subj", "body") is False
diff --git a/src/aipass/daemon/tests/test_scheduler_bot.py b/src/aipass/daemon/tests/test_scheduler_bot.py
new file mode 100644
index 00000000..eaee3127
--- /dev/null
+++ b/src/aipass/daemon/tests/test_scheduler_bot.py
@@ -0,0 +1,351 @@
+# =================== AIPass ====================
+# Name: test_scheduler_bot.py
+# Description: Tests for TDPLAN-0008 Phase 1 — scheduler bot daemon layer
+# Version: 1.0.0
+# Created: 2026-06-25
+# Modified: 2026-06-25
+# =============================================
+
+"""Tests for TDPLAN-0008 Phase 1: status capture, queue view, lifecycle notifications, archive."""
+
+from datetime import datetime
+from pathlib import Path
+from unittest.mock import patch
+
+import pytest
+
+from aipass.daemon.apps.handlers.schedule.runstate import (
+    update_job_runstate,
+    record_job_failure,
+)
+from aipass.daemon.apps.handlers.schedule.telegram_notifier import (
+    notify_triggered,
+    notify_complete,
+    notify_error,
+)
+from aipass.daemon.apps.modules.queue import (
+    _build_queue,
+    _build_json_output,
+    _schedule_human,
+    handle_command,
+)
+
+
+# ── Fixtures ──────────────────────────────────────────
+
+
+@pytest.fixture
+def once_job():
+    """A once-type job that fires on due_date."""
+    return {
+        "owner": "@api",
+        "id": "data-check",
+        "enabled": True,
+        "schedule": {"type": "once", "due_date": datetime.now().strftime("%Y-%m-%d")},
+        "wake": {"fresh": True, "model": "haiku"},
+        "prompt": "Check the live data and report back.",
+    }
+
+
+@pytest.fixture
+def interval_job():
+    """An interval-type job."""
+    return {
+        "owner": "@commons",
+        "id": "rotation",
+        "enabled": True,
+        "schedule": {"type": "interval", "interval_minutes": 120},
+        "wake": {"fresh": True},
+        "prompt": "Rotate community content.",
+    }
+
+
+# ── Test 1: once job fires on due_date, then marks completed ───
+
+
+class TestOnceJobLifecycle:
+    """Verify once jobs fire on/after due_date and mark completed."""
+
+    def test_fires_on_due_date(self, once_job):
+        """Once job with today's due_date gets last_status=success + completed."""
+        runstate = {"jobs": {}}
+        update_job_runstate(runstate, "@api", "data-check", once_job["schedule"])
+        entry = runstate["jobs"]["@api/data-check"]
+        assert entry["last_status"] == "success"
+        assert "completed" in entry
+        assert entry["last_success_at"] is not None
+        assert entry["last_error"] is None
+
+    def test_completed_once_excluded_from_queue(self, once_job):
+        """Completed once jobs are filtered out of the queue view."""
+        runstate = {
+            "jobs": {
+                "@api/data-check": {
+                    "completed": "2026-06-25T10:00:00",
+                    "last_run": "2026-06-25T10:00:00",
+                }
+            }
+        }
+        entries = _build_queue([once_job], runstate)
+        assert len(entries) == 0
+
+
+# ── Test 2: fire emits notify_triggered then notify_complete; failed emits notify_error ──
+
+
+class TestLifecycleNotifications:
+    """Verify telegram notifications fire on real job events."""
+
+    @patch("aipass.daemon.apps.handlers.schedule.telegram_notifier._send")
+    def test_triggered_sends_running(self, mock_send):
+        """notify_triggered sends running ping."""
+        mock_send.return_value = True
+        result = notify_triggered("@api", "data-check")
+        assert result is True
+        call_msg = mock_send.call_args[0][0]
+        assert "@api/data-check" in call_msg
+        assert "running" in call_msg
+
+    @patch("aipass.daemon.apps.handlers.schedule.telegram_notifier._send")
+    def test_complete_sends_dispatched(self, mock_send):
+        """notify_complete sends dispatched ping with summary."""
+        mock_send.return_value = True
+        result = notify_complete("@api", "data-check", "Agent spawned OK")
+        assert result is True
+        call_msg = mock_send.call_args[0][0]
+        assert "dispatched" in call_msg
+        assert "Agent spawned OK" in call_msg
+
+    @patch("aipass.daemon.apps.handlers.schedule.telegram_notifier._send")
+    def test_error_sends_failed(self, mock_send):
+        """notify_error sends failed ping with error detail."""
+        mock_send.return_value = True
+        result = notify_error("@api", "data-check", "timeout")
+        assert result is True
+        call_msg = mock_send.call_args[0][0]
+        assert "FAILED" in call_msg
+        assert "timeout" in call_msg
+
+
+# ── Test 3: runstate records last_status + last_error on both paths ──
+
+
+class TestRunstateStatusCapture:
+    """Verify runstate tracks status on success AND failure."""
+
+    def test_success_records_status(self):
+        """Successful fire sets last_status=success, last_success_at, clears error."""
+        runstate = {"jobs": {}}
+        schedule = {"type": "interval", "interval_minutes": 60}
+        update_job_runstate(runstate, "@commons", "test", schedule)
+        entry = runstate["jobs"]["@commons/test"]
+        assert entry["last_status"] == "success"
+        assert entry["last_success_at"] is not None
+        assert entry["last_error"] is None
+
+    def test_failure_records_status(self):
+        """Failed fire sets last_status=failed, last_failure_at, last_error."""
+        runstate = {"jobs": {}}
+        record_job_failure(runstate, "@commons", "test", "branch locked")
+        entry = runstate["jobs"]["@commons/test"]
+        assert entry["last_status"] == "failed"
+        assert entry["last_failure_at"] is not None
+        assert entry["last_error"] == "branch locked"
+
+    def test_failure_preserves_last_run(self):
+        """Failure path still records last_run timestamp."""
+        runstate = {"jobs": {}}
+        record_job_failure(runstate, "@x", "y", "err")
+        entry = runstate["jobs"]["@x/y"]
+        assert "last_run" in entry
+
+    def test_error_truncated(self):
+        """Long error messages are truncated to 500 chars."""
+        runstate = {"jobs": {}}
+        record_job_failure(runstate, "@x", "y", "x" * 1000)
+        entry = runstate["jobs"]["@x/y"]
+        assert len(entry["last_error"]) == 500
+
+
+# ── Test 4: queue --json returns frozen schema ──
+
+
+class TestQueueJsonSchema:
+    """Verify queue --json output matches the frozen contract."""
+
+    def test_schema_structure(self, interval_job):
+        """JSON output has generated_at, count, jobs array."""
+        runstate = {"jobs": {}}
+        entries = _build_queue([interval_job], runstate)
+        output = _build_json_output(entries)
+        assert "generated_at" in output
+        assert "count" in output
+        assert isinstance(output["jobs"], list)
+        assert output["count"] == len(output["jobs"])
+
+    def test_job_fields(self, interval_job):
+        """Each job in output has all frozen-schema fields."""
+        runstate = {"jobs": {}}
+        entries = _build_queue([interval_job], runstate)
+        job_out = entries[0]
+        required_fields = [
+            "owner",
+            "id",
+            "enabled",
+            "type",
+            "schedule_human",
+            "next_run",
+            "last_run",
+            "last_status",
+            "last_error",
+            "prompt_preview",
+            "wake",
+        ]
+        for field in required_fields:
+            assert field in job_out, f"Missing field: {field}"
+
+    def test_type_values(self, once_job, interval_job):
+        """Type field matches schedule type."""
+        runstate = {"jobs": {}}
+        once_entries = _build_queue([once_job], runstate)
+        assert once_entries[0]["type"] == "once"
+        interval_entries = _build_queue([interval_job], runstate)
+        assert interval_entries[0]["type"] == "interval"
+
+    def test_schedule_human_formats(self):
+        """schedule_human renders each type correctly."""
+        assert _schedule_human({"schedule": {"type": "once", "due_date": "2026-07-02"}}) == "2026-07-02"
+        assert _schedule_human({"schedule": {"type": "daily", "time": "04:00"}}) == "daily @ 04:00"
+        assert _schedule_human({"schedule": {"type": "hourly", "time": "30"}}) == "hourly @ :30"
+        assert _schedule_human({"schedule": {"type": "interval", "interval_minutes": 120}}) == "every 2h"
+        assert _schedule_human({"schedule": {"type": "interval", "interval_minutes": 30}}) == "every 30m"
+
+
+# ── Test 5: empty tick emits ZERO telegram calls ──
+
+
+class TestEmptyTickNoNotify:
+    """Verify no telegram calls on empty ticks (no due jobs)."""
+
+    @patch("aipass.daemon.apps.modules.run.discover_jobs", return_value=[])
+    @patch("aipass.daemon.apps.handlers.schedule.telegram_notifier._send")
+    def test_no_jobs_no_send(self, mock_send, mock_discover):
+        """Empty tick with no discovered jobs makes zero telegram calls."""
+        from aipass.daemon.apps.modules.run import run_tick
+
+        run_tick(dry_run=True)
+        mock_send.assert_not_called()
+
+    @patch("aipass.daemon.apps.modules.run.discover_jobs")
+    @patch("aipass.daemon.apps.modules.run.load_runstate")
+    @patch("aipass.daemon.apps.handlers.schedule.telegram_notifier._send")
+    def test_no_due_jobs_no_send(self, mock_send, mock_rs, mock_discover):
+        """Tick with jobs but none due makes zero telegram calls."""
+        from aipass.daemon.apps.modules.run import run_tick
+
+        mock_discover.return_value = [
+            {
+                "owner": "@commons",
+                "id": "test",
+                "enabled": True,
+                "schedule": {"type": "interval", "interval_minutes": 9999},
+                "wake": {},
+                "prompt": "test",
+            }
+        ]
+        mock_rs.return_value = {"jobs": {"@commons/test": {"last_run": datetime.now().isoformat()}}}
+        run_tick()
+        mock_send.assert_not_called()
+
+
+# ── Test 6: send is fail-soft ──
+
+
+class TestFailSoft:
+    """Verify telegram send failures don't block job firing."""
+
+    @patch("aipass.daemon.apps.handlers.schedule.telegram_notifier._send")
+    def test_send_returns_false_on_failure(self, mock_send):
+        """When _send fails, notify functions return False gracefully."""
+        mock_send.return_value = False
+        assert notify_triggered("@x", "y") is False
+        assert notify_complete("@x", "y", "s") is False
+        assert notify_error("@x", "y", "e") is False
+
+    @patch(
+        "aipass.skills.lib.telegram.apps.handlers.notifier.send_telegram_notification",
+        side_effect=Exception("connection refused"),
+    )
+    def test_exception_caught(self, mock_notifier):
+        """Exception in send_telegram_notification is caught, returns False."""
+        from aipass.daemon.apps.handlers.schedule.telegram_notifier import _send
+
+        result = _send("test message")
+        assert result is False
+
+    @patch("aipass.daemon.apps.modules.run.save_runstate")
+    @patch("aipass.daemon.apps.modules.run.record_job_failure")
+    @patch("aipass.daemon.apps.modules.run.update_job_runstate")
+    @patch("aipass.daemon.apps.modules.run.discover_jobs")
+    @patch("aipass.daemon.apps.modules.run.load_runstate", return_value={"jobs": {}})
+    def test_fire_continues_when_notify_fails(self, mock_rs, mock_discover, mock_update, mock_fail, mock_save):
+        """Job fires and records status even when telegram is down."""
+        from aipass.daemon.apps.modules.run import run_tick
+
+        mock_discover.return_value = [
+            {
+                "owner": "@commons",
+                "id": "test",
+                "enabled": True,
+                "schedule": {"type": "interval", "interval_minutes": 1},
+                "wake": {"fresh": True},
+                "prompt": "test",
+                "notify": True,
+            }
+        ]
+
+        with patch("aipass.daemon.apps.modules.run._fire_job", return_value=(True, "")):
+            results = run_tick()
+            assert results["fired"] == 1
+
+
+# ── Test 7: dormant registries archived ──
+
+
+class TestDormantArchived:
+    """Verify dormant registries are archived and no live code references them."""
+
+    def test_original_data_files_gone(self):
+        """Original data files no longer at daemon_json/ root."""
+        daemon_root = Path(__file__).resolve().parents[1]
+        assert not (daemon_root / "daemon_json" / "schedule.json").exists()
+        assert not (daemon_root / "daemon_json" / "actions_registry.json").exists()
+
+    def test_task_registry_not_importable(self):
+        """task_registry handler is gone from the live import path."""
+        with pytest.raises(ImportError):
+            from aipass.daemon.apps.handlers.schedule.task_registry import load_tasks  # type: ignore[import-not-found] # noqa: F401
+
+    def test_actions_registry_not_importable(self):
+        """actions_registry handler is gone from the live import path."""
+        with pytest.raises(ImportError):
+            from aipass.daemon.apps.handlers.actions.actions_registry import load_registry  # type: ignore[import-not-found] # noqa: F401
+
+    def test_schedule_module_retired(self):
+        """Schedule module handle_command shows retirement notice, not old CRUD."""
+        from aipass.daemon.apps.modules.schedule import handle_command as sched_cmd
+
+        assert sched_cmd("schedule", []) is True
+        assert sched_cmd("schedule", ["create", "test"]) is True
+
+    def test_actions_module_retired(self):
+        """Actions module handle_command shows retirement notice, not old CRUD."""
+        from aipass.daemon.apps.modules.actions import handle_command as act_cmd
+
+        assert act_cmd("actions", []) is True
+        assert act_cmd("actions", ["list"]) is True
+
+    def test_queue_command_wired(self):
+        """drone @daemon queue is routable."""
+        assert handle_command("queue", []) is True
+        assert handle_command("notqueue", []) is False
diff --git a/src/aipass/daemon/tests/test_scheduler_cron.py b/src/aipass/daemon/tests/test_scheduler_cron.py
deleted file mode 100644
index 2ae13ef9..00000000
--- a/src/aipass/daemon/tests/test_scheduler_cron.py
+++ /dev/null
@@ -1,488 +0,0 @@
-# ===================AIPASS====================
-# META DATA HEADER
-# Name: test_scheduler_cron.py - Scheduler Cron Tests
-# Date: 2026-04-02
-# Version: 1.0.0
-# Category: daemon/tests
-#
-# CHANGELOG (Max 5 entries):
-#   - v1.0.0 (2026-04-02): Initial creation - scheduler_cron dispatch path tests
-#
-# CODE STANDARDS:
-#   - Pytest conventions
-#   - Full mock isolation (no real subprocesses or locks)
-# =============================================
-
-"""Tests for scheduler_cron dispatch paths."""
-
-import subprocess
-import sys
-from datetime import datetime
-from unittest.mock import MagicMock, patch
-
-import pytest
-
-MODULE = "aipass.daemon.apps.scheduler_cron"
-
-
-# =============================================
-# FIXTURES
-# =============================================
-
-
-def _make_task(
-    task_id: str = "abc12345-6789",
-    recipient: str = "@devpulse",
-    task: str = "Run morning briefing",
-    message: str = "Details here",
-) -> dict:
-    """Build a minimal task dict for testing."""
-    return {
-        "id": task_id,
-        "recipient": recipient,
-        "task": task,
-        "message": message,
-    }
-
-
-@pytest.fixture(autouse=True)
-def _silence_logging():
-    """Suppress logger and console output for all tests."""
-    with (
-        patch(f"{MODULE}.logger"),
-        patch(f"{MODULE}.console"),
-        patch(f"{MODULE}.log"),
-    ):
-        yield
-
-
-# =============================================
-# _send_email_via_drone
-# =============================================
-
-
-class TestSendEmailViaDrone:
-    """Tests for _send_email_via_drone subprocess wrapper."""
-
-    def test_success(self):
-        from aipass.daemon.apps.scheduler_cron import _send_email_via_drone
-
-        mock_result = MagicMock(returncode=0)
-        with patch(f"{MODULE}.subprocess.run", return_value=mock_result) as mock_run:
-            result = _send_email_via_drone("@devpulse", "Subject", "Body")
-        assert result is True
-        mock_run.assert_called_once()
-        cmd = mock_run.call_args[0][0]
-        assert cmd[:3] == ["drone", "@ai_mail", "send"]
-        assert "--dispatch" in cmd
-
-    def test_no_auto_execute(self):
-        from aipass.daemon.apps.scheduler_cron import _send_email_via_drone
-
-        mock_result = MagicMock(returncode=0)
-        with patch(f"{MODULE}.subprocess.run", return_value=mock_result) as mock_run:
-            _send_email_via_drone("@devpulse", "Subj", "Msg", auto_execute=False)
-        cmd = mock_run.call_args[0][0]
-        assert "--dispatch" not in cmd
-
-    def test_nonzero_returncode(self):
-        from aipass.daemon.apps.scheduler_cron import _send_email_via_drone
-
-        mock_result = MagicMock(returncode=1)
-        with patch(f"{MODULE}.subprocess.run", return_value=mock_result):
-            result = _send_email_via_drone("@devpulse", "Subj", "Msg")
-        assert result is False
-
-    def test_subprocess_error(self):
-        from aipass.daemon.apps.scheduler_cron import _send_email_via_drone
-
-        with patch(f"{MODULE}.subprocess.run", side_effect=subprocess.TimeoutExpired(cmd="drone", timeout=15)):
-            result = _send_email_via_drone("@devpulse", "Subj", "Msg")
-        assert result is False
-
-    def test_os_error(self):
-        from aipass.daemon.apps.scheduler_cron import _send_email_via_drone
-
-        with patch(f"{MODULE}.subprocess.run", side_effect=OSError("drone not found")):
-            result = _send_email_via_drone("@devpulse", "Subj", "Msg")
-        assert result is False
-
-
-# =============================================
-# _next_cron_run
-# =============================================
-
-
-class TestNextCronRun:
-    """Tests for next cron run time calculation."""
-
-    def test_before_half_hour(self):
-        from aipass.daemon.apps.scheduler_cron import _next_cron_run
-
-        fake_now = datetime(2026, 4, 2, 10, 15, 0)
-        with patch(f"{MODULE}.datetime") as mock_dt:
-            mock_dt.now.return_value = fake_now
-            mock_dt.side_effect = lambda *a, **kw: datetime(*a, **kw)
-            result = _next_cron_run()
-        assert result == "10:30"
-
-    def test_after_half_hour(self):
-        from aipass.daemon.apps.scheduler_cron import _next_cron_run
-
-        fake_now = datetime(2026, 4, 2, 10, 45, 0)
-        with patch(f"{MODULE}.datetime") as mock_dt:
-            mock_dt.now.return_value = fake_now
-            mock_dt.side_effect = lambda *a, **kw: datetime(*a, **kw)
-            result = _next_cron_run()
-        assert result == "11:00"
-
-    def test_before_midnight_rollover(self):
-        from aipass.daemon.apps.scheduler_cron import _next_cron_run
-
-        fake_now = datetime(2026, 4, 2, 23, 45, 0)
-        with patch(f"{MODULE}.datetime") as mock_dt:
-            mock_dt.now.return_value = fake_now
-            mock_dt.side_effect = lambda *a, **kw: datetime(*a, **kw)
-            result = _next_cron_run()
-        assert result == "00:00"
-
-
-# =============================================
-# _process_single_task
-# =============================================
-
-
-class TestProcessSingleTask:
-    """Tests for the single-task dispatch function."""
-
-    def test_success_path(self):
-        from aipass.daemon.apps.scheduler_cron import _process_single_task
-
-        results = {"success": 0, "failed": 0, "errors": []}
-        task = _make_task()
-
-        with (
-            patch(f"{MODULE}.mark_dispatching") as mock_dispatch,
-            patch(f"{MODULE}.send_email_direct", return_value=True) as mock_send,
-            patch(f"{MODULE}.mark_completed") as mock_complete,
-            patch(f"{MODULE}.AI_MAIL_AVAILABLE", True),
-        ):
-            _process_single_task(task, results)
-
-        mock_dispatch.assert_called_once_with(task["id"])
-        mock_send.assert_called_once()
-        mock_complete.assert_called_once_with(task["id"])
-        assert results["success"] == 1
-        assert results["failed"] == 0
-
-    def test_mark_dispatching_failure(self):
-        from aipass.daemon.apps.scheduler_cron import _process_single_task
-
-        results = {"success": 0, "failed": 0, "errors": []}
-        task = _make_task()
-
-        with (
-            patch(f"{MODULE}.mark_dispatching", side_effect=RuntimeError("lock error")),
-            patch(f"{MODULE}.send_email_direct") as mock_send,
-        ):
-            _process_single_task(task, results)
-
-        mock_send.assert_not_called()
-        assert results["failed"] == 1
-        assert len(results["errors"]) == 1
-
-    def test_email_unavailable(self):
-        from aipass.daemon.apps.scheduler_cron import _process_single_task
-
-        results = {"success": 0, "failed": 0, "errors": []}
-        task = _make_task()
-
-        with (
-            patch(f"{MODULE}.mark_dispatching"),
-            patch(f"{MODULE}.AI_MAIL_AVAILABLE", False),
-            patch(f"{MODULE}.mark_pending") as mock_pending,
-        ):
-            _process_single_task(task, results)
-
-        mock_pending.assert_called_once_with(task["id"])
-        assert results["failed"] == 1
-
-    def test_email_send_returns_false(self):
-        from aipass.daemon.apps.scheduler_cron import _process_single_task
-
-        results = {"success": 0, "failed": 0, "errors": []}
-        task = _make_task()
-
-        with (
-            patch(f"{MODULE}.mark_dispatching"),
-            patch(f"{MODULE}.send_email_direct", return_value=False),
-            patch(f"{MODULE}.mark_pending") as mock_pending,
-            patch(f"{MODULE}.AI_MAIL_AVAILABLE", True),
-        ):
-            _process_single_task(task, results)
-
-        mock_pending.assert_called_once_with(task["id"])
-        assert results["failed"] == 1
-        assert results["success"] == 0
-
-    def test_email_exception_resets_to_pending(self):
-        from aipass.daemon.apps.scheduler_cron import _process_single_task
-
-        results = {"success": 0, "failed": 0, "errors": []}
-        task = _make_task()
-
-        with (
-            patch(f"{MODULE}.mark_dispatching"),
-            patch(f"{MODULE}.send_email_direct", side_effect=ConnectionError("timeout")),
-            patch(f"{MODULE}.mark_pending") as mock_pending,
-            patch(f"{MODULE}.AI_MAIL_AVAILABLE", True),
-        ):
-            _process_single_task(task, results)
-
-        mock_pending.assert_called_once_with(task["id"])
-        assert results["failed"] == 1
-
-
-# =============================================
-# process_due_tasks
-# =============================================
-
-
-class TestProcessDueTasks:
-    """Tests for the top-level due-task processor."""
-
-    def test_no_tasks_due(self):
-        from aipass.daemon.apps.scheduler_cron import process_due_tasks
-
-        with (
-            patch(f"{MODULE}.TASK_REGISTRY_AVAILABLE", True),
-            patch(f"{MODULE}.recover_stale_dispatches", return_value=0),
-            patch(f"{MODULE}.get_due_tasks", return_value=[]),
-        ):
-            results = process_due_tasks()
-
-        assert results["due"] == 0
-        assert results["success"] == 0
-
-    def test_task_registry_unavailable(self):
-        from aipass.daemon.apps.scheduler_cron import process_due_tasks
-
-        with patch(f"{MODULE}.TASK_REGISTRY_AVAILABLE", False):
-            results = process_due_tasks()
-
-        assert results["due"] == 0
-        assert results["success"] == 0
-
-    def test_stale_dispatch_recovery(self):
-        from aipass.daemon.apps.scheduler_cron import process_due_tasks
-
-        with (
-            patch(f"{MODULE}.TASK_REGISTRY_AVAILABLE", True),
-            patch(f"{MODULE}.recover_stale_dispatches", return_value=3) as mock_recover,
-            patch(f"{MODULE}.get_due_tasks", return_value=[]),
-        ):
-            results = process_due_tasks()
-
-        mock_recover.assert_called_once_with(max_age_minutes=5)
-        assert results["recovered"] == 3
-
-    def test_stale_recovery_exception(self):
-        from aipass.daemon.apps.scheduler_cron import process_due_tasks
-
-        with (
-            patch(f"{MODULE}.TASK_REGISTRY_AVAILABLE", True),
-            patch(f"{MODULE}.recover_stale_dispatches", side_effect=RuntimeError("fs error")),
-            patch(f"{MODULE}.get_due_tasks", return_value=[]),
-        ):
-            results = process_due_tasks()
-
-        assert len(results["errors"]) == 1
-        assert "Stale recovery" in results["errors"][0]
-
-    def test_get_due_tasks_exception(self):
-        from aipass.daemon.apps.scheduler_cron import process_due_tasks
-
-        with (
-            patch(f"{MODULE}.TASK_REGISTRY_AVAILABLE", True),
-            patch(f"{MODULE}.recover_stale_dispatches", return_value=0),
-            patch(f"{MODULE}.get_due_tasks", side_effect=RuntimeError("corrupt JSON")),
-        ):
-            results = process_due_tasks()
-
-        assert "Load tasks" in results["errors"][0]
-
-    @patch(f"{MODULE}.time.sleep")
-    def test_successful_send(self, _mock_sleep):
-        from aipass.daemon.apps.scheduler_cron import process_due_tasks
-
-        task = _make_task()
-        with (
-            patch(f"{MODULE}.TASK_REGISTRY_AVAILABLE", True),
-            patch(f"{MODULE}.recover_stale_dispatches", return_value=0),
-            patch(f"{MODULE}.get_due_tasks", return_value=[task]),
-            patch(f"{MODULE}.mark_dispatching"),
-            patch(f"{MODULE}.send_email_direct", return_value=True),
-            patch(f"{MODULE}.mark_completed"),
-            patch(f"{MODULE}.AI_MAIL_AVAILABLE", True),
-        ):
-            results = process_due_tasks()
-
-        assert results["due"] == 1
-        assert results["success"] == 1
-        assert results["failed"] == 0
-
-    @patch(f"{MODULE}.time.sleep")
-    def test_send_failure_marks_pending(self, _mock_sleep):
-        from aipass.daemon.apps.scheduler_cron import process_due_tasks
-
-        task = _make_task()
-        with (
-            patch(f"{MODULE}.TASK_REGISTRY_AVAILABLE", True),
-            patch(f"{MODULE}.recover_stale_dispatches", return_value=0),
-            patch(f"{MODULE}.get_due_tasks", return_value=[task]),
-            patch(f"{MODULE}.mark_dispatching"),
-            patch(f"{MODULE}.send_email_direct", return_value=False),
-            patch(f"{MODULE}.mark_pending") as mock_pending,
-            patch(f"{MODULE}.AI_MAIL_AVAILABLE", True),
-        ):
-            results = process_due_tasks()
-
-        mock_pending.assert_called_once()
-        assert results["failed"] == 1
-
-
-# =============================================
-# _run_locked
-# =============================================
-
-
-class TestRunLocked:
-    """Tests for the locked orchestration function."""
-
-    def test_success_no_errors(self):
-        from aipass.daemon.apps.scheduler_cron import _run_locked
-
-        task_results = {"due": 0, "success": 0, "failed": 0, "recovered": 0, "errors": []}
-        tick_results = {"discovered": 0, "enabled": 0, "due": 0, "fired": 0, "failed": 0, "skipped": 0}
-
-        with (
-            patch(f"{MODULE}.process_due_tasks", return_value=task_results),
-            patch(f"{MODULE}.run_tick", return_value=tick_results),
-            patch(f"{MODULE}._next_cron_run", return_value="10:30"),
-        ):
-            code = _run_locked()
-
-        assert code == 0
-
-    def test_returns_1_on_task_failures(self):
-        from aipass.daemon.apps.scheduler_cron import _run_locked
-
-        task_results = {"due": 1, "success": 0, "failed": 1, "recovered": 0, "errors": ["fail"]}
-        tick_results = {"discovered": 0, "enabled": 0, "due": 0, "fired": 0, "failed": 0, "skipped": 0}
-
-        with (
-            patch(f"{MODULE}.process_due_tasks", return_value=task_results),
-            patch(f"{MODULE}.run_tick", return_value=tick_results),
-            patch(f"{MODULE}._next_cron_run", return_value="10:30"),
-        ):
-            code = _run_locked()
-
-        assert code == 1
-
-    def test_process_due_tasks_unhandled_exception(self):
-        from aipass.daemon.apps.scheduler_cron import _run_locked
-
-        with patch(f"{MODULE}.process_due_tasks", side_effect=RuntimeError("boom")):
-            code = _run_locked()
-
-        assert code == 1
-
-    def test_run_tick_exception_handled(self):
-        from aipass.daemon.apps.scheduler_cron import _run_locked
-
-        task_results = {"due": 0, "success": 0, "failed": 0, "recovered": 0, "errors": []}
-
-        with (
-            patch(f"{MODULE}.process_due_tasks", return_value=task_results),
-            patch(f"{MODULE}.run_tick", side_effect=RuntimeError("tick boom")),
-            patch(f"{MODULE}._next_cron_run", return_value="10:30"),
-        ):
-            code = _run_locked()
-
-        assert code == 0
-
-
-# =============================================
-# main
-# =============================================
-
-
-class TestMain:
-    """Tests for the main entry point."""
-
-    def test_no_args_introspection(self):
-        from aipass.daemon.apps.scheduler_cron import main
-
-        with (
-            patch(f"{MODULE}.sys.argv", ["scheduler_cron.py"]),
-            patch(f"{MODULE}.print_introspection") as mock_intro,
-        ):
-            code = main()
-
-        mock_intro.assert_called_once()
-        assert code == 0
-
-    def test_help_flag(self):
-        from aipass.daemon.apps.scheduler_cron import main
-
-        with (
-            patch(f"{MODULE}.sys.argv", ["scheduler_cron.py", "--help"]),
-            patch(f"{MODULE}.print_help") as mock_help,
-        ):
-            with pytest.raises(SystemExit) as exc_info:
-                main()
-        mock_help.assert_called_once()
-        assert exc_info.value.code == 0
-
-    @pytest.mark.skipif(
-        sys.platform == "win32",
-        reason="patches fcntl.flock; fcntl is Unix-only (None on Windows). Scheduler skips locking on non-Unix.",
-    )
-    def test_lock_acquisition_failure(self, tmp_path):
-        from aipass.daemon.apps.scheduler_cron import main
-
-        lock_file = tmp_path / "schedule.lock"
-        mock_fd = MagicMock()
-        with (
-            patch(f"{MODULE}.sys.argv", ["scheduler_cron.py", "run"]),
-            patch(f"{MODULE}.json_handler"),
-            patch(f"{MODULE}.LOCK_FILE", lock_file),
-            patch("builtins.open", return_value=mock_fd),
-            patch(f"{MODULE}.fcntl.flock", side_effect=OSError("locked")),
-        ):
-            code = main()
-
-        assert code == 0  # graceful skip when another instance is running
-        mock_fd.close.assert_called()
-
-    @pytest.mark.skipif(
-        sys.platform == "win32",
-        reason="patches fcntl.flock; fcntl is Unix-only (None on Windows). Scheduler skips locking on non-Unix.",
-    )
-    def test_lock_acquired_runs_locked(self, tmp_path):
-        from aipass.daemon.apps.scheduler_cron import main
-
-        lock_file = tmp_path / "schedule.lock"
-        mock_fd = MagicMock()
-        with (
-            patch(f"{MODULE}.sys.argv", ["scheduler_cron.py", "run"]),
-            patch(f"{MODULE}.json_handler"),
-            patch(f"{MODULE}.LOCK_FILE", lock_file),
-            patch("builtins.open", return_value=mock_fd),
-            patch(f"{MODULE}.fcntl.flock"),
-            patch(f"{MODULE}._run_locked", return_value=0) as mock_run,
-        ):
-            code = main()
-
-        mock_run.assert_called_once()
-        assert code == 0
diff --git a/src/aipass/daemon/tests/test_scheduler_ops.py b/src/aipass/daemon/tests/test_scheduler_ops.py
deleted file mode 100644
index 9be64627..00000000
--- a/src/aipass/daemon/tests/test_scheduler_ops.py
+++ /dev/null
@@ -1,117 +0,0 @@
-# =================== AIPass ====================
-# Name: test_scheduler_ops.py
-# Description: Tests for the scheduler_ops facade module
-# Version: 1.0.0
-# Created: 2026-04-03
-# Modified: 2026-04-03
-# =============================================
-
-"""Tests for the scheduler_ops facade module (apps/modules/scheduler_ops.py)."""
-
-from unittest.mock import patch
-
-MODULE = "aipass.daemon.apps.modules.scheduler_ops"
-
-
-# =============================================
-# handle_command — routing
-# =============================================
-
-
-@patch(f"{MODULE}.json_handler")
-@patch(f"{MODULE}.console")
-@patch(f"{MODULE}.logger")
-class TestHandleCommand:
-    """Tests for handle_command routing."""
-
-    def test_wrong_command_returns_false(self, _log, _con, _jh):
-        from aipass.daemon.apps.modules.scheduler_ops import handle_command
-
-        assert handle_command("not-scheduler-ops", []) is False
-
-    def test_no_args_shows_introspection(self, _log, mock_console, _jh):
-        from aipass.daemon.apps.modules.scheduler_ops import handle_command
-
-        result = handle_command("scheduler-ops", [])
-        assert result is True
-        calls = [str(c) for c in mock_console.print.call_args_list]
-        assert any("scheduler_ops Module" in c for c in calls)
-
-    def test_help_flag_shows_introspection(self, _log, mock_console, _jh):
-        from aipass.daemon.apps.modules.scheduler_ops import handle_command
-
-        assert handle_command("scheduler-ops", ["--help"]) is True
-        calls = [str(c) for c in mock_console.print.call_args_list]
-        assert any("scheduler_ops Module" in c for c in calls)
-
-    def test_h_flag_shows_introspection(self, _log, mock_console, _jh):
-        from aipass.daemon.apps.modules.scheduler_ops import handle_command
-
-        assert handle_command("scheduler-ops", ["-h"]) is True
-        calls = [str(c) for c in mock_console.print.call_args_list]
-        assert any("scheduler_ops Module" in c for c in calls)
-
-    def test_help_word_shows_introspection(self, _log, mock_console, _jh):
-        from aipass.daemon.apps.modules.scheduler_ops import handle_command
-
-        assert handle_command("scheduler-ops", ["help"]) is True
-        calls = [str(c) for c in mock_console.print.call_args_list]
-        assert any("scheduler_ops Module" in c for c in calls)
-
-    def test_status_arg_shows_registry_info(self, _log, mock_console, mock_jh):
-        from aipass.daemon.apps.modules.scheduler_ops import handle_command
-
-        assert handle_command("scheduler-ops", ["status"]) is True
-        mock_jh.log_operation.assert_called_once_with("scheduler_ops_status")
-        calls = [str(c) for c in mock_console.print.call_args_list]
-        assert any("Scheduler Ops" in c for c in calls)
-
-    def test_status_prints_task_registry_availability(self, _log, mock_console, mock_jh):
-        from aipass.daemon.apps.modules.scheduler_ops import handle_command
-
-        handle_command("scheduler-ops", ["status"])
-        calls = [str(c) for c in mock_console.print.call_args_list]
-        assert any("Task registry" in c for c in calls)
-
-    def test_status_prints_action_registry_availability(self, _log, mock_console, mock_jh):
-        from aipass.daemon.apps.modules.scheduler_ops import handle_command
-
-        handle_command("scheduler-ops", ["status"])
-        calls = [str(c) for c in mock_console.print.call_args_list]
-        assert any("Action registry" in c for c in calls)
-
-
-# =============================================
-# Module-level availability flags
-# =============================================
-
-
-class TestRegistryAvailability:
-    """Verify that registry imports succeed in the test environment."""
-
-    def test_task_registry_available(self):
-        from aipass.daemon.apps.modules.scheduler_ops import TASK_REGISTRY_AVAILABLE
-
-        assert TASK_REGISTRY_AVAILABLE is True
-
-    def test_action_registry_available(self):
-        from aipass.daemon.apps.modules.scheduler_ops import ACTION_REGISTRY_AVAILABLE
-
-        assert ACTION_REGISTRY_AVAILABLE is True
-
-
-# =============================================
-# print_introspection
-# =============================================
-
-
-@patch(f"{MODULE}.console")
-class TestPrintIntrospection:
-    """Tests for print_introspection output."""
-
-    def test_prints_module_header(self, mock_console):
-        from aipass.daemon.apps.modules.scheduler_ops import print_introspection
-
-        print_introspection()
-        calls = [str(c) for c in mock_console.print.call_args_list]
-        assert any("scheduler_ops Module" in c for c in calls)
diff --git a/src/aipass/daemon/tests/test_task_registry.py b/src/aipass/daemon/tests/test_task_registry.py
deleted file mode 100644
index d27696d5..00000000
--- a/src/aipass/daemon/tests/test_task_registry.py
+++ /dev/null
@@ -1,588 +0,0 @@
-# ===================AIPASS====================
-# META DATA HEADER
-# Name: test_task_registry.py - Task Registry Tests
-# Date: 2026-03-24
-# Version: 1.0.0
-# Category: daemon/tests
-#
-# CHANGELOG (Max 5 entries):
-#   - v1.0.0 (2026-03-24): Initial creation - task_registry handler tests
-#
-# CODE STANDARDS:
-#   - Pytest conventions
-#   - Temp dir isolation (no writes to real registry)
-# =============================================
-
-"""Tests for the scheduled task registry handler."""
-
-import json
-from datetime import datetime, timedelta
-from unittest.mock import patch
-
-import pytest
-
-from aipass.daemon.apps.handlers.schedule import task_registry as _mod
-
-parse_due_date = _mod.parse_due_date
-create_task = _mod.create_task
-load_tasks = _mod.load_tasks
-save_tasks = _mod.save_tasks
-get_due_tasks = _mod.get_due_tasks
-mark_dispatching = _mod.mark_dispatching
-mark_completed = _mod.mark_completed
-mark_pending = _mod.mark_pending
-recover_stale_dispatches = _mod.recover_stale_dispatches
-delete_task = _mod.delete_task
-get_task_by_id = _mod.get_task_by_id
-get_pending_tasks = _mod.get_pending_tasks
-ensure_lock_dir = _mod.ensure_lock_dir
-
-
-@pytest.fixture(autouse=True)
-def isolate_registry(tmp_path):
-    """Redirect SCHEDULE_JSON_PATH to a temp dir for every test."""
-    test_file = tmp_path / "schedule.json"
-    original = _mod.SCHEDULE_JSON_PATH
-    _mod.SCHEDULE_JSON_PATH = test_file
-    yield test_file
-    _mod.SCHEDULE_JSON_PATH = original
-
-
-# =============================================
-# DATE PARSING TESTS
-# =============================================
-
-
-class TestParseDueDate:
-    def test_days_format(self):
-        """'7d' should resolve to 7 days from today."""
-        result = parse_due_date("7d")
-        expected = (datetime.now().date() + timedelta(days=7)).isoformat()
-        assert result == expected
-
-    def test_days_format_single_digit(self):
-        """'1d' should resolve to tomorrow."""
-        result = parse_due_date("1d")
-        expected = (datetime.now().date() + timedelta(days=1)).isoformat()
-        assert result == expected
-
-    def test_weeks_format(self):
-        """'1w' should resolve to 1 week from today."""
-        result = parse_due_date("1w")
-        expected = (datetime.now().date() + timedelta(weeks=1)).isoformat()
-        assert result == expected
-
-    def test_weeks_format_multiple(self):
-        """'2w' should resolve to 2 weeks from today."""
-        result = parse_due_date("2w")
-        expected = (datetime.now().date() + timedelta(weeks=2)).isoformat()
-        assert result == expected
-
-    def test_iso_date_format(self):
-        """'2026-06-15' should pass through as-is."""
-        result = parse_due_date("2026-06-15")
-        assert result == "2026-06-15"
-
-    def test_whitespace_stripped(self):
-        """Leading/trailing whitespace should be stripped."""
-        result = parse_due_date("  7d  ")
-        expected = (datetime.now().date() + timedelta(days=7)).isoformat()
-        assert result == expected
-
-    def test_case_insensitive_days(self):
-        """'7D' should work the same as '7d'."""
-        result = parse_due_date("7D")
-        expected = (datetime.now().date() + timedelta(days=7)).isoformat()
-        assert result == expected
-
-    def test_case_insensitive_weeks(self):
-        """'2W' should work the same as '2w'."""
-        result = parse_due_date("2W")
-        expected = (datetime.now().date() + timedelta(weeks=2)).isoformat()
-        assert result == expected
-
-    def test_invalid_format_raises(self):
-        """Unsupported format should raise ValueError."""
-        with pytest.raises(ValueError, match="Invalid date format"):
-            parse_due_date("next tuesday")
-
-    def test_invalid_iso_date_raises(self):
-        """Invalid calendar date in ISO format should raise ValueError."""
-        with pytest.raises(ValueError, match="Invalid date"):
-            parse_due_date("2026-02-30")
-
-    def test_empty_string_raises(self):
-        """Empty string should raise ValueError."""
-        with pytest.raises(ValueError, match="Invalid date format"):
-            parse_due_date("")
-
-    def test_zero_days(self):
-        """'0d' should resolve to today."""
-        result = parse_due_date("0d")
-        expected = datetime.now().date().isoformat()
-        assert result == expected
-
-
-# =============================================
-# LOAD / SAVE TESTS
-# =============================================
-
-
-class TestLoadSave:
-    def test_load_creates_file_if_missing(self, isolate_registry):
-        """load_tasks should create schedule.json if it does not exist."""
-        assert not isolate_registry.exists()
-        tasks = load_tasks()
-        assert tasks == []
-        assert isolate_registry.exists()
-
-    def test_load_returns_empty_on_fresh_file(self):
-        """Fresh schedule.json should have no tasks."""
-        tasks = load_tasks()
-        assert tasks == []
-
-    def test_save_and_load_roundtrip(self, isolate_registry):
-        """save_tasks then load_tasks should return the same data."""
-        sample = [{"id": "abc123", "task": "test", "status": "pending"}]
-        assert save_tasks(sample) is True
-        loaded = load_tasks()
-        assert len(loaded) == 1
-        assert loaded[0]["id"] == "abc123"
-
-    def test_save_overwrites_existing(self, isolate_registry):
-        """Saving new tasks should fully replace existing data."""
-        save_tasks([{"id": "first", "status": "pending"}])
-        save_tasks([{"id": "second", "status": "pending"}])
-        loaded = load_tasks()
-        assert len(loaded) == 1
-        assert loaded[0]["id"] == "second"
-
-    def test_load_handles_corrupt_json(self, isolate_registry):
-        """Corrupt JSON should return empty list, not crash."""
-        isolate_registry.parent.mkdir(parents=True, exist_ok=True)
-        isolate_registry.write_text("{invalid json", encoding="utf-8")
-        tasks = load_tasks()
-        assert tasks == []
-
-
-# =============================================
-# CREATE TASK TESTS
-# =============================================
-
-
-class TestCreateTask:
-    @patch.object(_mod.json_handler, "log_operation")
-    def test_create_basic(self, mock_log):
-        """Create a task and verify all fields."""
-        task = create_task(
-            task="Check backup health",
-            due_date="7d",
-            recipient="@devpulse",
-            message="Verify backup systems",
-        )
-        assert task["task"] == "Check backup health"
-        assert task["recipient"] == "@devpulse"
-        assert task["message"] == "Verify backup systems"
-        assert task["status"] == "pending"
-        assert len(task["id"]) == 16
-        assert task["id"].isalnum()
-        assert task["created"] == datetime.now().date().isoformat()
-        mock_log.assert_called_once_with("task_created")
-
-    @patch.object(_mod.json_handler, "log_operation")
-    def test_create_persists_to_json(self, mock_log, isolate_registry):
-        """Created task should be saved to the JSON file."""
-        create_task(
-            task="persisted task",
-            due_date="1d",
-            recipient="@seedgo",
-            message="msg",
-        )
-        raw = json.loads(isolate_registry.read_text(encoding="utf-8"))
-        assert len(raw["tasks"]) == 1
-        assert raw["tasks"][0]["task"] == "persisted task"
-
-    @patch.object(_mod.json_handler, "log_operation")
-    def test_create_multiple_tasks(self, mock_log):
-        """Multiple tasks should accumulate in the registry."""
-        create_task(task="t1", due_date="1d", recipient="@a", message="m1")
-        create_task(task="t2", due_date="2d", recipient="@b", message="m2")
-        tasks = load_tasks()
-        assert len(tasks) == 2
-        assert tasks[0]["task"] == "t1"
-        assert tasks[1]["task"] == "t2"
-
-    def test_create_invalid_date_raises(self):
-        """create_task should propagate ValueError from bad due_date."""
-        with pytest.raises(ValueError):
-            create_task(task="bad", due_date="xyz", recipient="@a", message="m")
-
-
-# =============================================
-# DUE TASKS TESTS
-# =============================================
-
-
-class TestDueTasks:
-    def test_overdue_task_returned(self, isolate_registry):
-        """A pending task with a past due_date should be returned."""
-        yesterday = (datetime.now().date() - timedelta(days=1)).isoformat()
-        save_tasks(
-            [
-                {
-                    "id": "past01",
-                    "due_date": yesterday,
-                    "status": "pending",
-                    "task": "overdue",
-                }
-            ]
-        )
-        due = get_due_tasks()
-        assert len(due) == 1
-        assert due[0]["id"] == "past01"
-
-    def test_today_task_returned(self, isolate_registry):
-        """A pending task due today should be returned."""
-        today = datetime.now().date().isoformat()
-        save_tasks(
-            [
-                {
-                    "id": "today01",
-                    "due_date": today,
-                    "status": "pending",
-                    "task": "due today",
-                }
-            ]
-        )
-        due = get_due_tasks()
-        assert len(due) == 1
-        assert due[0]["id"] == "today01"
-
-    def test_future_task_not_returned(self, isolate_registry):
-        """A pending task with a future due_date should not be returned."""
-        future = (datetime.now().date() + timedelta(days=30)).isoformat()
-        save_tasks(
-            [
-                {
-                    "id": "future01",
-                    "due_date": future,
-                    "status": "pending",
-                    "task": "future task",
-                }
-            ]
-        )
-        due = get_due_tasks()
-        assert len(due) == 0
-
-    def test_dispatching_task_excluded(self, isolate_registry):
-        """Tasks with status 'dispatching' should not be returned."""
-        yesterday = (datetime.now().date() - timedelta(days=1)).isoformat()
-        save_tasks(
-            [
-                {
-                    "id": "disp01",
-                    "due_date": yesterday,
-                    "status": "dispatching",
-                    "task": "already dispatching",
-                }
-            ]
-        )
-        due = get_due_tasks()
-        assert len(due) == 0
-
-    def test_completed_task_excluded(self, isolate_registry):
-        """Tasks with status 'completed' should not be returned."""
-        yesterday = (datetime.now().date() - timedelta(days=1)).isoformat()
-        save_tasks(
-            [
-                {
-                    "id": "done01",
-                    "due_date": yesterday,
-                    "status": "completed",
-                    "task": "done",
-                }
-            ]
-        )
-        due = get_due_tasks()
-        assert len(due) == 0
-
-    def test_empty_registry_returns_empty(self):
-        """Empty registry should return empty list."""
-        due = get_due_tasks()
-        assert due == []
-
-
-# =============================================
-# STATUS TRANSITION TESTS
-# =============================================
-
-
-class TestStatusTransitions:
-    def _seed_task(self, task_id: str = "abc12345abcd1234", status: str = "pending"):
-        """Helper to seed a single task."""
-        save_tasks(
-            [
-                {
-                    "id": task_id,
-                    "task": "test",
-                    "status": status,
-                    "due_date": "2026-01-01",
-                }
-            ]
-        )
-        return task_id
-
-    def test_mark_dispatching_success(self):
-        """mark_dispatching should set status and dispatch_started."""
-        tid = self._seed_task()
-        assert mark_dispatching(tid) is True
-        task = get_task_by_id(tid)
-        assert task is not None
-        assert task["status"] == "dispatching"
-        assert "dispatch_started" in task
-
-    def test_mark_dispatching_missing(self):
-        """mark_dispatching returns False for nonexistent ID."""
-        assert mark_dispatching("nonexistent_id__") is False
-
-    def test_mark_completed_success(self):
-        """mark_completed should set status and completed_date."""
-        tid = self._seed_task()
-        assert mark_completed(tid) is True
-        task = get_task_by_id(tid)
-        assert task is not None
-        assert task["status"] == "completed"
-        assert task["completed_date"] == datetime.now().date().isoformat()
-
-    def test_mark_completed_missing(self):
-        """mark_completed returns False for nonexistent ID."""
-        assert mark_completed("nonexistent_id__") is False
-
-    def test_mark_pending_success(self):
-        """mark_pending should reset status and remove dispatch_started."""
-        tid = self._seed_task(status="dispatching")
-        # Add dispatch_started to simulate real scenario
-        tasks = load_tasks()
-        tasks[0]["dispatch_started"] = datetime.now().isoformat()
-        save_tasks(tasks)
-
-        assert mark_pending(tid) is True
-        task = get_task_by_id(tid)
-        assert task is not None
-        assert task["status"] == "pending"
-        assert "dispatch_started" not in task
-
-    def test_mark_pending_missing(self):
-        """mark_pending returns False for nonexistent ID."""
-        assert mark_pending("nonexistent_id__") is False
-
-    def test_full_lifecycle(self):
-        """pending -> dispatching -> completed lifecycle."""
-        tid = self._seed_task()
-        task = get_task_by_id(tid)
-        assert task is not None
-        assert task["status"] == "pending"
-
-        mark_dispatching(tid)
-        task = get_task_by_id(tid)
-        assert task is not None
-        assert task["status"] == "dispatching"
-
-        mark_completed(tid)
-        task = get_task_by_id(tid)
-        assert task is not None
-        assert task["status"] == "completed"
-
-
-# =============================================
-# RECOVER STALE DISPATCHES TESTS
-# =============================================
-
-
-class TestRecoverStale:
-    def test_recovers_stale_task(self, isolate_registry):
-        """Task stuck in dispatching beyond max_age should be reset."""
-        stale_time = (datetime.now() - timedelta(minutes=10)).isoformat()
-        save_tasks(
-            [
-                {
-                    "id": "stale01",
-                    "task": "stale dispatch",
-                    "status": "dispatching",
-                    "dispatch_started": stale_time,
-                    "due_date": "2026-01-01",
-                }
-            ]
-        )
-        recovered = recover_stale_dispatches(max_age_minutes=5)
-        assert recovered == 1
-        task = get_task_by_id("stale01")
-        assert task is not None
-        assert task["status"] == "pending"
-        assert "dispatch_started" not in task
-
-    def test_does_not_recover_recent_dispatch(self, isolate_registry):
-        """Task dispatching within max_age should not be recovered."""
-        recent_time = (datetime.now() - timedelta(minutes=1)).isoformat()
-        save_tasks(
-            [
-                {
-                    "id": "recent01",
-                    "task": "recent dispatch",
-                    "status": "dispatching",
-                    "dispatch_started": recent_time,
-                    "due_date": "2026-01-01",
-                }
-            ]
-        )
-        recovered = recover_stale_dispatches(max_age_minutes=5)
-        assert recovered == 0
-        task = get_task_by_id("recent01")
-        assert task is not None
-        assert task["status"] == "dispatching"
-
-    def test_recovers_invalid_timestamp(self, isolate_registry):
-        """Task with unparseable dispatch_started should be recovered."""
-        save_tasks(
-            [
-                {
-                    "id": "bad_ts01",
-                    "task": "bad timestamp",
-                    "status": "dispatching",
-                    "dispatch_started": "not-a-date",
-                    "due_date": "2026-01-01",
-                }
-            ]
-        )
-        recovered = recover_stale_dispatches(max_age_minutes=5)
-        assert recovered == 1
-        task = get_task_by_id("bad_ts01")
-        assert task is not None
-        assert task["status"] == "pending"
-
-    def test_pending_tasks_untouched(self, isolate_registry):
-        """Pending tasks should not be affected by recovery."""
-        save_tasks(
-            [
-                {
-                    "id": "ok01",
-                    "task": "normal pending",
-                    "status": "pending",
-                    "due_date": "2026-01-01",
-                }
-            ]
-        )
-        recovered = recover_stale_dispatches(max_age_minutes=5)
-        assert recovered == 0
-        task = get_task_by_id("ok01")
-        assert task is not None
-        assert task["status"] == "pending"
-
-    def test_empty_registry_returns_zero(self):
-        """Recovery on empty registry should return 0."""
-        assert recover_stale_dispatches() == 0
-
-
-# =============================================
-# DELETE TASK TESTS
-# =============================================
-
-
-class TestDeleteTask:
-    def test_delete_existing(self, isolate_registry):
-        """Deleting an existing task returns True and removes it."""
-        save_tasks([{"id": "del01", "task": "to delete", "status": "pending"}])
-        assert delete_task("del01") is True
-        assert get_task_by_id("del01") is None
-        assert load_tasks() == []
-
-    def test_delete_missing(self):
-        """Deleting a nonexistent task returns False."""
-        assert delete_task("nonexistent_id__") is False
-
-    def test_delete_preserves_other_tasks(self, isolate_registry):
-        """Deleting one task should leave others intact."""
-        save_tasks(
-            [
-                {"id": "keep01", "task": "keep this", "status": "pending"},
-                {"id": "del02", "task": "delete this", "status": "pending"},
-            ]
-        )
-        delete_task("del02")
-        remaining = load_tasks()
-        assert len(remaining) == 1
-        assert remaining[0]["id"] == "keep01"
-
-    def test_delete_from_empty_registry(self):
-        """Delete on empty registry should return False without error."""
-        assert delete_task("anything") is False
-
-
-# =============================================
-# GET PENDING TASKS TESTS
-# =============================================
-
-
-class TestGetPendingTasks:
-    """Tests for get_pending_tasks()."""
-
-    def test_returns_only_pending(self, isolate_registry):
-        """Only tasks with status 'pending' are returned."""
-        save_tasks(
-            [
-                {"id": "pend01", "task": "pending one", "status": "pending"},
-                {"id": "pend02", "task": "pending two", "status": "pending"},
-                {"id": "done01", "task": "done", "status": "completed"},
-            ]
-        )
-        result = get_pending_tasks()
-        assert len(result) == 2
-        assert all(t["status"] == "pending" for t in result)
-
-    def test_excludes_dispatching_and_completed(self, isolate_registry):
-        """Tasks with dispatching or completed status are excluded."""
-        save_tasks(
-            [
-                {"id": "disp01", "task": "dispatching", "status": "dispatching"},
-                {"id": "done01", "task": "completed", "status": "completed"},
-                {"id": "pend01", "task": "pending", "status": "pending"},
-            ]
-        )
-        result = get_pending_tasks()
-        assert len(result) == 1
-        assert result[0]["id"] == "pend01"
-
-    def test_empty_registry_returns_empty(self):
-        """Empty registry returns empty list."""
-        result = get_pending_tasks()
-        assert result == []
-
-
-# =============================================
-# ENSURE LOCK DIR TESTS
-# =============================================
-
-
-class TestEnsureLockDir:
-    """Tests for ensure_lock_dir()."""
-
-    def test_creates_directory_if_missing(self, isolate_registry):
-        """Creates the lock directory when it does not exist."""
-        lock_dir = isolate_registry.parent
-        if lock_dir.exists():
-            import shutil
-
-            shutil.rmtree(lock_dir)
-        assert not lock_dir.exists()
-
-        result = ensure_lock_dir()
-        assert lock_dir.exists()
-        assert lock_dir.is_dir()
-        assert result["path"] == str(lock_dir)
-
-    def test_returns_dict_with_path_key(self, isolate_registry):
-        """Return value is a dict containing the 'path' key."""
-        result = ensure_lock_dir()
-        assert isinstance(result, dict)
-        assert "path" in result
-        assert isinstance(result["path"], str)
diff --git a/src/aipass/daemon/tests/test_timer_install.py b/src/aipass/daemon/tests/test_timer_install.py
new file mode 100644
index 00000000..3fe7cbc3
--- /dev/null
+++ b/src/aipass/daemon/tests/test_timer_install.py
@@ -0,0 +1,150 @@
+# =================== AIPass ====================
+# Name: test_timer_install.py
+# Description: Tests for the timer_install module (systemd user timer installer)
+# Version: 1.0.0
+# Created: 2026-06-25
+# Modified: 2026-06-25
+# =============================================
+
+"""Tests for the timer_install module (systemd user timer installer)."""
+
+import subprocess
+from unittest.mock import patch, MagicMock
+from pathlib import Path
+
+from aipass.daemon.apps.modules.timer_install import (
+    handle_command,
+    HANDLED_COMMANDS,
+    _run_systemctl,
+    _install,
+    _uninstall,
+)
+
+
+class TestHandleCommand:
+    """Tests for command routing."""
+
+    def test_handles_install_timer(self):
+        """Verify install-timer is in handled commands."""
+        assert "install-timer" in HANDLED_COMMANDS
+
+    def test_handles_uninstall_timer(self):
+        """Verify uninstall-timer is in handled commands."""
+        assert "uninstall-timer" in HANDLED_COMMANDS
+
+    def test_rejects_unknown(self):
+        """Unknown commands return False."""
+        assert handle_command("unknown", []) is False
+
+    def test_help_flag(self, capsys):
+        """Help flag prints usage and returns True."""
+        result = handle_command("install-timer", ["--help"])
+        assert result is True
+
+
+class TestRunSystemctl:
+    """Tests for the systemctl wrapper."""
+
+    @patch("subprocess.run")
+    def test_success(self, mock_run):
+        """Successful systemctl returns True."""
+        mock_run.return_value = MagicMock(returncode=0)
+        assert _run_systemctl("status", "daemon-tick.timer") is True
+
+    @patch("subprocess.run")
+    def test_failure_returncode(self, mock_run):
+        """Non-zero returncode returns False."""
+        mock_run.return_value = MagicMock(returncode=1, stderr="unit not found")
+        assert _run_systemctl("start", "daemon-tick.timer") is False
+
+    @patch("subprocess.run", side_effect=FileNotFoundError)
+    def test_systemctl_not_found(self, mock_run):
+        """Missing systemctl returns False."""
+        assert _run_systemctl("status", "daemon-tick.timer") is False
+
+    @patch(
+        "subprocess.run",
+        side_effect=subprocess.TimeoutExpired(cmd="systemctl", timeout=15),
+    )
+    def test_timeout(self, mock_run):
+        """Timed-out systemctl returns False."""
+        assert _run_systemctl("status", "daemon-tick.timer") is False
+
+
+class TestInstall:
+    """Tests for the install flow."""
+
+    def test_install_missing_unit_file(self):
+        """Returns 1 when unit files are missing."""
+        with patch(
+            "aipass.daemon.apps.modules.timer_install._DAEMON_ROOT",
+            Path("/nonexistent"),
+        ):
+            result = _install()
+            assert result == 1
+
+    @patch("aipass.daemon.apps.modules.timer_install._run_systemctl", return_value=True)
+    @patch("shutil.copy2")
+    def test_install_success(self, mock_copy, mock_systemctl, tmp_path):
+        """Successful install copies files and calls systemctl 3 times."""
+        service = tmp_path / "daemon-tick.service"
+        timer = tmp_path / "daemon-tick.timer"
+        service.write_text("[Unit]\n")
+        timer.write_text("[Unit]\n")
+
+        install_dir = tmp_path / "systemd"
+        install_dir.mkdir()
+
+        with (
+            patch("aipass.daemon.apps.modules.timer_install._DAEMON_ROOT", tmp_path),
+            patch("aipass.daemon.apps.modules.timer_install._UNIT_DIR", install_dir),
+        ):
+            result = _install()
+            assert result == 0
+            assert mock_systemctl.call_count == 3
+
+    @patch("aipass.daemon.apps.modules.timer_install._run_systemctl")
+    @patch("shutil.copy2")
+    def test_install_systemctl_fails(self, mock_copy, mock_systemctl, tmp_path):
+        """Returns 1 when systemctl fails."""
+        service = tmp_path / "daemon-tick.service"
+        timer = tmp_path / "daemon-tick.timer"
+        service.write_text("[Unit]\n")
+        timer.write_text("[Unit]\n")
+
+        install_dir = tmp_path / "systemd"
+        install_dir.mkdir()
+
+        mock_systemctl.return_value = False
+
+        with (
+            patch("aipass.daemon.apps.modules.timer_install._DAEMON_ROOT", tmp_path),
+            patch("aipass.daemon.apps.modules.timer_install._UNIT_DIR", install_dir),
+        ):
+            result = _install()
+            assert result == 1
+
+
+class TestUninstall:
+    """Tests for the uninstall flow."""
+
+    @patch("aipass.daemon.apps.modules.timer_install._run_systemctl", return_value=True)
+    def test_uninstall_files_not_present(self, mock_systemctl, tmp_path):
+        """Returns 0 even when unit files are already absent."""
+        with patch("aipass.daemon.apps.modules.timer_install._UNIT_DIR", tmp_path):
+            result = _uninstall()
+            assert result == 0
+
+    @patch("aipass.daemon.apps.modules.timer_install._run_systemctl", return_value=True)
+    def test_uninstall_removes_files(self, mock_systemctl, tmp_path):
+        """Removes unit files from the target directory."""
+        service = tmp_path / "daemon-tick.service"
+        timer = tmp_path / "daemon-tick.timer"
+        service.write_text("[Unit]\n")
+        timer.write_text("[Unit]\n")
+
+        with patch("aipass.daemon.apps.modules.timer_install._UNIT_DIR", tmp_path):
+            result = _uninstall()
+            assert result == 0
+            assert not service.exists()
+            assert not timer.exists()
diff --git a/src/aipass/devpulse/.aipass/aipass_local_prompt.md b/src/aipass/devpulse/.aipass/aipass_local_prompt.md
index 99df7675..ec625e7b 100644
--- a/src/aipass/devpulse/.aipass/aipass_local_prompt.md
+++ b/src/aipass/devpulse/.aipass/aipass_local_prompt.md
@@ -6,6 +6,12 @@ Breadcrumbs only — details in README, `--help`, `.trinity/`, `DASHBOARD.local.
 
 DEVPULSE — the user's primary collaborator, orchestration hub. Design, plan, debug, dispatch, track. Build own modules (watchdog, feedback), DPLANs, FPLANs, memories. Venture into other branches to investigate, debug, fix small bugs. Delegate heavy multi-file builds to sub-agents. CWD is identity grounding.
 
+# Memory entry limits — hook-enforced, over-limit = whole edit REJECTED
+
+ - The caps are NOT listed here (they'd go stale). Single source: @memory's `memory.config.json → entry_limits`, auto-rendered into each file's `*_meta` line (e.g. `todos_meta: … task ≤150 chars`). **Read the `*_meta` line of the section you're writing — the live cap is right there.**
+ - **Draft to ~80% of the cap** — never write at the ceiling. Unsure? `echo -n 'text' | wc -c` first.
+ - If rejected anyway: **rewrite hard in ONE pass** (cut to ~80%), never shave a few chars per retry.
+
 # How you work
 
  - Build own directly: modules, DPLANs, FPLANs, memories — edit freely.
diff --git a/src/aipass/drone/.seedgo/bypass.json b/src/aipass/drone/.seedgo/bypass.json
index 45467787..c0e6f90d 100644
--- a/src/aipass/drone/.seedgo/bypass.json
+++ b/src/aipass/drone/.seedgo/bypass.json
@@ -8,11 +8,14 @@
     {
       "file": "apps/drone.py",
       "standard": "cli",
-      "lines": [
-        166,
-        168
-      ],
-      "reason": "Raw passthrough of module subprocess stdout/stderr — console.print() breaks routed output"
+      "lines": [244, 246, 360, 362, 479, 481, 585, 587],
+      "reason": "Raw passthrough of routed command stdout/stderr — console.print() wraps at 80 cols when piped, corrupting JSON and machine output"
+    },
+    {
+      "file": "apps/modules/router.py",
+      "standard": "cli",
+      "lines": [62],
+      "reason": "Raw passthrough of routed command stdout — console.print() wraps at 80 cols when piped, corrupting JSON and machine output"
     },
     {
       "file": "apps/handlers/scanning/formatters.py",
@@ -252,25 +255,25 @@
     {
       "file": "apps/handlers/command_registry/ops.py",
       "standard": "unused_function",
-      "lines": [232, 263],
+      "functions": ["update_command", "command_exists"],
       "reason": "Public CRUD API surface (update_command, command_exists) — tested, available for programmatic use. No CLI subcommand wired yet."
     },
     {
       "file": "apps/handlers/git/pr_handler.py",
       "standard": "unused_function",
-      "lines": [108],
+      "functions": ["create_pr"],
       "reason": "create_pr() is deprecated per FPLAN-0210 — pr command blocked at auth tier. Handler kept for backwards compatibility; still tested in test_git_module.py."
     },
     {
       "file": "apps/modules/git_module.py",
       "standard": "unused_function",
-      "lines": [665],
+      "functions": ["get_introspective"],
       "reason": "get_introspective() called dynamically via getattr() by module_registry_handler.py:219 for internal module introspection. Also tested in test_git_module, test_system_pr, test_devpulse_plugins, test_git_access."
     },
     {
       "file": "apps/handlers/broker/daemon.py",
       "standard": "unused_function",
-      "lines": [422],
+      "functions": ["start_background"],
       "reason": "Threaded broker entrypoint, exercised by tests/test_broker.py; production uses blocking start(); intentionally not called in shipped non-test code."
     }
   ],
diff --git a/src/aipass/drone/apps/drone.py b/src/aipass/drone/apps/drone.py
index ecf3386e..8694fda1 100644
--- a/src/aipass/drone/apps/drone.py
+++ b/src/aipass/drone/apps/drone.py
@@ -241,9 +241,9 @@ def _handle_module(name: str, args: List[str]) -> int:
         return 1
 
     if result.get("stdout"):
-        console.print(result["stdout"], end="", highlight=False, markup=False)
+        sys.stdout.write(result["stdout"])
     if result.get("stderr"):
-        err_console.print(result["stderr"], end="", highlight=False, markup=False)
+        sys.stderr.write(result["stderr"])
     return result.get("exit_code", 0)
 
 
@@ -357,9 +357,9 @@ def _handle_custom_command(args: list[str]) -> int:
         return 1
 
     if result.stdout:
-        console.print(result.stdout, end="", highlight=False)
+        sys.stdout.write(result.stdout)
     if result.stderr:
-        err_console.print(result.stderr, end="", highlight=False)
+        sys.stderr.write(result.stderr)
     return result.exit_code
 
 
@@ -476,9 +476,9 @@ def _handle_target(args: List[str]) -> int:
         return 1
 
     if result.stdout:
-        console.print(result.stdout, end="", highlight=False)
+        sys.stdout.write(result.stdout)
     if result.stderr:
-        err_console.print(result.stderr, end="", highlight=False)
+        sys.stderr.write(result.stderr)
     return result.exit_code
 
 
@@ -582,9 +582,9 @@ def main() -> int:
             return 1
         if isinstance(result, dict):
             if result.get("stdout"):
-                console.print(result["stdout"], end="", highlight=False)
+                sys.stdout.write(result["stdout"])
             if result.get("stderr"):
-                err_console.print(result["stderr"], end="", highlight=False)
+                sys.stderr.write(result["stderr"])
             return result.get("exit_code", 0)
         return 0 if result else 1
 
diff --git a/src/aipass/drone/apps/handlers/__init__.py b/src/aipass/drone/apps/handlers/__init__.py
index c0323ec9..43ab76e5 100644
--- a/src/aipass/drone/apps/handlers/__init__.py
+++ b/src/aipass/drone/apps/handlers/__init__.py
@@ -41,13 +41,15 @@ def _find_real_caller():
     return None, None
 
 
+_BRANCH_ROOT = str(Path(__file__).resolve().parents[2])
+
+
 def _extract_branch_name(filepath: str) -> str:
-    """Extract branch name from a file path."""
-    parts = Path(filepath).parts
-    for i, part in enumerate(parts):
-        if part == "aipass":
-            if i + 1 < len(parts):
-                return parts[i + 1]
+    """Extract branch name from a file path by walking up to .trinity/."""
+    path = Path(filepath)
+    for parent in [path, *path.parents]:
+        if (parent / ".trinity").is_dir():
+            return parent.name
     return "unknown"
 
 
@@ -60,14 +62,13 @@ def _guard_branch_access():
     """
     caller_file, import_line = _find_real_caller()
 
-    # DEBUG: Print what we found
     import os
 
     if os.environ.get("AIPASS_DEBUG_GUARD"):
         import sys
 
-        print(f"[GUARD DEBUG] caller_file = {caller_file}", file=sys.stderr)
-        print(f"[GUARD DEBUG] import_line = {import_line}", file=sys.stderr)
+        sys.stderr.write(f"[GUARD DEBUG] caller_file = {caller_file}\n")
+        sys.stderr.write(f"[GUARD DEBUG] import_line = {import_line}\n")
 
     if caller_file is None:
         # Can't determine caller from real files
@@ -79,10 +80,7 @@ def _guard_branch_access():
                 return  # Allow command-line Python through
         return  # Allow if truly can't determine
 
-    # Check if caller is from our branch
-    # MY_BRANCH is "aipass.drone" (dotted), but filesystem uses "/aipass/drone/"
-    branch_path = "/" + MY_BRANCH.replace(".", "/") + "/"
-    if branch_path in caller_file.replace("\\", "/"):
+    if Path(caller_file).is_relative_to(_BRANCH_ROOT):
         return  # Same branch, allowed
 
     # External caller - block access
@@ -90,6 +88,7 @@ def _guard_branch_access():
     caller_filename = Path(caller_file).name
     blocked_import = import_line if import_line else "unknown"
 
+    module_api = f"{MY_BRANCH}.apps.modules"
     raise ImportError(
         f"\n{'=' * 60}\n"
         f"ACCESS DENIED: Cross-branch handler import blocked\n"
@@ -99,11 +98,7 @@ def _guard_branch_access():
         f"  Blocked:       {blocked_import}\n"
         f"\n"
         f"  Handlers are internal to their branch.\n"
-        f"  Use the module API instead:\n"
-        f"    from {MY_BRANCH}.apps.modules.<module> import <function>\n"
-        f"\n"
-        f"  Example:\n"
-        f"    from {MY_BRANCH}.apps.modules.logger import logger\n"
+        f"  Use the module API instead: {module_api}.<module>\n"
         f"\n"
         f"  For full standards guide:\n"
         f"    drone @seedgo handlers\n"
diff --git a/src/aipass/drone/apps/handlers/broker/daemon.py b/src/aipass/drone/apps/handlers/broker/daemon.py
index 4414422d..9f58c683 100644
--- a/src/aipass/drone/apps/handlers/broker/daemon.py
+++ b/src/aipass/drone/apps/handlers/broker/daemon.py
@@ -27,6 +27,7 @@ from __future__ import annotations
 import hashlib
 import hmac as hmac_mod
 import json
+import os
 import secrets
 import socket
 import threading
@@ -50,8 +51,6 @@ _TMP_BASES = (Path("/tmp"), Path("/var/tmp"))
 
 def _find_project_root() -> Path | None:
     """Walk up from CWD to find *_REGISTRY.json; return its parent as project root."""
-    import os
-
     cwd = Path.cwd()
     for parent in [cwd, *cwd.parents]:
         if list(parent.glob("*_REGISTRY.json")):
@@ -166,11 +165,24 @@ class BrokerDaemon:
         if identity == "devpulse":
             bases.append(self._repo_root)
             return bases
-        branch_dir = self._repo_root / "src" / "aipass" / identity
-        if branch_dir.is_dir():
+        branch_dir = self._resolve_branch_dir(identity)
+        if branch_dir and branch_dir.is_dir():
             bases.append(branch_dir)
         return bases
 
+    def _resolve_branch_dir(self, identity: str) -> Path | None:
+        """Find a branch directory by name via .trinity/ marker walk."""
+        if self._repo_root is None:
+            return None
+        for root, dirs, _files in os.walk(self._repo_root):
+            depth = len(Path(root).relative_to(self._repo_root).parts)
+            if depth > 3:
+                dirs.clear()
+                continue
+            if Path(root).name == identity and (Path(root) / ".trinity").is_dir():
+                return Path(root).resolve()
+        return None
+
     def _handle_identify(self, req: BrokerRequest) -> tuple[BrokerResponse, str | None]:
         """Verify HMAC and bind identity to the connection."""
         audit_entry: dict = {
diff --git a/src/aipass/drone/apps/handlers/git/commit_handler.py b/src/aipass/drone/apps/handlers/git/commit_handler.py
index bd6ec58e..6de30286 100644
--- a/src/aipass/drone/apps/handlers/git/commit_handler.py
+++ b/src/aipass/drone/apps/handlers/git/commit_handler.py
@@ -18,6 +18,18 @@ from aipass.drone.apps.handlers.json import json_handler
 from aipass.drone.apps.handlers.git.lock_handler import find_repo_root
 
 
+def _find_branch_for_path(filepath: str, repo_root: Path) -> tuple[str, Path] | None:
+    """Find which branch a changed file belongs to by walking up to .trinity/."""
+    abs_path = (repo_root / filepath).resolve()
+    root = repo_root.resolve()
+    for parent in [abs_path.parent, *abs_path.parent.parents]:
+        if not parent.is_relative_to(root):
+            break
+        if (parent / ".trinity").is_dir():
+            return parent.name, parent
+    return None
+
+
 def _run_test_gate(repo_root: Path) -> dict | None:
     """Run pytest for changed branches. Returns error dict if tests fail, None if all pass."""
     status_result = subprocess.run(
@@ -26,21 +38,22 @@ def _run_test_gate(repo_root: Path) -> dict | None:
         text=True,
         cwd=str(repo_root),
     )
-    changed_branches: set[str] = set()
+    changed_branches: dict[str, Path] = {}
     for line in status_result.stdout.splitlines():
         if len(line) < 4:
             continue
         filepath = line[3:].split(" -> ")[-1]
-        parts = Path(filepath).parts
-        if len(parts) >= 3 and parts[0] == "src" and parts[1] == "aipass":
-            changed_branches.add(parts[2])
+        result = _find_branch_for_path(filepath, repo_root)
+        if result:
+            name, branch_path = result
+            changed_branches[name] = branch_path
 
     venv_python = repo_root / ".venv" / "bin" / "python"
     python_bin = str(venv_python) if venv_python.exists() else "python3"
 
     failed_branches: list[tuple[str, str]] = []
     for branch_name in sorted(changed_branches):
-        test_dir = repo_root / "src" / "aipass" / branch_name / "tests"
+        test_dir = changed_branches[branch_name] / "tests"
         if not test_dir.is_dir():
             continue
         try:
diff --git a/src/aipass/drone/apps/handlers/registry_handler.py b/src/aipass/drone/apps/handlers/registry_handler.py
index d1459d07..7ce34be2 100644
--- a/src/aipass/drone/apps/handlers/registry_handler.py
+++ b/src/aipass/drone/apps/handlers/registry_handler.py
@@ -144,13 +144,16 @@ def find_registry() -> Path:
         if hit is not None:
             return hit
 
-    # Fallback — use package-relative path; glob there too
-    fallback_dir = Path(__file__).resolve().parents[4]
+    # Fallback — walk up from this file to the project root (marker-based)
+    _markers = (".git", "pyproject.toml", "setup.py", "setup.cfg")
+    fallback_dir = Path(__file__).resolve().parent
+    for parent in [fallback_dir, *fallback_dir.parents]:
+        if any((parent / m).exists() for m in _markers):
+            fallback_dir = parent
+            break
     hit = _first_registry_in(fallback_dir)
     if hit is not None:
         return hit
-    # Ultimate fallback: return a conventional name so the caller
-    # gets a clear "not found" path in the error message.
     return fallback_dir / "AIPASS_REGISTRY.json"
 
 
diff --git a/src/aipass/drone/apps/handlers/rm_handler.py b/src/aipass/drone/apps/handlers/rm_handler.py
index d745c55e..47bd0614 100644
--- a/src/aipass/drone/apps/handlers/rm_handler.py
+++ b/src/aipass/drone/apps/handlers/rm_handler.py
@@ -67,16 +67,23 @@ def get_allowed_roots() -> list[Path]:
     return roots
 
 
+def _find_branch_root(path: Path, project_root: Path) -> Path | None:
+    """Walk up from *path* looking for .trinity/; return branch dir or None."""
+    root = project_root.resolve()
+    for parent in [path, *path.parents]:
+        if not parent.is_relative_to(root):
+            break
+        if (parent / ".trinity").is_dir():
+            return parent
+    return None
+
+
 def _detect_current_branch(project_root: Path | None) -> str | None:
     """Return the branch name the CWD lives in, or None."""
     if project_root is None:
         return None
-    cwd = Path.cwd().resolve()
-    aipass_src = project_root / "src" / "aipass"
-    if not cwd.is_relative_to(aipass_src):
-        return None
-    rel = cwd.relative_to(aipass_src)
-    return rel.parts[0] if rel.parts else None
+    branch_root = _find_branch_root(Path.cwd().resolve(), project_root)
+    return branch_root.name if branch_root else None
 
 
 def _resolve_git_dir(path: Path) -> Path | None:
@@ -109,14 +116,11 @@ def check_carveouts(resolved: Path, project_root: Path | None) -> tuple[bool, st
                 return True, "Protected: path resolves inside .git worktree gitdir"
 
     if project_root is not None:
-        aipass_src = project_root / "src" / "aipass"
-        if resolved.is_relative_to(aipass_src):
-            rel = resolved.relative_to(aipass_src)
-            if rel.parts:
-                target_branch = rel.parts[0]
-                current_branch = _detect_current_branch(project_root)
-                if current_branch is None or target_branch != current_branch:
-                    return True, (f"Protected: path is inside sibling branch src/aipass/{target_branch}/")
+        target_branch_root = _find_branch_root(resolved, project_root)
+        if target_branch_root is not None:
+            current_branch = _detect_current_branch(project_root)
+            if current_branch is None or target_branch_root.name != current_branch:
+                return True, f"Protected: path is inside sibling branch {target_branch_root.name}/"
 
     return False, ""
 
diff --git a/src/aipass/drone/apps/modules/router.py b/src/aipass/drone/apps/modules/router.py
index 9c994d40..68a30191 100644
--- a/src/aipass/drone/apps/modules/router.py
+++ b/src/aipass/drone/apps/modules/router.py
@@ -14,6 +14,7 @@ to the handler layer.
 """
 
 import os
+import sys
 from pathlib import Path
 from typing import Dict, List, Optional
 
@@ -58,7 +59,7 @@ def handle_command(command: Optional[str] = None, args: Optional[List[str]] = No
         cmd_args = args[2:] if len(args) > 2 else None
         result = route_command(target, cmd, args=cmd_args)
         if result.stdout:
-            console.print(result.stdout, highlight=False)
+            sys.stdout.write(result.stdout)
         return result.exit_code == 0
     if command == "route_all":
         if not args:
@@ -132,7 +133,8 @@ def print_introspection():
     console.print("[yellow]Connected Handlers:[/yellow]")
     console.print("  [cyan]handlers/[/cyan]")
     console.print(
-        "    - [cyan]router_handler.py[/cyan] [dim](execute_branch_command — resolves and executes branch commands)[/dim]"
+        "    - [cyan]router_handler.py[/cyan] "
+        "[dim](execute_branch_command — resolves and executes branch commands)[/dim]"
     )
     console.print("    - [cyan]executor.py[/cyan] [dim](CommandResult — subprocess execution result dataclass)[/dim]")
     console.print()
diff --git a/src/aipass/drone/tests/test_broker.py b/src/aipass/drone/tests/test_broker.py
index 5692da41..ce3b989b 100644
--- a/src/aipass/drone/tests/test_broker.py
+++ b/src/aipass/drone/tests/test_broker.py
@@ -90,11 +90,12 @@ def _send_identified(broker: BrokerDaemon, branch: str, req: BrokerRequest) -> B
 
 @pytest.fixture()
 def repo_root(tmp_path: Path) -> Path:
-    """Set up a mock repo root with branch directories."""
+    """Set up a mock repo root with branch directories marked by .trinity/."""
     root = tmp_path / "repo"
     root.mkdir()
     branch = root / "src" / "aipass" / "testbranch"
     branch.mkdir(parents=True)
+    (branch / ".trinity").mkdir()
     (branch / "deleteme.txt").write_text("delete me", encoding="utf-8")
     (branch / "subdir").mkdir()
     (branch / "subdir" / "nested.txt").write_text("nested", encoding="utf-8")
@@ -102,6 +103,7 @@ def repo_root(tmp_path: Path) -> Path:
     (branch / ".git" / "HEAD").write_text("ref: refs/heads/main", encoding="utf-8")
     sibling = root / "src" / "aipass" / "sibling"
     sibling.mkdir(parents=True)
+    (sibling / ".trinity").mkdir()
     (sibling / "important.txt").write_text("don't delete", encoding="utf-8")
     return root
 
diff --git a/src/aipass/drone/tests/test_git_access.py b/src/aipass/drone/tests/test_git_access.py
index be1e7717..38211183 100644
--- a/src/aipass/drone/tests/test_git_access.py
+++ b/src/aipass/drone/tests/test_git_access.py
@@ -387,8 +387,11 @@ class TestCommitChanges:
             stderr="",
         )
 
-        test_dir = repo_dir / "src" / "aipass" / "drone" / "tests"
-        test_dir.mkdir(parents=True)
+        drone_dir = repo_dir / "src" / "aipass" / "drone"
+        drone_dir.mkdir(parents=True)
+        (drone_dir / ".trinity").mkdir()
+        test_dir = drone_dir / "tests"
+        test_dir.mkdir()
 
         with (
             patch("shutil.which", return_value="/usr/bin/ruff"),
@@ -417,8 +420,11 @@ class TestCommitChanges:
         mock_diff = MagicMock(returncode=1, stdout="", stderr="")
         mock_commit = MagicMock(returncode=0, stdout="[main abc999] green commit", stderr="")
 
-        test_dir = repo_dir / "src" / "aipass" / "drone" / "tests"
-        test_dir.mkdir(parents=True)
+        drone_dir = repo_dir / "src" / "aipass" / "drone"
+        drone_dir.mkdir(parents=True)
+        (drone_dir / ".trinity").mkdir()
+        test_dir = drone_dir / "tests"
+        test_dir.mkdir()
 
         with (
             patch("shutil.which", return_value="/usr/bin/ruff"),
diff --git a/src/aipass/drone/tests/test_rm.py b/src/aipass/drone/tests/test_rm.py
index 159e4cbc..d1822ee0 100644
--- a/src/aipass/drone/tests/test_rm.py
+++ b/src/aipass/drone/tests/test_rm.py
@@ -36,10 +36,11 @@ def project_dir(tmp_path):
 
 @pytest.fixture()
 def project_with_branches(project_dir):
-    """Project root with src/aipass/<branch> layout for sibling tests."""
+    """Project root with branch dirs containing .trinity/ markers."""
     for branch in ("drone", "api", "flow"):
         d = project_dir / "src" / "aipass" / branch
         d.mkdir(parents=True)
+        (d / ".trinity").mkdir()
         (d / "README.md").write_text(f"# {branch}")
     return project_dir
 
diff --git a/src/aipass/flow/README.md b/src/aipass/flow/README.md
index 42413763..369fae7b 100644
--- a/src/aipass/flow/README.md
+++ b/src/aipass/flow/README.md
@@ -146,6 +146,8 @@ On `drone @flow close`:
 
 Vector verification displays in console: "Vectorized: N chunks in chroma" or "NOT vectorized".
 
+Closed plans are archived to `<repo-root>/.backup/processed_plans/`, a shared runtime namespace managed by `@backup` (see `src/aipass/backup/README.md`) and consumed by `@memory` for vectorization.
+
 ---
 
 ## Integration Points
diff --git a/src/aipass/hooks/.seedgo/bypass.json b/src/aipass/hooks/.seedgo/bypass.json
index 892f2145..c60683c9 100644
--- a/src/aipass/hooks/.seedgo/bypass.json
+++ b/src/aipass/hooks/.seedgo/bypass.json
@@ -869,6 +869,31 @@
       "standard": "unused_function",
       "reason": "sandbox_launch(), build_policy(), build_srt_config(), and resolve_bwrap_command() are consumed CROSS-BRANCH by ai_mail's dispatch_monitor.py (the launch seam at Phase 4). seedgo's intra-branch static analysis cannot see these callers. Verified: dispatch_monitor imports sandbox module to wire build_policy + sandbox_launch at agent launch."
     },
+    {
+      "file": "apps/handlers/security/presence_gate.py",
+      "standard": "dead_code",
+      "reason": "Invoked dynamically by engine via importlib from hooks.json handler path 'aipass.hooks.apps.handlers.security.presence_gate.handle' — not statically imported by design. Wired in UserPromptSubmit.presence_gate + Stop.presence_release."
+    },
+    {
+      "file": "apps/handlers/security/presence_gate.py",
+      "standard": "unused_function",
+      "reason": "handle() and handle_stop() called dynamically by engine._run_handler via importlib.import_module + getattr from hooks.json. Wired in UserPromptSubmit.presence_gate and Stop.presence_release."
+    },
+    {
+      "file": "apps/handlers/security/presence_gate.py",
+      "standard": "json_structure",
+      "reason": "Security gate uses stdlib json.dumps for hook protocol block responses — no JSON file ops needing json_handler."
+    },
+    {
+      "file": "apps/modules/presence.py",
+      "standard": "json_structure",
+      "reason": "Presence service uses stdlib json for .ai_central/PRESENCE.central.json — shared runtime namespace, not branch json_handler storage."
+    },
+    {
+      "file": "apps/modules/presence.py",
+      "standard": "unused_function",
+      "reason": "claim(), release(), refresh(), read_all() consumed by presence_gate.py handler (dynamically dispatched via engine). Static analysis cannot trace hooks.json → engine → handler → presence module."
+    },
     {
       "file": "apps/handlers/notification/telegram_response.py",
       "standard": "unused_function",
@@ -898,6 +923,141 @@
       "file": "tests/test_telegram_response.py",
       "standard": "meta",
       "reason": "Test files do not need Version/Modified metadata headers."
+    },
+    {
+      "file": "apps/modules/presence.py",
+      "standard": "json_structure",
+      "reason": "Uses stdlib json for .ai_central/PRESENCE.central.json shared runtime namespace — not branch data storage needing json_handler."
+    },
+    {
+      "file": "apps/modules/presence.py",
+      "standard": "modules",
+      "reason": "Direct file ops on .ai_central/PRESENCE.central.json — a shared runtime namespace (gitignored, cross-branch). Not a handler-level concern; the module IS the presence service that owns this file."
+    },
+    {
+      "file": "apps/modules/presence.py",
+      "standard": "dead_code",
+      "reason": "claim(), release(), refresh(), read_all() consumed by presence_gate.py handler (dynamically dispatched via engine). handle_command() and print_introspection() called by drone routing. Static analysis cannot trace hooks.json → engine → handler → presence module."
+    },
+    {
+      "file": "apps/modules/presence.py",
+      "standard": "unused_function",
+      "reason": "claim(), release(), refresh(), read_all() consumed by presence_gate.py handler (dynamically dispatched via engine). handle_command() and print_introspection() called by drone routing."
+    },
+    {
+      "file": "apps/handlers/security/presence_gate.py",
+      "standard": "dead_code",
+      "reason": "Invoked dynamically by engine via importlib from hooks.json handler path 'aipass.hooks.apps.handlers.security.presence_gate.handle' — not statically imported by design. Wired in UserPromptSubmit.presence_gate + Stop.presence_release."
+    },
+    {
+      "file": "apps/handlers/security/presence_gate.py",
+      "standard": "unused_function",
+      "reason": "handle() and handle_stop() called dynamically by engine._run_handler via importlib.import_module + getattr from hooks.json. Wired in UserPromptSubmit.presence_gate + Stop.presence_release."
+    },
+    {
+      "file": "apps/handlers/security/presence_gate.py",
+      "standard": "json_structure",
+      "reason": "Security gate uses stdlib json.dumps for hook protocol block responses — no JSON file ops needing json_handler."
+    },
+    {
+      "file": "tests/test_presence.py",
+      "standard": "architecture",
+      "reason": "Test files live in tests/, not in the 3-layer apps structure."
+    },
+    {
+      "file": "tests/test_presence.py",
+      "standard": "documentation",
+      "reason": "Test methods use descriptive names as documentation per pytest convention."
+    },
+    {
+      "file": "tests/test_presence.py",
+      "standard": "encapsulation",
+      "reason": "Tests import modules directly to test implementation details."
+    },
+    {
+      "file": "tests/test_presence.py",
+      "standard": "meta",
+      "reason": "Test files do not need Version/Modified metadata headers."
+    },
+    {
+      "file": "tests/test_presence_gate.py",
+      "standard": "architecture",
+      "reason": "Test files live in tests/, not in the 3-layer apps structure."
+    },
+    {
+      "file": "tests/test_presence_gate.py",
+      "standard": "documentation",
+      "reason": "Test methods use descriptive names as documentation per pytest convention."
+    },
+    {
+      "file": "tests/test_presence_gate.py",
+      "standard": "encapsulation",
+      "reason": "Tests import handlers directly to test implementation details."
+    },
+    {
+      "file": "tests/test_presence_gate.py",
+      "standard": "meta",
+      "reason": "Test files do not need Version/Modified metadata headers."
+    },
+    {
+      "file": "apps/modules/cc_sessions.py",
+      "standard": "json_structure",
+      "reason": "Reads CC-native ~/.claude/sessions/*.json (external files, not branch data) with stdlib json — no JSON file ops needing json_handler."
+    },
+    {
+      "file": "apps/modules/cc_sessions.py",
+      "standard": "modules",
+      "reason": "Direct file ops on ~/.claude/sessions/*.json — external CC-native session files, not branch data. The module IS the CC session reader service; json_handler is for branch-managed JSON, not external platform files."
+    },
+    {
+      "file": "apps/handlers/lifecycle/session_boot.py",
+      "standard": "json_structure",
+      "reason": "Boot wrapper has no JSON file ops — delegates to cc_sessions module for session reads. No json_handler needed."
+    },
+    {
+      "file": "apps/handlers/lifecycle/session_boot.py",
+      "standard": "dead_code",
+      "reason": "Boot wrapper invoked via __main__ entry point from shell shim (tools/install_boot_shim.sh) — not engine-dispatched. boot() and main() called at process entry, not statically imported."
+    },
+    {
+      "file": "apps/handlers/lifecycle/session_boot.py",
+      "standard": "unused_function",
+      "reason": "boot() and main() invoked via __main__ entry point from shell shim — not statically imported. _resolve_claude_binary(), _find_live_sessions(), _find_tmux(), etc. are internal helpers called by boot()."
+    },
+    {
+      "file": "tests/test_cc_sessions.py",
+      "standard": "architecture",
+      "reason": "Test files live in tests/, not in the 3-layer apps structure."
+    },
+    {
+      "file": "tests/test_cc_sessions.py",
+      "standard": "documentation",
+      "reason": "Test methods use descriptive names as documentation per pytest convention."
+    },
+    {
+      "file": "tests/test_cc_sessions.py",
+      "standard": "meta",
+      "reason": "Test files do not need Version/Modified metadata headers."
+    },
+    {
+      "file": "tests/test_session_boot.py",
+      "standard": "architecture",
+      "reason": "Test files live in tests/, not in the 3-layer apps structure."
+    },
+    {
+      "file": "tests/test_session_boot.py",
+      "standard": "documentation",
+      "reason": "Test methods use descriptive names as documentation per pytest convention."
+    },
+    {
+      "file": "tests/test_session_boot.py",
+      "standard": "meta",
+      "reason": "Test files do not need Version/Modified metadata headers."
+    },
+    {
+      "file": "tests/test_session_boot.py",
+      "standard": "encapsulation",
+      "reason": "Tests import handlers directly to test implementation details."
     }
   ],
   "notes": {
diff --git a/src/aipass/hooks/README.md b/src/aipass/hooks/README.md
index d11597ca..c3bf993e 100644
--- a/src/aipass/hooks/README.md
+++ b/src/aipass/hooks/README.md
@@ -49,9 +49,11 @@ src/aipass/hooks/
 │   ├── sound.py                 # Shared sound utilities (speak, play, mute)
 │   ├── modules/
 │   │   ├── cadence.py           # Prompt injection cadence (every-Nth-turn gating)
+│   │   ├── cc_sessions.py       # CC-native session file reader (~/.claude/sessions/<pid>.json)
 │   │   ├── engine.py            # Core dispatch — routes events to handlers
 │   │   ├── hooksound.py         # Sound control (drone @hooks hooksound on/off)
 │   │   ├── hookstatus.py        # Config viewer (drone @hooks status)
+│   │   ├── presence.py          # Branch presence — claim/release/refresh for .ai_central/PRESENCE.central.json
 │   │   └── sandbox.py           # Kernel sandbox — srt/bwrap wrapper + per-role policy generator
 │   ├── handlers/
 │   │   ├── bridges/             # One per provider (thin normalization)
@@ -64,6 +66,7 @@ src/aipass/hooks/
 │   │   ├── security/            # Enforcement hooks
 │   │   │   ├── edit_gate.py     #   Blocks unsafe edits (cross-branch, inbox, diagnostics)
 │   │   │   ├── git_gate.py      #   Enforces git access tiers
+│   │   │   ├── presence_gate.py  #   Single-session gate — blocks duplicate runtimes per branch
 │   │   │   ├── rm_gate.py       #   Guardrail — catches accidental rm -rf, teaches drone rm
 │   │   │   └── subagent_gate.py #   Blocks sub-agent stop until clean
 │   │   ├── lifecycle/           # Session management hooks
@@ -82,7 +85,7 @@ src/aipass/hooks/
 │       └── diagnostics.py       # JSONL logging for hook execution
 ├── logs/
 │   └── engine.jsonl             # JSONL diagnostics (every hook execution)
-└── tests/                       # 593 tests across 23 test files
+└── tests/                       # 705 tests across 25 test files
 ```
 
 ## How It Works
@@ -103,11 +106,11 @@ Handlers are called **dynamically at runtime** — the engine uses `importlib.im
 
 | Event | Hooks | Description |
 |---|---|---|
-| UserPromptSubmit | identity, email, branch_loader, tier0_kernel, navmap | Prompt injection + inbox check |
+| UserPromptSubmit | presence_gate, identity, email, branch_loader, tier0_kernel, navmap | Presence gate + prompt injection + inbox check |
 | PreToolUse | tool_sound, edit_gate, git_gate, rm_gate | Security gates + guardrails + sound |
 | PostToolUse | auto_fix, auto_watchdog | Diagnostics + watchdog |
 | SubagentStop | subagent_gate | Seedgo validation |
-| Stop | stop_sound, telegram_response | Achievement bell + Telegram reply delivery |
+| Stop | stop_sound, telegram_response, presence_release | Bell + Telegram delivery + presence release |
 | Notification | announce | Announcement tone |
 | PreCompact | compact, rollover | Memory archival + rollover |
 
@@ -151,7 +154,7 @@ The @drone broker validates sandbox policy before agent launch. @ai_mail's dispa
 - All branches via hook dispatch — every Claude Code session routes through the engine
 - @ai_mail dispatch_monitor — sandbox_launch + build_policy for agent launch boundary
 
-*Last Updated: 2026-06-10*
+*Last Updated: 2026-06-29*
 
 ---
 
diff --git a/src/aipass/hooks/apps/handlers/bridges/claude.py b/src/aipass/hooks/apps/handlers/bridges/claude.py
index 384f8577..35321ae7 100644
--- a/src/aipass/hooks/apps/handlers/bridges/claude.py
+++ b/src/aipass/hooks/apps/handlers/bridges/claude.py
@@ -53,9 +53,11 @@ def main() -> None:
         hook_def = full_config.get(event_type, {}).get(hook_filter, {})
         config = {"hooks_enabled": True, event_type: {hook_filter: hook_def}}
 
-    output = dispatch(event_type, stdin_data, config)
+    output, exit_code = dispatch(event_type, stdin_data, config)
     if output:
         sys.stdout.write(output)
+    if exit_code:
+        sys.exit(exit_code)
 
 
 if __name__ == "__main__":
diff --git a/src/aipass/hooks/apps/handlers/lifecycle/session_boot.py b/src/aipass/hooks/apps/handlers/lifecycle/session_boot.py
new file mode 100644
index 00000000..68b583a5
--- /dev/null
+++ b/src/aipass/hooks/apps/handlers/lifecycle/session_boot.py
@@ -0,0 +1,190 @@
+# =================== AIPass ====================
+# Name: session_boot.py
+# Version: 1.1.0
+# Description: Boot wrapper — attach-if-live or start-in-tmux for Claude Code
+# Branch: hooks
+# Layer: apps/handlers/lifecycle
+# Created: 2026-06-30
+# Modified: 2026-06-30
+# =============================================
+
+"""Boot wrapper for Claude Code sessions.
+
+When Patrick boots Claude in a branch directory, this wrapper:
+  1. If already inside tmux ($TMUX set) → execs claude directly (no nesting).
+  2. Checks CC-native ~/.claude/sessions/ for a live session at this cwd.
+  3. If live AND hosted in a tmux session → attaches to that tmux session.
+  4. If live but NOT in tmux → warns (can't inject into a plain terminal).
+  5. If no live session → starts fresh inside a new tmux session.
+
+Tmux sessions are named after the branch directory (e.g., "hooks", "devpulse").
+All sessions use --permission-mode bypassPermissions (TG user can't answer prompts).
+Remote visibility is preserved (tmux composes with remoteControlAtStartup).
+
+Entry points:
+  drone @hooks boot [claude args...]
+"""
+
+import os
+import shutil
+import subprocess
+import sys
+from pathlib import Path
+
+from aipass.prax.apps.modules.logger import system_logger as logger
+
+_DEFAULT_ARGS = ["--permission-mode", "bypassPermissions"]
+
+
+def _resolve_claude_binary() -> str:
+    """Resolve the REAL claude binary path from PATH.
+
+    Uses shutil.which, which searches the filesystem PATH — it does NOT see
+    shell functions. So even when a claude() shell function shadows the binary,
+    this finds the real one.
+    """
+    path = shutil.which("claude")
+    if path:
+        return path
+    logger.error("[SESSION_BOOT] claude binary not found on PATH")
+    return "claude"
+
+
+def _find_live_sessions(cwd: str) -> list[dict]:
+    """Find live CC sessions for the given cwd via cc_sessions module."""
+    import importlib
+
+    cc_sessions = importlib.import_module("aipass.hooks.apps.modules.cc_sessions")
+    return cc_sessions.find_live_for_cwd(cwd)
+
+
+def _find_tmux() -> str | None:
+    """Find tmux binary on PATH."""
+    return shutil.which("tmux")
+
+
+def _tmux_session_exists(name: str) -> bool:
+    """Check if a tmux session with the given name exists."""
+    result = subprocess.run(
+        ["tmux", "has-session", "-t", name],
+        capture_output=True,
+        text=True,
+    )
+    return result.returncode == 0
+
+
+def _find_tmux_session_for_pid(pid: int) -> str | None:
+    """Find which tmux session hosts the given PID (as a descendant of a pane)."""
+    result = subprocess.run(
+        ["tmux", "list-panes", "-a", "-F", "#{pane_pid} #{session_name}"],
+        capture_output=True,
+        text=True,
+    )
+    if result.returncode != 0:
+        return None
+    for line in result.stdout.strip().splitlines():
+        parts = line.split(None, 1)
+        if len(parts) != 2:
+            continue
+        pane_pid_str, session_name = parts
+        try:
+            pane_pid = int(pane_pid_str)
+        except ValueError:
+            logger.info("[SESSION_BOOT] Non-integer pane PID: %s", pane_pid_str)
+            continue
+        if _is_descendant(pid, pane_pid):
+            return session_name
+    return None
+
+
+def _is_descendant(target_pid: int, ancestor_pid: int) -> bool:
+    """Check if target_pid is a descendant of ancestor_pid via /proc."""
+    pid = target_pid
+    for _ in range(20):
+        if pid == ancestor_pid:
+            return True
+        if pid <= 1:
+            return False
+        try:
+            for line in Path(f"/proc/{pid}/status").read_text().splitlines():
+                if line.startswith("PPid:"):
+                    pid = int(line.split()[1])
+                    break
+            else:
+                return False
+        except OSError as exc:
+            logger.info("[SESSION_BOOT] Cannot read /proc/%d/status: %s", pid, exc)
+            return False
+    return False
+
+
+def boot(cwd: str | None = None, extra_args: list[str] | None = None) -> dict:
+    """Boot Claude Code — attach if live, else start in tmux.
+
+    Args:
+        cwd: Branch directory (defaults to current working directory).
+        extra_args: Additional arguments to pass to claude (after default args).
+
+    Returns:
+        Result dict with action taken and details.
+    """
+    cwd = cwd or str(Path.cwd().resolve())
+    branch = Path(cwd).name
+    claude_bin = _resolve_claude_binary()
+
+    if os.environ.get("TMUX"):
+        logger.info("[SESSION_BOOT] Already inside tmux — running claude directly")
+        claude_cmd = [claude_bin] + _DEFAULT_ARGS
+        if extra_args:
+            claude_cmd.extend(extra_args)
+        os.execvp(claude_bin, claude_cmd)
+        return {"exit_code": 0, "action": "direct", "reason": "already in tmux"}
+
+    tmux = _find_tmux()
+    if not tmux:
+        logger.error("[SESSION_BOOT] tmux not found on PATH")
+        return {"exit_code": 1, "error": "tmux not found — required for session hosting"}
+
+    live = _find_live_sessions(cwd)
+
+    if live:
+        session = live[0]
+        pid = session["pid"]
+        name = session.get("name", "")
+        logger.info("[SESSION_BOOT] Live session found: PID %d%s", pid, f" ({name})" if name else "")
+
+        tmux_session = _find_tmux_session_for_pid(pid)
+        if tmux_session:
+            logger.info("[SESSION_BOOT] Attaching to tmux session '%s'", tmux_session)
+            os.execvp("tmux", ["tmux", "attach-session", "-t", tmux_session])
+            return {"exit_code": 0, "action": "attached", "tmux_session": tmux_session}
+
+        return {
+            "exit_code": 1,
+            "action": "warn",
+            "error": f"Live session at PID {pid} is not in tmux. Kill it first or attach to its terminal.",
+        }
+
+    if _tmux_session_exists(branch):
+        logger.info("[SESSION_BOOT] Killing stale tmux session '%s'", branch)
+        subprocess.run(["tmux", "kill-session", "-t", branch], check=False)
+
+    claude_cmd = [claude_bin] + _DEFAULT_ARGS
+    if extra_args:
+        claude_cmd.extend(extra_args)
+
+    logger.info("[SESSION_BOOT] Starting fresh in tmux session '%s': %s", branch, " ".join(claude_cmd))
+    os.execvp("tmux", ["tmux", "new-session", "-s", branch, "--"] + claude_cmd)
+    return {"exit_code": 0, "action": "started", "tmux_session": branch}
+
+
+def main() -> None:
+    """CLI entry point for the boot wrapper."""
+    result = boot(extra_args=sys.argv[1:] if len(sys.argv) > 1 else None)
+    if result.get("exit_code", 0) != 0:
+        sys.stderr.write(f"{result.get('error', 'boot failed')}\n")
+        sys.exit(result["exit_code"])
+
+
+if __name__ == "__main__":
+    main()
diff --git a/src/aipass/hooks/apps/handlers/notification/telegram_response.py b/src/aipass/hooks/apps/handlers/notification/telegram_response.py
index cd336694..8ea70900 100644
--- a/src/aipass/hooks/apps/handlers/notification/telegram_response.py
+++ b/src/aipass/hooks/apps/handlers/notification/telegram_response.py
@@ -1,11 +1,11 @@
 # =================== AIPass ====================
 # Name: telegram_response.py
-# Version: 1.0.0
+# Version: 2.0.0
 # Description: Telegram response delivery on Stop event (ported from Dev-Pass)
 # Branch: hooks
 # Layer: apps/handlers/notification
 # Created: 2026-06-15
-# Modified: 2026-06-15
+# Modified: 2026-06-29
 # =============================================
 
 """Telegram response delivery on Stop event.
@@ -18,6 +18,7 @@ Layer 2: isSidechain filter — skips sidechain entries during transcript extrac
 Layer 3: Transcript position — only extracts text after the recorded injection point
 """
 
+import hashlib
 import json
 import os
 import re
@@ -30,12 +31,16 @@ from urllib.request import Request, urlopen
 from aipass.prax.apps.modules.logger import system_logger as logger
 
 PENDING_DIR = Path.home() / ".aipass" / "telegram_pending"
+MIRROR_DIR = Path.home() / ".aipass" / "telegram_bots"
 PENDING_TTL = 3600
 TELEGRAM_CHAR_LIMIT = 4096
+_DELIVERY_LOG = Path(__file__).resolve().parent.parent.parent.parent / "logs" / "telegram_delivery.jsonl"
 
 
 def _is_expired(data: dict) -> bool:
     """Check if pending file is expired (1-hour TTL + tmux-alive check)."""
+    if data.get("mirror"):
+        return False
     timestamp = data.get("timestamp", 0)
     if isinstance(timestamp, str):
         try:
@@ -73,38 +78,49 @@ def _try_load_pending(path: Path) -> dict | None:
     return None
 
 
+def _in_mirror_dir(path: Path) -> bool:
+    """Check if a path is inside the persistent mirror mapping directory."""
+    try:
+        path.relative_to(MIRROR_DIR)
+        return True
+    except ValueError:
+        logger.info("[HOOKS] telegram: %s is not in mirror dir", path.name)
+        return False
+
+
 def find_pending_file(session_id: str) -> Path | None:  # noqa: ARG001
     """Find pending file matching current context via multi-bot matching.
 
-    Priority 1: AIPASS_BOT_ID env var -> bot-{bot_id}.json
-    Priority 2: CWD relative_to work_dir -> bot-*.json
+    Priority 1: AIPASS_BOT_ID env var -> bot-{bot_id}.json (mirror dir first, then pending)
+    Priority 2: CWD relative_to work_dir -> bot-*.json (both dirs)
     """
-    if not PENDING_DIR.exists():
-        return None
-
     cwd = Path.cwd()
     env_bot_id = os.environ.get("AIPASS_BOT_ID")
 
     if env_bot_id:
-        v2_path = PENDING_DIR / f"bot-{env_bot_id}.json"
-        if _try_load_pending(v2_path) is not None:
-            logger.info("[HOOKS] telegram: v2 match bot_id env -> %s", v2_path.name)
-            return v2_path
+        for search_dir in [MIRROR_DIR, PENDING_DIR]:
+            path = search_dir / f"bot-{env_bot_id}.json"
+            if _try_load_pending(path) is not None:
+                logger.info("[HOOKS] telegram: match bot_id env -> %s", path)
+                return path
 
-    for pending_path in sorted(PENDING_DIR.glob("bot-*.json")):
-        data = _try_load_pending(pending_path)
-        if data is None:
-            continue
-        work_dir = data.get("work_dir")
-        if not work_dir:
-            continue
-        try:
-            cwd.relative_to(Path(work_dir))
-            logger.info("[HOOKS] telegram: v2 match cwd -> %s", pending_path.name)
-            return pending_path
-        except ValueError:
-            logger.info("[HOOKS] telegram: cwd not relative to %s, skipping", pending_path.name)
+    for search_dir in [PENDING_DIR, MIRROR_DIR]:
+        if not search_dir.exists():
             continue
+        for pending_path in sorted(search_dir.glob("bot-*.json")):
+            data = _try_load_pending(pending_path)
+            if data is None:
+                continue
+            work_dir = data.get("work_dir")
+            if not work_dir:
+                continue
+            try:
+                cwd.relative_to(Path(work_dir))
+                logger.info("[HOOKS] telegram: match cwd -> %s", pending_path)
+                return pending_path
+            except ValueError:
+                logger.info("[HOOKS] telegram: cwd not relative to %s, skipping", pending_path.name)
+                continue
 
     return None
 
@@ -192,6 +208,128 @@ def _collect_assistant_text(lines: list[str]) -> list[str]:
     return text_parts
 
 
+def _extract_user_text(content: list | str) -> str | None:
+    """Extract text from user message content, returning None for tool-result-only messages."""
+    if isinstance(content, str):
+        return content.strip() or None
+    if not isinstance(content, list):
+        return None
+    texts: list[str] = []
+    has_non_tool = False
+    for block in content:
+        if not isinstance(block, dict):
+            continue
+        if block.get("type") == "text":
+            text = block.get("text", "").strip()
+            if text:
+                texts.append(text)
+            has_non_tool = True
+        elif block.get("type") != "tool_result":
+            has_non_tool = True
+    if not has_non_tool:
+        return None
+    return " ".join(texts) if texts else None
+
+
+def _text_from_content(content: list) -> list[str]:
+    """Extract text strings from a message content block list."""
+    if not isinstance(content, list):
+        return []
+    parts: list[str] = []
+    for block in content:
+        if isinstance(block, dict) and block.get("type") == "text":
+            text = block.get("text", "").strip()
+            if text:
+                parts.append(text)
+    return parts
+
+
+def _collect_mirror_entries(lines: list[str]) -> list[tuple[str | None, list[str]]]:
+    """Collect user+assistant turn pairs from JSONL lines for mirror delivery."""
+    turns: list[tuple[str | None, list[str]]] = []
+    current_user: str | None = None
+    current_assistant: list[str] = []
+
+    for line in lines:
+        try:
+            entry = json.loads(line)
+        except json.JSONDecodeError:
+            logger.info("[HOOKS] telegram: skipping malformed JSONL line in mirror collection")
+            continue
+        if entry.get("isSidechain", False):
+            continue
+
+        entry_type = entry.get("type")
+        message = entry.get("message", {})
+        content = message.get("content", [])
+
+        if entry_type == "user":
+            user_text = _extract_user_text(content)
+            if user_text is None:
+                continue
+            if current_user is not None or current_assistant:
+                turns.append((current_user, current_assistant))
+            current_user = user_text
+            current_assistant = []
+
+        elif entry_type == "assistant":
+            current_assistant.extend(_text_from_content(content))
+
+    if current_user is not None or current_assistant:
+        turns.append((current_user, current_assistant))
+
+    return turns
+
+
+def extract_mirror_turn(transcript_path: str, start_line: int = 0) -> str | None:
+    """Extract all new turns (user input + assistant response) for mirror delivery."""
+    path = Path(transcript_path)
+    if not path.exists():
+        logger.warning("[HOOKS] telegram: mirror transcript not found: %s", transcript_path)
+        return None
+
+    try:
+        all_lines = path.read_text(encoding="utf-8").strip().split("\n")
+    except OSError as e:
+        logger.error("[HOOKS] telegram: failed to read mirror transcript: %s", e)
+        return None
+
+    if not all_lines:
+        return None
+
+    lines = all_lines[start_line:] if start_line > 0 else all_lines
+    if not lines and start_line > len(all_lines):
+        logger.warning(
+            "[HOOKS] telegram: cursor ahead of transcript (%d > %d) — clamping to deliver latest",
+            start_line,
+            len(all_lines),
+        )
+        clamped = _find_last_real_user_message(all_lines)
+        lines = all_lines[max(0, clamped) :]
+    if not lines:
+        return None
+
+    turns = _collect_mirror_entries(lines)
+    if not turns:
+        return None
+
+    formatted = []
+    for user_text, assistant_parts in turns:
+        parts: list[str] = []
+        if user_text:
+            parts.append(f"You: {user_text}")
+        if assistant_parts:
+            parts.append("\n\n".join(assistant_parts))
+        if parts:
+            formatted.append("\n\n".join(parts))
+
+    if not formatted:
+        return None
+
+    result = "\n\n---\n\n".join(formatted).strip()
+    return result if result else None
+
+
 def chunk_text(text: str, limit: int = TELEGRAM_CHAR_LIMIT) -> list[str]:
     """Split text into chunks for Telegram's message limit."""
     if len(text) <= limit:
@@ -278,8 +416,14 @@ def markdown_to_telegram_html(text: str) -> str:
     return text
 
 
-def send_to_telegram(bot_token: str, chat_id: int, text: str, message_id: int | None = None) -> bool:
-    """Send a message to Telegram via Bot API using urllib."""
+def _parse_api_message(api_result: dict) -> dict:
+    """Extract message_id and text from a Telegram API response."""
+    msg = api_result.get("result", {})
+    return {"ok": True, "message_id": msg.get("message_id"), "text": msg.get("text", "")}
+
+
+def send_to_telegram(bot_token: str, chat_id: int, text: str, message_id: int | None = None) -> dict:
+    """Send a message to Telegram via Bot API. Returns dict with ok, message_id, text."""
     url = f"https://api.telegram.org/bot{bot_token}/sendMessage"
 
     try:
@@ -290,10 +434,10 @@ def send_to_telegram(bot_token: str, chat_id: int, text: str, message_id: int |
         data = json.dumps(html_payload).encode("utf-8")
         req = Request(url, data=data, headers={"Content-Type": "application/json"})
         with urlopen(req, timeout=15) as resp:
-            result = json.loads(resp.read())
-            if result.get("ok"):
-                return True
-        logger.warning("[HOOKS] telegram: HTML send failed: %s", result.get("description"))
+            api_result = json.loads(resp.read())
+            if api_result.get("ok"):
+                return _parse_api_message(api_result)
+        logger.warning("[HOOKS] telegram: HTML send failed: %s", api_result.get("description"))
     except Exception as e:
         logger.warning("[HOOKS] telegram: HTML send error: %s, plain text fallback", e)
 
@@ -306,11 +450,11 @@ def send_to_telegram(bot_token: str, chat_id: int, text: str, message_id: int |
 
     try:
         with urlopen(req, timeout=15) as resp:
-            result = json.loads(resp.read())
-            if result.get("ok"):
-                return True
-            logger.error("[HOOKS] telegram: API error: %s", result.get("description"))
-            return False
+            api_result = json.loads(resp.read())
+            if api_result.get("ok"):
+                return _parse_api_message(api_result)
+            logger.error("[HOOKS] telegram: API error: %s", api_result.get("description"))
+            return {"ok": False}
     except HTTPError as e:
         try:
             body = json.loads(e.read().decode("utf-8"))
@@ -318,17 +462,17 @@ def send_to_telegram(bot_token: str, chat_id: int, text: str, message_id: int |
             logger.error("[HOOKS] telegram: HTTP %d: %s (len=%d)", e.code, description, len(text))
         except Exception:
             logger.error("[HOOKS] telegram: HTTP %d: %s (len=%d)", e.code, e.reason, len(text))
-        return False
+        return {"ok": False}
     except URLError as e:
         logger.error("[HOOKS] telegram: send failed: %s", e)
-        return False
+        return {"ok": False}
     except Exception as e:
         logger.error("[HOOKS] telegram: unexpected send error: %s", e)
-        return False
+        return {"ok": False}
 
 
-def edit_telegram_message(bot_token: str, chat_id: int, message_id: int, text: str) -> bool:
-    """Edit an existing Telegram message via Bot API."""
+def edit_telegram_message(bot_token: str, chat_id: int, message_id: int, text: str) -> dict:
+    """Edit an existing Telegram message via Bot API. Returns dict with ok, message_id, text."""
     url = f"https://api.telegram.org/bot{bot_token}/editMessageText"
 
     try:
@@ -337,9 +481,9 @@ def edit_telegram_message(bot_token: str, chat_id: int, message_id: int, text: s
         data = json.dumps(html_payload).encode("utf-8")
         req = Request(url, data=data, headers={"Content-Type": "application/json"})
         with urlopen(req, timeout=15) as resp:
-            result = json.loads(resp.read())
-            if result.get("ok", False):
-                return True
+            api_result = json.loads(resp.read())
+            if api_result.get("ok", False):
+                return _parse_api_message(api_result)
         logger.warning("[HOOKS] telegram: HTML edit failed, plain text fallback")
     except Exception as e:
         logger.warning("[HOOKS] telegram: HTML edit error: %s, plain text fallback", e)
@@ -350,23 +494,26 @@ def edit_telegram_message(bot_token: str, chat_id: int, message_id: int, text: s
 
     try:
         with urlopen(req, timeout=15) as resp:
-            result = json.loads(resp.read())
-            return result.get("ok", False)
+            api_result = json.loads(resp.read())
+            if api_result.get("ok", False):
+                return _parse_api_message(api_result)
+            return {"ok": False}
     except Exception as e:
         logger.warning("[HOOKS] telegram: edit failed: %s", e)
-        return False
+        return {"ok": False}
 
 
-def _send_with_retry(bot_token: str, chat_id: int, text: str, retries: int = 3) -> bool:
-    """Send with retry and exponential backoff."""
+def _send_with_retry(bot_token: str, chat_id: int, text: str, retries: int = 3) -> dict:
+    """Send with retry and exponential backoff. Returns dict with ok, message_id, text."""
     for attempt in range(retries):
-        if send_to_telegram(bot_token, chat_id, text):
-            return True
+        result = send_to_telegram(bot_token, chat_id, text)
+        if result["ok"]:
+            return result
         if attempt < retries - 1:
             delay = 1.0 * (2**attempt)
             logger.info("[HOOKS] telegram: send retry %d/%d after %.0fs", attempt + 2, retries, delay)
             time.sleep(delay)
-    return False
+    return {"ok": False}
 
 
 def handle(hook_data: dict) -> dict:
@@ -394,16 +541,19 @@ def handle(hook_data: dict) -> dict:
         pending_data = json.loads(pending_file.read_text(encoding="utf-8"))
     except (json.JSONDecodeError, OSError) as e:
         logger.error("[HOOKS] telegram: failed to read pending: %s", e)
-        pending_file.unlink(missing_ok=True)
+        if not _in_mirror_dir(pending_file):
+            pending_file.unlink(missing_ok=True)
         return {"stdout": "", "exit_code": 0}
 
+    is_mirror = pending_data.get("mirror", False)
     chat_id = pending_data.get("chat_id")
     bot_token = pending_data.get("bot_token")
     processing_message_id = pending_data.get("processing_message_id")
 
     if not chat_id or not bot_token:
         logger.error("[HOOKS] telegram: missing chat_id or bot_token in pending")
-        pending_file.unlink(missing_ok=True)
+        if not is_mirror:
+            pending_file.unlink(missing_ok=True)
         return {"stdout": "", "exit_code": 0}
 
     response_text = _extract_response(hook_data, transcript_path, pending_data)
@@ -417,11 +567,12 @@ def handle(hook_data: dict) -> dict:
     chunks = chunk_text(response_text)
     logger.info("[HOOKS] telegram: sending %d chunk(s) (logs_active=%s)", len(chunks), logs_were_active)
 
-    all_sent = _deliver_chunks(chunks, bot_token, chat_id, processing_message_id, logs_were_active)
+    all_sent, chunk_results = _deliver_chunks(chunks, bot_token, chat_id, processing_message_id, logs_were_active)
+
+    _write_delivery_log(response_text, chunks, chunk_results, session_id)
 
     if all_sent:
-        pending_file.unlink(missing_ok=True)
-        logger.info("[HOOKS] telegram: response delivered, pending cleaned")
+        _advance_pending(pending_file, pending_data, transcript_path)
     else:
         logger.error("[HOOKS] telegram: delivery failed — keeping pending for retry")
 
@@ -430,6 +581,9 @@ def handle(hook_data: dict) -> dict:
 
 def _extract_response(hook_data: dict, transcript_path: str, pending_data: dict) -> str | None:
     """Try JSONL transcript extraction with retries, fall back to last_assistant_message."""
+    if pending_data.get("mirror"):
+        return _extract_mirror_response(transcript_path, pending_data)
+
     response_text = None
 
     if transcript_path:
@@ -446,7 +600,7 @@ def _extract_response(hook_data: dict, transcript_path: str, pending_data: dict)
                 logger.info("[HOOKS] telegram: JSONL retry %.1fs (attempt %d/3)", delay, attempt + 1)
                 time.sleep(delay)
 
-    if not response_text:
+    if not response_text and not pending_data.get("delivered"):
         response_text = (hook_data.get("last_assistant_message") or "").strip()
         if response_text:
             logger.info("[HOOKS] telegram: using last_assistant_message fallback (%d chars)", len(response_text))
@@ -454,6 +608,23 @@ def _extract_response(hook_data: dict, transcript_path: str, pending_data: dict)
     return response_text or None
 
 
+def _extract_mirror_response(transcript_path: str, pending_data: dict) -> str | None:
+    """Extract all new turns for mirror delivery with retries."""
+    if not transcript_path:
+        return None
+    start_line = pending_data.get("transcript_line_after", 0)
+    for attempt in range(3):
+        result = extract_mirror_turn(transcript_path, start_line)
+        if result:
+            logger.info("[HOOKS] telegram: mirror extraction: %d chars (attempt %d)", len(result), attempt + 1)
+            return result
+        if attempt < 2:
+            delay = [0.2, 0.5][attempt]
+            logger.info("[HOOKS] telegram: mirror retry %.1fs (attempt %d/3)", delay, attempt + 1)
+            time.sleep(delay)
+    return None
+
+
 def _prepend_branch_prefix(text: str) -> str:
     """Prepend @branch identifier so user knows which branch responded."""
     try:
@@ -486,22 +657,110 @@ def _deliver_chunks(
     chat_id: int,
     processing_message_id: int | None,
     logs_were_active: bool,
-) -> bool:
-    """Send all response chunks to Telegram. Returns True if all succeeded."""
+) -> tuple[bool, list[dict]]:
+    """Send all response chunks to Telegram. Returns (all_sent, per-chunk results)."""
+    chunk_results: list[dict] = []
     all_sent = True
+    single = len(chunks) == 1
+
     for i, chunk in enumerate(chunks):
-        if i == 0 and processing_message_id and not logs_were_active:
-            text = f"[1/{len(chunks)}]\n{chunk}" if len(chunks) > 1 else chunk
-            if not edit_telegram_message(bot_token, chat_id, processing_message_id, text):
-                if not _send_with_retry(bot_token, chat_id, text):
+        if i == 0 and processing_message_id:
+            if single and not logs_were_active:
+                result = edit_telegram_message(bot_token, chat_id, processing_message_id, chunk)
+                if result["ok"]:
+                    chunk_results.append({"idx": i, "method": "edit", **result})
+                    continue
+                result = _send_with_retry(bot_token, chat_id, chunk)
+                chunk_results.append({"idx": i, "method": "send", **result})
+                if not result["ok"]:
                     all_sent = False
-        elif i == 0 and processing_message_id and logs_were_active:
+                continue
             edit_telegram_message(bot_token, chat_id, processing_message_id, "Done.")
-            text = f"[1/{len(chunks)}]\n{chunk}" if len(chunks) > 1 else chunk
-            if not _send_with_retry(bot_token, chat_id, text):
-                all_sent = False
+
+        prefix = f"[{i + 1}/{len(chunks)}]\n" if not single else ""
+        result = _send_with_retry(bot_token, chat_id, prefix + chunk)
+        chunk_results.append({"idx": i, "method": "send", **result})
+        if not result["ok"]:
+            all_sent = False
+
+    return all_sent, chunk_results
+
+
+def _advance_pending(pending_file: Path, pending_data: dict, transcript_path: str) -> None:
+    """Advance transcript cursor so later Stops can deliver new text."""
+    is_mirror = pending_data.get("mirror", False)
+    if not transcript_path:
+        if not is_mirror:
+            pending_file.unlink(missing_ok=True)
+        logger.info("[HOOKS] telegram: no transcript — pending %s", "kept (mirror)" if is_mirror else "removed")
+        return
+    try:
+        line_count = 0
+        with open(transcript_path, encoding="utf-8") as f:
+            for _ in f:
+                line_count += 1
+        pending_data["transcript_line_after"] = line_count
+        pending_data["delivered"] = True
+        pending_file.write_text(json.dumps(pending_data, indent=2), encoding="utf-8")
+        logger.info("[HOOKS] telegram: cursor advanced to line %d", line_count)
+    except OSError as e:
+        logger.warning("[HOOKS] telegram: cursor advance failed: %s", e)
+        if not is_mirror:
+            pending_file.unlink(missing_ok=True)
+
+
+def _write_delivery_log(intended_text: str, chunks: list[str], chunk_results: list[dict], session_id: str) -> None:
+    """Write JSONL record documenting what was delivered to Telegram."""
+    intended_sha = hashlib.sha256(intended_text.encode("utf-8")).hexdigest()[:16]
+
+    delivered_parts = []
+    for cr in chunk_results:
+        text = cr.get("text") or ""
+        text = re.sub(r"^\[\d+/\d+\]\n", "", text)
+        delivered_parts.append(text)
+    delivered_concat = "\n\n".join(delivered_parts)
+    delivered_sha = hashlib.sha256(delivered_concat.encode("utf-8")).hexdigest()[:16]
+
+    all_ok = all(cr.get("ok") for cr in chunk_results)
+    match = all_ok and intended_sha == delivered_sha
+
+    culprit = None
+    if not match:
+        failed = [cr["idx"] for cr in chunk_results if not cr.get("ok")]
+        if failed:
+            culprit = f"delivery_failed: chunks {failed}"
+        elif abs(len(intended_text) - len(delivered_concat)) > max(len(intended_text) * 0.1, 20):
+            culprit = f"length_mismatch: intended={len(intended_text)} delivered={len(delivered_concat)}"
         else:
-            prefix = f"[{i + 1}/{len(chunks)}]\n" if len(chunks) > 1 else ""
-            if not _send_with_retry(bot_token, chat_id, prefix + chunk):
-                all_sent = False
-    return all_sent
+            culprit = "formatting_conversion"
+
+    record = {
+        "ts": time.time(),
+        "session": session_id[:8] if session_id else "",
+        "intended_text": intended_text,
+        "intended_sha256": intended_sha,
+        "intended_len": len(intended_text),
+        "chunks": [
+            {
+                "idx": cr.get("idx"),
+                "method": cr.get("method"),
+                "message_id": cr.get("message_id"),
+                "ok": cr.get("ok"),
+                "returned_len": len(cr.get("text") or ""),
+            }
+            for cr in chunk_results
+        ],
+        "delivered_concat": delivered_concat,
+        "delivered_sha256": delivered_sha,
+        "delivered_len": len(delivered_concat),
+        "match": match,
+    }
+    if culprit:
+        record["culprit"] = culprit
+
+    try:
+        _DELIVERY_LOG.parent.mkdir(parents=True, exist_ok=True)
+        with open(_DELIVERY_LOG, "a", encoding="utf-8") as f:
+            f.write(json.dumps(record) + "\n")
+    except OSError as e:
+        logger.warning("[HOOKS] telegram: delivery log write failed: %s", e)
diff --git a/src/aipass/hooks/apps/handlers/security/presence_gate.py b/src/aipass/hooks/apps/handlers/security/presence_gate.py
new file mode 100644
index 00000000..36d5a688
--- /dev/null
+++ b/src/aipass/hooks/apps/handlers/security/presence_gate.py
@@ -0,0 +1,97 @@
+# =================== AIPass ====================
+# Name: presence_gate.py
+# Version: 2.0.0
+# Description: Single-session gate — blocks duplicate Claude runtimes per branch
+# Branch: hooks
+# Layer: apps/handlers/security
+# Created: 2026-06-29
+# Modified: 2026-06-30
+# =============================================
+
+"""Single-session gate — blocks duplicate Claude runtimes per branch.
+
+Sources truth from CC-native ~/.claude/sessions/<pid>.json (resume-aware,
+exit-aware) instead of PRESENCE.central.json. Resume-aware because /resume
+keeps the same PID; exit-aware because CC deletes the file on clean exit.
+
+Fires on UserPromptSubmit: checks CC sessions for another live brain in the
+same branch. If occupied by a different PID, blocks. If free, allows.
+
+handle_stop is a no-op (Stop fires every turn, not just session end; CC-native
+session files handle cleanup on exit).
+
+Skips sub-agents and dispatched/daemon session types.
+
+PRESENCE.central.json + presence.py are preserved (not deleted) but the guard
+no longer sources truth from them.
+"""
+
+import importlib
+import json
+import os
+from pathlib import Path
+
+from aipass.prax.apps.modules.logger import system_logger as logger
+
+_ALLOW = {"exit_code": 0, "stdout": ""}
+_NON_BLOCKING_SESSION_TYPES = frozenset({"dispatched", "daemon"})
+
+
+def _resolve_branch(hook_data: dict) -> str:
+    """Resolve the branch name from hook_data's cwd (session dir, not process cwd)."""
+    cwd = hook_data.get("cwd", "") or str(Path.cwd())
+    search = Path(cwd).resolve()
+    while search.parent != search:
+        if (search / ".trinity").is_dir() or (search / "apps").is_dir():
+            return search.name
+        if (search / "pyproject.toml").exists() or (search / ".git").is_dir():
+            break
+        search = search.parent
+    return Path(cwd).name
+
+
+def handle(hook_data: dict) -> dict:
+    """UserPromptSubmit gate — enforce one live session per branch.
+
+    Sources truth from CC-native ~/.claude/sessions/<pid>.json.
+    Resume-aware: /resume keeps the same PID, so exclude_pid correctly
+    identifies re-entry. Exit-aware: CC deletes the file on clean exit.
+    """
+    try:
+        agent_type = hook_data.get("agent_type", "")
+        if agent_type and agent_type != "main":
+            return _ALLOW
+
+        session_type = os.environ.get("AIPASS_SESSION_TYPE", "interactive")
+        if session_type in _NON_BLOCKING_SESSION_TYPES:
+            return _ALLOW
+
+        branch = _resolve_branch(hook_data)
+        branch_cwd = hook_data.get("cwd", "") or str(Path.cwd())
+
+        presence = importlib.import_module("aipass.hooks.apps.modules.presence")
+        our_pid = presence._resolve_session_pid()
+
+        cc_sessions = importlib.import_module("aipass.hooks.apps.modules.cc_sessions")
+        occupant = cc_sessions.find_occupant(branch_cwd, exclude_pid=our_pid)
+
+        if occupant is None:
+            return _ALLOW
+
+        occ_pid = occupant.get("pid", "?")
+        occ_name = occupant.get("name", "")
+        reason = f"{branch} already live at PID {occ_pid}{f' ({occ_name})' if occ_name else ''} — attach, do not spawn."
+        logger.warning("[presence_gate] BLOCKED: %s", reason)
+        return {
+            "exit_code": 2,
+            "stdout": json.dumps({"decision": "block", "reason": reason}),
+            "sound": "presence gate",
+        }
+    except Exception as exc:
+        logger.warning("[presence_gate] gate error (allowing): %s", exc)
+        return _ALLOW
+
+
+def handle_stop(hook_data: dict) -> dict:
+    """No-op on Stop. CC-native session files handle cleanup on exit."""
+    return _ALLOW
diff --git a/src/aipass/hooks/apps/modules/cc_sessions.py b/src/aipass/hooks/apps/modules/cc_sessions.py
new file mode 100644
index 00000000..f8bd872b
--- /dev/null
+++ b/src/aipass/hooks/apps/modules/cc_sessions.py
@@ -0,0 +1,148 @@
+# =================== AIPass ====================
+# Name: cc_sessions.py
+# Version: 1.0.0
+# Description: Read CC-native session files for active-session discovery
+# Branch: hooks
+# Layer: apps/modules
+# Created: 2026-06-30
+# Modified: 2026-06-30
+# =============================================
+
+"""Read Claude Code native session files (~/.claude/sessions/<pid>.json).
+
+CC maintains one JSON file per running session at ~/.claude/sessions/<pid>.json.
+These are resume-aware (sessionId updated on /resume), exit-aware (deleted on
+clean exit, stale-swept by CC itself), and the authoritative source of which
+sessions are live for a given working directory.
+
+Used by presence_gate to source truth instead of PRESENCE.central.json.
+"""
+
+import json
+import os
+from pathlib import Path
+
+from aipass.cli.apps.modules import err_console
+from aipass.prax.apps.modules.logger import system_logger as logger
+
+CONSOLE = err_console
+
+CC_SESSIONS_DIR = Path.home() / ".claude" / "sessions"
+
+
+def _is_pid_alive(pid: int) -> bool:
+    """Check if a process with the given PID exists."""
+    if pid <= 1:
+        return False
+    try:
+        os.kill(pid, 0)
+        return True
+    except ProcessLookupError:
+        logger.info("[CC_SESSIONS] PID %d not found (dead)", pid)
+        return False
+    except PermissionError:
+        logger.info("[CC_SESSIONS] PID %d exists but permission denied — treating as alive", pid)
+        return True
+    except OSError as exc:
+        logger.info("[CC_SESSIONS] PID %d os.kill failed: %s — treating as dead", pid, exc)
+        return False
+
+
+def read_all_sessions() -> list[dict]:
+    """Read all CC session PID files. Returns list of session dicts."""
+    if not CC_SESSIONS_DIR.is_dir():
+        return []
+    sessions = []
+    for f in CC_SESSIONS_DIR.iterdir():
+        if not f.name.endswith(".json") or not f.stem.isdigit():
+            continue
+        try:
+            data = json.loads(f.read_text(encoding="utf-8"))
+            sessions.append(data)
+        except (json.JSONDecodeError, OSError) as exc:
+            logger.info("[CC_SESSIONS] Failed to read %s: %s", f, exc)
+    return sessions
+
+
+def find_live_for_cwd(cwd: str) -> list[dict]:
+    """Find all live CC sessions whose cwd matches the given directory.
+
+    Compares resolved paths for robustness (symlinks, trailing slashes).
+    Only returns sessions whose PID is still alive.
+    """
+    target = str(Path(cwd).resolve())
+    live = []
+    for session in read_all_sessions():
+        session_cwd = session.get("cwd", "")
+        if not session_cwd:
+            continue
+        if str(Path(session_cwd).resolve()) != target:
+            continue
+        pid = session.get("pid")
+        if pid and _is_pid_alive(pid):
+            live.append(session)
+        else:
+            logger.info(
+                "[CC_SESSIONS] Stale session file for PID %s at %s",
+                pid,
+                session_cwd,
+            )
+    return live
+
+
+def find_occupant(cwd: str, exclude_pid: int | None = None) -> dict | None:
+    """Find a live CC session occupying the given cwd, excluding our own PID.
+
+    Returns the first occupant session dict, or None if the branch is free.
+    This is resume-aware: /resume keeps the same PID, so exclude_pid correctly
+    identifies re-entry.
+    """
+    for session in find_live_for_cwd(cwd):
+        if exclude_pid is not None and session.get("pid") == exclude_pid:
+            continue
+        return session
+    return None
+
+
+# =============================================================================
+# MODULE INTERFACE (drone @hooks routing)
+# =============================================================================
+
+
+def print_introspection():
+    """Print CC session state for drone routing."""
+    CONSOLE.print("[bold cyan]cc_sessions[/bold cyan] Module")
+    CONSOLE.print(f"  Sessions dir: {CC_SESSIONS_DIR}")
+    try:
+        sessions = read_all_sessions()
+        if not sessions:
+            CONSOLE.print("  No CC session files found")
+        else:
+            for s in sessions:
+                pid = s.get("pid", "?")
+                cwd = s.get("cwd", "?")
+                kind = s.get("kind", "?")
+                name = s.get("name", "")
+                alive = _is_pid_alive(pid) if isinstance(pid, int) else False
+                status = "[green]live[/green]" if alive else "[dim]stale[/dim]"
+                label = f" ({name})" if name else ""
+                CONSOLE.print(f"  PID {pid}{label}: {Path(cwd).name}  kind={kind}  {status}")
+    except Exception as exc:
+        logger.info("[CC_SESSIONS] introspection error: %s", exc)
+        CONSOLE.print(f"  Error reading sessions: {exc}")
+
+
+def handle_command(command: str, args: list) -> bool:
+    """Route cc_sessions commands from drone @hooks."""
+    if command in ("--help", "-h", "help"):
+        CONSOLE.print("[bold cyan]cc_sessions[/bold cyan] — CC-native session file reader")
+        CONSOLE.print()
+        CONSOLE.print("  drone @hooks cc_sessions    Show live CC sessions")
+        return True
+
+    if command == "cc_sessions":
+        if not args:
+            print_introspection()
+            return True
+
+    return False
diff --git a/src/aipass/hooks/apps/modules/engine.py b/src/aipass/hooks/apps/modules/engine.py
index c46727aa..3c8d936f 100644
--- a/src/aipass/hooks/apps/modules/engine.py
+++ b/src/aipass/hooks/apps/modules/engine.py
@@ -89,17 +89,17 @@ def _matches(matcher: str, value: str) -> bool:
     return value in matcher.split("|")
 
 
-def dispatch(event_type: str, stdin_data: str, config: dict) -> str:
-    """Core dispatch — run hooks for event, return merged stdout."""
+def dispatch(event_type: str, stdin_data: str, config: dict) -> tuple[str, int]:
+    """Core dispatch — run hooks for event, return (merged_stdout, exit_code)."""
     if not config.get("hooks_enabled", True):
         logger.info("[HOOKS] all hooks disabled")
         _log({"ts": time.time(), "event": event_type, "action": "all_hooks_disabled"})
-        return ""
+        return "", 0
 
     event_hooks = config.get(event_type, {})
     if not event_hooks:
         _log({"ts": time.time(), "event": event_type, "action": "no_hooks_configured"})
-        return ""
+        return "", 0
 
     match_value = ""
     parsed = {}
@@ -196,7 +196,7 @@ def dispatch(event_type: str, stdin_data: str, config: dict) -> str:
                         "total_ms": round(total_ms, 1),
                     }
                 )
-                return result["stdout"]
+                return result["stdout"], 2
 
             logger.error(
                 "[HOOKS] %s.%s CRASHED exit=2: %s",
@@ -229,7 +229,7 @@ def dispatch(event_type: str, stdin_data: str, config: dict) -> str:
         }
     )
 
-    return "\n".join(outputs)
+    return "\n".join(outputs), 0
 
 
 # =============================================================================
diff --git a/src/aipass/hooks/apps/modules/presence.py b/src/aipass/hooks/apps/modules/presence.py
new file mode 100644
index 00000000..569af348
--- /dev/null
+++ b/src/aipass/hooks/apps/modules/presence.py
@@ -0,0 +1,416 @@
+# =================== AIPass ====================
+# Name: presence.py
+# Version: 1.0.0
+# Description: Branch presence service — claim/release/refresh for .ai_central/PRESENCE.central.json
+# Branch: hooks
+# Layer: apps/modules
+# Created: 2026-06-29
+# Modified: 2026-06-29
+# =============================================
+
+"""Branch presence service for concurrent session detection.
+
+Manages a shared PRESENCE.central.json in .ai_central/ at the AIPass project root.
+Each branch can claim presence (one live session per branch), detect stale holders
+via PID liveness + /proc/cwd verification, and release on exit.
+
+File locking uses flock (POSIX) / msvcrt (Windows) to prevent concurrent corruption.
+"""
+
+import json
+import os
+import sys
+from contextlib import contextmanager
+from datetime import datetime
+from pathlib import Path
+
+from aipass.cli.apps.modules import err_console
+from aipass.prax.apps.modules.logger import system_logger as logger
+
+CONSOLE = err_console
+
+# Cross-platform flock
+if sys.platform == "win32":
+    import msvcrt
+else:
+    import fcntl
+
+
+# ---------------------------------------------------------------------------
+# Path resolution
+# ---------------------------------------------------------------------------
+
+
+def _find_ai_central() -> Path:
+    """Walk up from this file to find the directory containing .ai_central/."""
+    current = Path(__file__).resolve().parent
+    for _ in range(20):  # safety cap
+        candidate = current / ".ai_central"
+        if candidate.is_dir():
+            return candidate
+        if current.parent == current:
+            break
+        current = current.parent
+    raise FileNotFoundError("Cannot locate .ai_central/ directory from presence module")
+
+
+_PRESENCE_FILE_NAME = "PRESENCE.central.json"
+_LOCK_FILE_NAME = ".presence.lock"
+
+
+def _presence_path() -> Path:
+    """Return path to the PRESENCE.central.json file."""
+    return _find_ai_central() / _PRESENCE_FILE_NAME
+
+
+def _lock_path() -> Path:
+    """Return path to the .presence.lock file."""
+    return _find_ai_central() / _LOCK_FILE_NAME
+
+
+# ---------------------------------------------------------------------------
+# File locking context manager
+# ---------------------------------------------------------------------------
+
+
+def _release_lock_fd(lock_fd) -> None:
+    """Release and close a lock file descriptor."""
+    try:
+        if sys.platform == "win32":
+            msvcrt.locking(lock_fd.fileno(), msvcrt.LK_UNLCK, 1)
+        else:
+            fcntl.flock(lock_fd.fileno(), fcntl.LOCK_UN)
+        lock_fd.close()
+    except Exception as exc:
+        logger.warning("[PRESENCE] lock release failed: %s", exc)
+        try:
+            lock_fd.close()
+        except Exception as close_exc:
+            logger.warning("[PRESENCE] lock file close failed: %s", close_exc)
+
+
+@contextmanager
+def _presence_lock():
+    """Acquire exclusive lock on the presence file for read-modify-write."""
+    lock_file = _lock_path()
+    lock_fd = None
+    try:
+        lock_fd = open(lock_file, "w", encoding="utf-8")
+        if sys.platform == "win32":
+            msvcrt.locking(lock_fd.fileno(), msvcrt.LK_LOCK, 1)
+        else:
+            fcntl.flock(lock_fd.fileno(), fcntl.LOCK_EX)
+        yield
+    finally:
+        if lock_fd is not None:
+            _release_lock_fd(lock_fd)
+
+
+# ---------------------------------------------------------------------------
+# JSON read/write helpers
+# ---------------------------------------------------------------------------
+
+
+def _read_presence() -> dict:
+    """Read the presence JSON. Returns empty dict if missing or corrupt."""
+    fp = _presence_path()
+    if not fp.exists():
+        return {}
+    try:
+        return json.loads(fp.read_text(encoding="utf-8"))
+    except (json.JSONDecodeError, OSError) as exc:
+        logger.warning("[PRESENCE] Failed to read %s: %s", fp, exc)
+        return {}
+
+
+def _write_presence(data: dict) -> None:
+    """Write the presence JSON."""
+    fp = _presence_path()
+    fp.parent.mkdir(parents=True, exist_ok=True)
+    fp.write_text(json.dumps(data, indent=2), encoding="utf-8")
+
+
+# ---------------------------------------------------------------------------
+# Session PID resolution
+# ---------------------------------------------------------------------------
+
+
+def _read_proc_comm(pid: int) -> str:
+    """Read /proc/<pid>/comm. Returns empty string on failure."""
+    try:
+        return Path(f"/proc/{pid}/comm").read_text().strip()
+    except OSError as exc:
+        logger.info("[PRESENCE] Cannot read /proc/%d/comm: %s", pid, exc)
+        return ""
+
+
+def _read_proc_ppid(pid: int) -> int | None:
+    """Read PPid from /proc/<pid>/status. Returns None on failure."""
+    try:
+        for line in Path(f"/proc/{pid}/status").read_text().splitlines():
+            if line.startswith("PPid:"):
+                return int(line.split()[1])
+    except OSError as exc:
+        logger.info("[PRESENCE] Cannot read /proc/%d/status: %s", pid, exc)
+    return None
+
+
+def _resolve_session_pid() -> int | None:
+    """Walk the parent process chain to find the persistent claude session PID.
+
+    The hook runs as an ephemeral subprocess — os.getpid() gives a PID that dies
+    in milliseconds. The owning claude session is a parent process with comm=claude.
+    Linux only (/proc). Returns None on non-Linux or if no claude ancestor found.
+    """
+    if sys.platform != "linux":
+        return None
+    pid = os.getpid()
+    ancestors = []
+    for _ in range(12):
+        comm = _read_proc_comm(pid)
+        if not comm:
+            break
+        ancestors.append(f"{pid}:{comm}")
+        if comm == "claude":
+            logger.info("[PRESENCE] Resolved session PID: %d (chain: %s)", pid, " -> ".join(ancestors))
+            return pid
+        ppid = _read_proc_ppid(pid)
+        if not ppid or ppid == pid:
+            break
+        pid = ppid
+    logger.info("[PRESENCE] No claude ancestor found (chain: %s)", " -> ".join(ancestors))
+    return None
+
+
+# ---------------------------------------------------------------------------
+# Liveness detection
+# ---------------------------------------------------------------------------
+
+
+def _is_pid_alive(pid: int) -> bool:
+    """Check if a process with the given PID exists."""
+    try:
+        os.kill(pid, 0)
+        return True
+    except ProcessLookupError:
+        logger.info("[PRESENCE] PID %d not found (dead)", pid)
+        return False
+    except PermissionError:
+        logger.info("[PRESENCE] PID %d exists but permission denied — treating as alive", pid)
+        return True
+    except OSError as exc:
+        logger.info("[PRESENCE] PID %d os.kill failed: %s — treating as dead", pid, exc)
+        return False
+
+
+def _cwd_matches(pid: int, expected_dir: str) -> bool:
+    """Check if the process CWD matches the expected branch directory.
+
+    Linux only — reads /proc/<pid>/cwd.
+    On non-Linux platforms, returns True (skip the check, rely on os.kill alone).
+    """
+    if sys.platform != "linux":
+        return True
+    try:
+        actual_cwd = os.readlink(f"/proc/{pid}/cwd")
+        return str(Path(actual_cwd).resolve()) == str(Path(expected_dir).resolve())
+    except (OSError, PermissionError):
+        logger.info("[PRESENCE] Cannot read /proc/%d/cwd — treating as stale", pid)
+        return False
+
+
+def _is_holder_alive(entry: dict) -> bool:
+    """Determine if the holder recorded in the presence entry is still alive.
+
+    A holder is alive if:
+      1. The PID exists (os.kill signal 0)
+      2. AND the PID's CWD matches the branch work_dir (Linux /proc check)
+
+    If either check fails, the holder is stale and can be reclaimed.
+    """
+    pid = entry.get("pid")
+    if pid is None:
+        return False
+    if not _is_pid_alive(pid):
+        return False
+    work_dir = entry.get("work_dir", "")
+    if not work_dir:
+        return False
+    return _cwd_matches(pid, work_dir)
+
+
+# ---------------------------------------------------------------------------
+# Public API
+# ---------------------------------------------------------------------------
+
+
+def claim(
+    branch: str,
+    session_id: str = "",
+    session_type: str = "interactive",
+    attach_handle: str = "",
+) -> dict:
+    """Claim presence for a branch.
+
+    Records the persistent claude session PID (resolved via parent chain),
+    not the ephemeral hook subprocess PID. Fails OPEN if no claude ancestor found.
+
+    Returns:
+        {"status": "ACQUIRED"} on success, or
+        {"status": "OCCUPIED", "pid": N, "session_id": "...",
+         "work_dir": "...", "session_type": "..."}
+        when a live session already owns the branch.
+    """
+    session_pid = _resolve_session_pid()
+    if session_pid is None:
+        logger.info("[PRESENCE] No claude session PID resolved — allowing (fail-open)")
+        return {"status": "ACQUIRED"}
+
+    now = datetime.now().strftime("%Y-%m-%dT%H:%M:%S")
+    cwd = os.getcwd()
+
+    with _presence_lock():
+        data = _read_presence()
+        existing = data.get(branch)
+
+        if existing:
+            result = _handle_existing(data, existing, branch, session_pid, now, session_id)
+            if result is not None:
+                return result
+
+        data[branch] = {
+            "pid": session_pid,
+            "session_id": session_id,
+            "work_dir": cwd,
+            "session_type": session_type,
+            "attach_handle": attach_handle,
+            "started": now,
+            "last_seen": now,
+        }
+        _write_presence(data)
+        logger.info("[PRESENCE] Acquired %s (session PID %d)", branch, session_pid)
+        return {"status": "ACQUIRED"}
+
+
+def _handle_existing(
+    data: dict,
+    existing: dict,
+    branch: str,
+    my_pid: int,
+    now: str,
+    session_id: str,
+) -> dict | None:
+    """Handle an existing presence entry. Returns a result dict or None to proceed."""
+    holder_pid = existing.get("pid")
+
+    # Re-entry: same PID already holds it
+    if holder_pid == my_pid:
+        existing["last_seen"] = now
+        existing["session_id"] = session_id or existing.get("session_id", "")
+        _write_presence(data)
+        logger.info("[PRESENCE] Re-entry for %s (PID %d)", branch, my_pid)
+        return {"status": "ACQUIRED"}
+
+    # Check if the holder is still alive
+    if _is_holder_alive(existing):
+        logger.info(
+            "[PRESENCE] %s occupied by PID %d (session_type=%s)",
+            branch,
+            holder_pid,
+            existing.get("session_type", "unknown"),
+        )
+        return {
+            "status": "OCCUPIED",
+            "pid": holder_pid,
+            "session_id": existing.get("session_id", ""),
+            "work_dir": existing.get("work_dir", ""),
+            "session_type": existing.get("session_type", ""),
+        }
+
+    # Stale holder — let caller reclaim
+    logger.info(
+        "[PRESENCE] Stale holder for %s (PID %d) — reclaiming",
+        branch,
+        holder_pid,
+    )
+    return None
+
+
+def release(branch: str) -> bool:
+    """Release presence for a branch. Only the holder session can release its own entry."""
+    session_pid = _resolve_session_pid()
+    if session_pid is None:
+        logger.info("[PRESENCE] Release skipped for %s — no claude session PID resolved", branch)
+        return False
+    with _presence_lock():
+        data = _read_presence()
+        if branch not in data:
+            return False
+        if data[branch].get("pid") != session_pid:
+            logger.info(
+                "[PRESENCE] Release skipped for %s — not our session (ours=%d, holder=%d)",
+                branch,
+                session_pid,
+                data[branch].get("pid", 0),
+            )
+            return False
+        del data[branch]
+        _write_presence(data)
+        logger.info("[PRESENCE] Released %s (session PID %d)", branch, session_pid)
+        return True
+
+
+def refresh(branch: str) -> None:
+    """Update last_seen timestamp for the branch entry."""
+    now = datetime.now().strftime("%Y-%m-%dT%H:%M:%S")
+    with _presence_lock():
+        data = _read_presence()
+        if branch in data:
+            data[branch]["last_seen"] = now
+            _write_presence(data)
+            logger.info("[PRESENCE] Refreshed %s", branch)
+
+
+def read_all() -> dict:
+    """Return the full presence JSON (all branches)."""
+    return _read_presence()
+
+
+# =============================================================================
+# MODULE INTERFACE (drone @hooks routing)
+# =============================================================================
+
+
+def print_introspection() -> None:
+    """Print presence state for drone routing."""
+    CONSOLE.print("[bold cyan]presence[/bold cyan] Module")
+    try:
+        data = _read_presence()
+        if not data:
+            CONSOLE.print("  No branches currently present")
+        else:
+            for branch, entry in data.items():
+                pid = entry.get("pid", "?")
+                stype = entry.get("session_type", "unknown")
+                last = entry.get("last_seen", "?")
+                alive = _is_holder_alive(entry)
+                status = "[green]live[/green]" if alive else "[dim]stale[/dim]"
+                CONSOLE.print(f"  {branch}: PID {pid}  type={stype}  last_seen={last}  {status}")
+    except FileNotFoundError as exc:
+        logger.info("[PRESENCE] introspection: %s", exc)
+        CONSOLE.print("  .ai_central/ not found")
+
+
+def handle_command(command: str, args: list) -> bool:
+    """Route presence commands from drone @hooks."""
+    if command in ("--help", "-h", "help"):
+        CONSOLE.print("[bold cyan]presence[/bold cyan] — Branch presence claim/release service")
+        CONSOLE.print()
+        CONSOLE.print("  drone @hooks presence    Show current presence state for all branches")
+        return True
+
+    if command == "presence":
+        if not args:
+            print_introspection()
+            return True
+    return False
diff --git a/src/aipass/hooks/tests/test_cc_sessions.py b/src/aipass/hooks/tests/test_cc_sessions.py
new file mode 100644
index 00000000..2911c687
--- /dev/null
+++ b/src/aipass/hooks/tests/test_cc_sessions.py
@@ -0,0 +1,152 @@
+"""Tests for CC-native session file reader."""
+
+import json
+import os
+from unittest.mock import patch
+
+from aipass.hooks.apps.modules import cc_sessions
+
+
+class TestIsPidAlive:
+    def test_alive(self):
+        assert cc_sessions._is_pid_alive(os.getpid()) is True
+
+    def test_dead(self):
+        assert cc_sessions._is_pid_alive(999999999) is False
+
+    def test_pid_zero(self):
+        assert cc_sessions._is_pid_alive(0) is False
+
+    def test_pid_one(self):
+        assert cc_sessions._is_pid_alive(1) is False
+
+    def test_permission_error_treated_as_alive(self):
+        with patch("os.kill", side_effect=PermissionError("denied")):
+            assert cc_sessions._is_pid_alive(42) is True
+
+    def test_oserror_treated_as_dead(self):
+        with patch("os.kill", side_effect=OSError("unknown")):
+            assert cc_sessions._is_pid_alive(42) is False
+
+
+class TestReadAllSessions:
+    def test_reads_pid_files(self, tmp_path):
+        session = {"pid": 1234, "sessionId": "abc", "cwd": "/tmp/branch", "kind": "interactive"}
+        (tmp_path / "1234.json").write_text(json.dumps(session))
+        with patch.object(cc_sessions, "CC_SESSIONS_DIR", tmp_path):
+            result = cc_sessions.read_all_sessions()
+        assert len(result) == 1
+        assert result[0]["pid"] == 1234
+
+    def test_skips_non_pid_files(self, tmp_path):
+        (tmp_path / "config.json").write_text("{}")
+        (tmp_path / "abc.json").write_text("{}")
+        with patch.object(cc_sessions, "CC_SESSIONS_DIR", tmp_path):
+            result = cc_sessions.read_all_sessions()
+        assert result == []
+
+    def test_skips_corrupt_json(self, tmp_path):
+        (tmp_path / "999.json").write_text("not json{{{")
+        with patch.object(cc_sessions, "CC_SESSIONS_DIR", tmp_path):
+            result = cc_sessions.read_all_sessions()
+        assert result == []
+
+    def test_empty_dir(self, tmp_path):
+        with patch.object(cc_sessions, "CC_SESSIONS_DIR", tmp_path):
+            result = cc_sessions.read_all_sessions()
+        assert result == []
+
+    def test_missing_dir(self, tmp_path):
+        with patch.object(cc_sessions, "CC_SESSIONS_DIR", tmp_path / "nonexistent"):
+            result = cc_sessions.read_all_sessions()
+        assert result == []
+
+    def test_multiple_sessions(self, tmp_path):
+        for pid in (100, 200, 300):
+            s = {"pid": pid, "sessionId": f"s-{pid}", "cwd": "/tmp", "kind": "interactive"}
+            (tmp_path / f"{pid}.json").write_text(json.dumps(s))
+        with patch.object(cc_sessions, "CC_SESSIONS_DIR", tmp_path):
+            result = cc_sessions.read_all_sessions()
+        assert len(result) == 3
+
+
+class TestFindLiveForCwd:
+    def test_filters_by_cwd(self, tmp_path):
+        s1 = {"pid": os.getpid(), "sessionId": "a", "cwd": "/tmp/hooks", "kind": "interactive"}
+        s2 = {"pid": os.getpid(), "sessionId": "b", "cwd": "/tmp/devpulse", "kind": "interactive"}
+        (tmp_path / f"{os.getpid()}.json").write_text(json.dumps(s1))
+        (tmp_path / "99999.json").write_text(json.dumps(s2))
+        with patch.object(cc_sessions, "CC_SESSIONS_DIR", tmp_path):
+            result = cc_sessions.find_live_for_cwd("/tmp/hooks")
+        assert len(result) == 1
+        assert result[0]["sessionId"] == "a"
+
+    def test_excludes_dead_pids(self, tmp_path):
+        s = {"pid": 999999999, "sessionId": "dead", "cwd": "/tmp/hooks", "kind": "interactive"}
+        (tmp_path / "999999999.json").write_text(json.dumps(s))
+        with patch.object(cc_sessions, "CC_SESSIONS_DIR", tmp_path):
+            result = cc_sessions.find_live_for_cwd("/tmp/hooks")
+        assert result == []
+
+    def test_resolves_paths(self, tmp_path):
+        target = str(tmp_path / "hooks")
+        s = {"pid": os.getpid(), "sessionId": "a", "cwd": target, "kind": "interactive"}
+        (tmp_path / f"{os.getpid()}.json").write_text(json.dumps(s))
+        with patch.object(cc_sessions, "CC_SESSIONS_DIR", tmp_path):
+            result = cc_sessions.find_live_for_cwd(target + "/")
+        assert len(result) == 1
+
+    def test_empty_cwd_skipped(self, tmp_path):
+        s = {"pid": os.getpid(), "sessionId": "a", "cwd": "", "kind": "interactive"}
+        (tmp_path / f"{os.getpid()}.json").write_text(json.dumps(s))
+        with patch.object(cc_sessions, "CC_SESSIONS_DIR", tmp_path):
+            result = cc_sessions.find_live_for_cwd("/tmp/hooks")
+        assert result == []
+
+
+class TestFindOccupant:
+    def test_no_occupant_when_free(self, tmp_path):
+        with patch.object(cc_sessions, "CC_SESSIONS_DIR", tmp_path):
+            result = cc_sessions.find_occupant("/tmp/hooks")
+        assert result is None
+
+    def test_excludes_own_pid(self, tmp_path):
+        my_pid = os.getpid()
+        s = {"pid": my_pid, "sessionId": "mine", "cwd": "/tmp/hooks", "kind": "interactive"}
+        (tmp_path / f"{my_pid}.json").write_text(json.dumps(s))
+        with patch.object(cc_sessions, "CC_SESSIONS_DIR", tmp_path):
+            result = cc_sessions.find_occupant("/tmp/hooks", exclude_pid=my_pid)
+        assert result is None
+
+    def test_finds_other_occupant(self, tmp_path):
+        my_pid = os.getpid()
+        s = {"pid": my_pid, "sessionId": "other", "cwd": "/tmp/hooks", "kind": "interactive"}
+        (tmp_path / f"{my_pid}.json").write_text(json.dumps(s))
+        with patch.object(cc_sessions, "CC_SESSIONS_DIR", tmp_path):
+            result = cc_sessions.find_occupant("/tmp/hooks", exclude_pid=99999)
+        assert result is not None
+        assert result["sessionId"] == "other"
+
+    def test_no_exclude_returns_any_live(self, tmp_path):
+        my_pid = os.getpid()
+        s = {"pid": my_pid, "sessionId": "any", "cwd": "/tmp/hooks", "kind": "interactive"}
+        (tmp_path / f"{my_pid}.json").write_text(json.dumps(s))
+        with patch.object(cc_sessions, "CC_SESSIONS_DIR", tmp_path):
+            result = cc_sessions.find_occupant("/tmp/hooks")
+        assert result is not None
+
+
+class TestIntrospection:
+    def test_print_introspection_no_sessions(self, tmp_path):
+        with patch.object(cc_sessions, "CC_SESSIONS_DIR", tmp_path):
+            cc_sessions.print_introspection()
+
+    def test_handle_command_cc_sessions(self, tmp_path):
+        with patch.object(cc_sessions, "CC_SESSIONS_DIR", tmp_path):
+            assert cc_sessions.handle_command("cc_sessions", []) is True
+
+    def test_handle_command_help(self):
+        assert cc_sessions.handle_command("--help", []) is True
+
+    def test_handle_command_unknown(self):
+        assert cc_sessions.handle_command("unknown", []) is False
diff --git a/src/aipass/hooks/tests/test_engine.py b/src/aipass/hooks/tests/test_engine.py
index 9e0bbf6e..365948d2 100644
--- a/src/aipass/hooks/tests/test_engine.py
+++ b/src/aipass/hooks/tests/test_engine.py
@@ -107,13 +107,15 @@ class TestDispatch:
         config = {"hooks_enabled": False}
         with patch("aipass.hooks.apps.modules.engine._log"):
             result = dispatch("UserPromptSubmit", "{}", config)
-        assert result == ""
+        assert result[0] == ""
+        assert result[1] == 0
 
     def test_no_hooks_for_event_returns_empty(self, mock_logger):
         config = {"hooks_enabled": True}
         with patch("aipass.hooks.apps.modules.engine._log"):
             result = dispatch("UnknownEvent", "{}", config)
-        assert result == ""
+        assert result[0] == ""
+        assert result[1] == 0
 
     def test_disabled_hook_skipped(self, mock_logger):
         config = {
@@ -130,7 +132,8 @@ class TestDispatch:
             with patch("aipass.hooks.apps.modules.engine._run_hook") as mock_run:
                 result = dispatch("PreToolUse", '{"tool_name":"Edit"}', config)
         mock_run.assert_not_called()
-        assert result == ""
+        assert result[0] == ""
+        assert result[1] == 0
 
     def test_matcher_filters_hooks(self, mock_logger):
         config = {
@@ -165,7 +168,8 @@ class TestDispatch:
                 mock_run.return_value = {"exit_code": 0, "stdout": "edit_output", "stderr": "", "elapsed_ms": 10}
                 result = dispatch("PreToolUse", '{"tool_name":"Edit"}', config)
         mock_run.assert_called_once()
-        assert "edit_output" in result
+        assert "edit_output" in result[0]
+        assert result[1] == 0
 
     def test_multiple_hooks_concatenate_output(self, mock_logger):
         config = {
@@ -182,8 +186,9 @@ class TestDispatch:
                     {"exit_code": 0, "stdout": "output_B", "stderr": "", "elapsed_ms": 10},
                 ]
                 result = dispatch("UserPromptSubmit", '{"user_prompt":"test"}', config)
-        assert "output_A" in result
-        assert "output_B" in result
+        assert "output_A" in result[0]
+        assert "output_B" in result[0]
+        assert result[1] == 0
 
     def test_exit2_with_block_json_bails(self, mock_logger):
         config = {
@@ -199,8 +204,9 @@ class TestDispatch:
                 mock_run.return_value = {"exit_code": 2, "stdout": block_json, "stderr": "", "elapsed_ms": 10}
                 result = dispatch("PreToolUse", '{"tool_name":"Edit"}', config)
         assert mock_run.call_count == 1
-        parsed = json.loads(result)
+        parsed = json.loads(result[0])
         assert parsed["decision"] == "block"
+        assert result[1] == 2
 
     def test_exit2_without_json_is_crash_not_block(self, mock_logger):
         config = {
@@ -218,7 +224,8 @@ class TestDispatch:
                 ]
                 result = dispatch("PreToolUse", '{"tool_name":"Edit"}', config)
         assert mock_run.call_count == 2
-        assert "survived" in result
+        assert "survived" in result[0]
+        assert result[1] == 0
 
     def test_hook_with_custom_timeout(self, mock_logger):
         config = {
@@ -261,7 +268,8 @@ class TestDispatch:
             with patch("aipass.hooks.apps.modules.engine._run_hook") as mock_run:
                 mock_run.return_value = {"exit_code": 0, "stdout": "ok", "stderr": "", "elapsed_ms": 5}
                 result = dispatch("UserPromptSubmit", "not json at all{{{", config)
-        assert "ok" in result
+        assert "ok" in result[0]
+        assert result[1] == 0
 
 
 class TestFindProjectConfig:
@@ -448,7 +456,7 @@ class TestExceptionContracts:
     def test_dispatch_with_none_config_event_returns_empty(self, mock_logger):
         with patch("aipass.hooks.apps.modules.engine._log"):
             result = dispatch("Stop", "{}", {"hooks_enabled": True})
-        assert result == ""
+        assert result == ("", 0)
 
     def test_run_hook_timeout_returns_negative_exit(self, mock_subprocess, mock_logger):
         mock_subprocess.side_effect = subprocess.TimeoutExpired("cmd", 30)
@@ -508,10 +516,13 @@ class TestInitProvisioning:
         assert len(lines) == 2
         assert json.loads(lines[0])["existing"] is True
 
-    def test_dispatch_returns_string(self, mock_logger):
+    def test_dispatch_returns_tuple(self, mock_logger):
         with patch("aipass.hooks.apps.modules.engine._log"):
             result = dispatch("Stop", "{}", {"hooks_enabled": True})
-        assert isinstance(result, str)
+        assert isinstance(result, tuple)
+        assert isinstance(result[0], str)
+        assert isinstance(result[1], int)
+        assert result == ("", 0)
 
 
 class TestConftest:
@@ -666,7 +677,8 @@ class TestErrorResilienceExtended:
             with patch("aipass.hooks.apps.modules.engine._run_hook") as mock_run:
                 mock_run.return_value = {"exit_code": 0, "stdout": "ok", "stderr": "", "elapsed_ms": 5}
                 result = dispatch("Stop", "", config)
-        assert "ok" in result
+        assert "ok" in result[0]
+        assert result[1] == 0
 
     def test_config_with_nonexistent_dir(self, temp_test_dir, mock_logger):
         nonexistent = temp_test_dir / "does_not_exist"
diff --git a/src/aipass/hooks/tests/test_presence.py b/src/aipass/hooks/tests/test_presence.py
new file mode 100644
index 00000000..3d551f30
--- /dev/null
+++ b/src/aipass/hooks/tests/test_presence.py
@@ -0,0 +1,536 @@
+"""Tests for the presence service module."""
+
+import json
+import sys
+from contextlib import nullcontext
+from unittest.mock import patch
+
+import pytest
+
+from aipass.hooks.apps.modules import presence
+
+
+@pytest.fixture
+def presence_dir(tmp_path):
+    """Create a temporary .ai_central directory with PRESENCE.central.json."""
+    ai_central = tmp_path / ".ai_central"
+    ai_central.mkdir()
+    return ai_central
+
+
+@pytest.fixture
+def presence_file(presence_dir):
+    """Return path to the presence file."""
+    return presence_dir / "PRESENCE.central.json"
+
+
+@pytest.fixture
+def patch_paths(presence_dir):
+    """Patch _find_ai_central to use the temp directory."""
+    with patch.object(presence, "_find_ai_central", return_value=presence_dir):
+        yield presence_dir
+
+
+@pytest.fixture
+def patch_flock():
+    """Make the presence lock a no-op (avoid real file locking in tests)."""
+    with patch.object(presence, "_presence_lock", side_effect=lambda: nullcontext()):
+        yield
+
+
+def _patch_session_pid(pid):
+    """Patch _resolve_session_pid to return a given PID."""
+    return patch.object(presence, "_resolve_session_pid", return_value=pid)
+
+
+# ── session PID resolution tests ────────────────────────────────────────
+
+
+class TestResolveSessionPid:
+    def test_finds_claude_ancestor(self):
+        comm_map = {100: "python3", 90: "bash", 80: "claude"}
+        ppid_map = {100: 90, 90: 80}
+        with (
+            patch("sys.platform", "linux"),
+            patch("os.getpid", return_value=100),
+            patch.object(presence, "_read_proc_comm", side_effect=lambda p: comm_map.get(p, "")),
+            patch.object(presence, "_read_proc_ppid", side_effect=lambda p: ppid_map.get(p)),
+        ):
+            assert presence._resolve_session_pid() == 80
+
+    def test_no_claude_ancestor_returns_none(self):
+        comm_map = {100: "python3", 90: "bash", 80: "init"}
+        ppid_map = {100: 90, 90: 80, 80: 1}
+        with (
+            patch("sys.platform", "linux"),
+            patch("os.getpid", return_value=100),
+            patch.object(presence, "_read_proc_comm", side_effect=lambda p: comm_map.get(p, "")),
+            patch.object(presence, "_read_proc_ppid", side_effect=lambda p: ppid_map.get(p)),
+        ):
+            assert presence._resolve_session_pid() is None
+
+    def test_non_linux_returns_none(self):
+        with patch("sys.platform", "win32"):
+            assert presence._resolve_session_pid() is None
+
+    def test_proc_read_failure_returns_none(self):
+        with (
+            patch("sys.platform", "linux"),
+            patch("os.getpid", return_value=100),
+            patch.object(presence, "_read_proc_comm", return_value=""),
+        ):
+            assert presence._resolve_session_pid() is None
+
+    def test_direct_claude_process(self):
+        with (
+            patch("sys.platform", "linux"),
+            patch("os.getpid", return_value=100),
+            patch.object(presence, "_read_proc_comm", return_value="claude"),
+        ):
+            assert presence._resolve_session_pid() == 100
+
+
+# ── claim tests ──────────────────────────────────────────────────────────
+
+
+class TestClaim:
+    def test_claim_empty_file(self, patch_paths, patch_flock, presence_file):
+        with _patch_session_pid(1000), patch("os.getcwd", return_value="/tmp/branch"):
+            result = presence.claim("devpulse", session_id="abc")
+        assert result["status"] == "ACQUIRED"
+        data = json.loads(presence_file.read_text())
+        assert data["devpulse"]["pid"] == 1000
+        assert data["devpulse"]["session_id"] == "abc"
+        assert data["devpulse"]["work_dir"] == "/tmp/branch"
+
+    def test_claim_reentry_same_pid(self, patch_paths, patch_flock, presence_file):
+        presence_file.write_text(
+            json.dumps(
+                {
+                    "devpulse": {
+                        "pid": 1000,
+                        "session_id": "old",
+                        "work_dir": "/w",
+                        "session_type": "interactive",
+                        "attach_handle": "",
+                        "started": "2026-01-01T00:00:00",
+                        "last_seen": "2026-01-01T00:00:00",
+                    }
+                }
+            )
+        )
+        with _patch_session_pid(1000), patch("os.getcwd", return_value="/w"):
+            result = presence.claim("devpulse", session_id="new-id")
+        assert result["status"] == "ACQUIRED"
+        data = json.loads(presence_file.read_text())
+        assert data["devpulse"]["session_id"] == "new-id"
+
+    def test_claim_stale_dead_pid(self, patch_paths, patch_flock, presence_file):
+        presence_file.write_text(
+            json.dumps(
+                {
+                    "devpulse": {
+                        "pid": 9999,
+                        "session_id": "old",
+                        "work_dir": "/w",
+                        "session_type": "interactive",
+                        "attach_handle": "",
+                        "started": "2026-01-01T00:00:00",
+                        "last_seen": "2026-01-01T00:00:00",
+                    }
+                }
+            )
+        )
+        with (
+            _patch_session_pid(2000),
+            patch("os.getcwd", return_value="/w2"),
+            patch.object(presence, "_is_pid_alive", return_value=False),
+        ):
+            result = presence.claim("devpulse", session_id="new")
+        assert result["status"] == "ACQUIRED"
+        data = json.loads(presence_file.read_text())
+        assert data["devpulse"]["pid"] == 2000
+
+    def test_claim_occupied_live_pid(self, patch_paths, patch_flock, presence_file):
+        presence_file.write_text(
+            json.dumps(
+                {
+                    "devpulse": {
+                        "pid": 5000,
+                        "session_id": "live",
+                        "work_dir": "/w",
+                        "session_type": "interactive",
+                        "attach_handle": "",
+                        "started": "2026-01-01T00:00:00",
+                        "last_seen": "2026-01-01T00:00:00",
+                    }
+                }
+            )
+        )
+        with (
+            _patch_session_pid(6000),
+            patch("os.getcwd", return_value="/w2"),
+            patch.object(presence, "_is_pid_alive", return_value=True),
+            patch.object(presence, "_cwd_matches", return_value=True),
+        ):
+            result = presence.claim("devpulse", session_id="new")
+        assert result["status"] == "OCCUPIED"
+        assert result["pid"] == 5000
+        assert result["session_type"] == "interactive"
+
+    def test_claim_stale_cwd_mismatch(self, patch_paths, patch_flock, presence_file):
+        presence_file.write_text(
+            json.dumps(
+                {
+                    "devpulse": {
+                        "pid": 5000,
+                        "session_id": "old",
+                        "work_dir": "/original",
+                        "session_type": "interactive",
+                        "attach_handle": "",
+                        "started": "2026-01-01T00:00:00",
+                        "last_seen": "2026-01-01T00:00:00",
+                    }
+                }
+            )
+        )
+        with (
+            _patch_session_pid(6000),
+            patch("os.getcwd", return_value="/new"),
+            patch.object(presence, "_is_pid_alive", return_value=True),
+            patch.object(presence, "_cwd_matches", return_value=False),
+        ):
+            result = presence.claim("devpulse", session_id="new")
+        assert result["status"] == "ACQUIRED"
+
+    def test_claim_no_existing_file(self, patch_paths, patch_flock):
+        with _patch_session_pid(1000), patch("os.getcwd", return_value="/w"):
+            result = presence.claim("hooks")
+        assert result["status"] == "ACQUIRED"
+
+    def test_claim_multiple_branches(self, patch_paths, patch_flock, presence_file):
+        presence_file.write_text(
+            json.dumps(
+                {
+                    "api": {
+                        "pid": 3000,
+                        "session_id": "a",
+                        "work_dir": "/api",
+                        "session_type": "interactive-mirror",
+                        "attach_handle": "",
+                        "started": "2026-01-01T00:00:00",
+                        "last_seen": "2026-01-01T00:00:00",
+                    }
+                }
+            )
+        )
+        with _patch_session_pid(4000), patch("os.getcwd", return_value="/hooks"):
+            result = presence.claim("hooks", session_id="h1")
+        assert result["status"] == "ACQUIRED"
+        data = json.loads(presence_file.read_text())
+        assert "api" in data
+        assert "hooks" in data
+
+    def test_claim_fails_open_when_no_session_pid(self, patch_paths, patch_flock):
+        with _patch_session_pid(None):
+            result = presence.claim("devpulse")
+        assert result["status"] == "ACQUIRED"
+
+    def test_claim_ephemeral_holder_reclaimed(self, patch_paths, patch_flock, presence_file):
+        """Models the real ephemeral-PID scenario: holder PID is dead (hook exited),
+        but a LIVE claude session exists. 2nd session reclaims."""
+        presence_file.write_text(
+            json.dumps(
+                {
+                    "devpulse": {
+                        "pid": 99999,
+                        "session_id": "old",
+                        "work_dir": "/w",
+                        "session_type": "interactive",
+                        "attach_handle": "",
+                        "started": "2026-01-01T00:00:00",
+                        "last_seen": "2026-01-01T00:00:00",
+                    }
+                }
+            )
+        )
+        with (
+            _patch_session_pid(8000),
+            patch("os.getcwd", return_value="/w"),
+            patch.object(presence, "_is_pid_alive", return_value=False),
+        ):
+            result = presence.claim("devpulse", session_id="new")
+        assert result["status"] == "ACQUIRED"
+        data = json.loads(presence_file.read_text())
+        assert data["devpulse"]["pid"] == 8000
+
+
+# ── release tests ────────────────────────────────────────────────────────
+
+
+class TestRelease:
+    def test_release_existing(self, patch_paths, patch_flock, presence_file):
+        presence_file.write_text(
+            json.dumps(
+                {
+                    "devpulse": {
+                        "pid": 1000,
+                        "session_id": "a",
+                        "work_dir": "/w",
+                        "session_type": "interactive",
+                        "attach_handle": "",
+                        "started": "2026-01-01T00:00:00",
+                        "last_seen": "2026-01-01T00:00:00",
+                    }
+                }
+            )
+        )
+        with _patch_session_pid(1000):
+            result = presence.release("devpulse")
+        assert result is True
+        data = json.loads(presence_file.read_text())
+        assert "devpulse" not in data
+
+    def test_release_not_claimed(self, patch_paths, patch_flock, presence_file):
+        presence_file.write_text(json.dumps({}))
+        with _patch_session_pid(1000):
+            result = presence.release("devpulse")
+        assert result is False
+
+    def test_release_wrong_pid_refused(self, patch_paths, patch_flock, presence_file):
+        presence_file.write_text(
+            json.dumps(
+                {
+                    "devpulse": {
+                        "pid": 1000,
+                        "session_id": "a",
+                        "work_dir": "/w",
+                        "session_type": "interactive",
+                        "attach_handle": "",
+                        "started": "2026-01-01T00:00:00",
+                        "last_seen": "2026-01-01T00:00:00",
+                    }
+                }
+            )
+        )
+        with _patch_session_pid(9999):
+            result = presence.release("devpulse")
+        assert result is False
+        data = json.loads(presence_file.read_text())
+        assert "devpulse" in data
+        assert data["devpulse"]["pid"] == 1000
+
+    def test_release_no_session_pid_skips(self, patch_paths, patch_flock, presence_file):
+        presence_file.write_text(
+            json.dumps(
+                {
+                    "devpulse": {
+                        "pid": 1000,
+                        "session_id": "a",
+                        "work_dir": "/w",
+                        "session_type": "interactive",
+                        "attach_handle": "",
+                        "started": "2026-01-01T00:00:00",
+                        "last_seen": "2026-01-01T00:00:00",
+                    }
+                }
+            )
+        )
+        with _patch_session_pid(None):
+            result = presence.release("devpulse")
+        assert result is False
+        data = json.loads(presence_file.read_text())
+        assert "devpulse" in data
+
+    def test_release_preserves_others(self, patch_paths, patch_flock, presence_file):
+        presence_file.write_text(
+            json.dumps(
+                {
+                    "devpulse": {
+                        "pid": 1000,
+                        "session_id": "a",
+                        "work_dir": "/w",
+                        "session_type": "interactive",
+                        "attach_handle": "",
+                        "started": "2026-01-01T00:00:00",
+                        "last_seen": "2026-01-01T00:00:00",
+                    },
+                    "api": {
+                        "pid": 2000,
+                        "session_id": "b",
+                        "work_dir": "/api",
+                        "session_type": "interactive-mirror",
+                        "attach_handle": "",
+                        "started": "2026-01-01T00:00:00",
+                        "last_seen": "2026-01-01T00:00:00",
+                    },
+                }
+            )
+        )
+        with _patch_session_pid(1000):
+            presence.release("devpulse")
+        data = json.loads(presence_file.read_text())
+        assert "api" in data
+        assert "devpulse" not in data
+
+
+# ── refresh tests ────────────────────────────────────────────────────────
+
+
+class TestRefresh:
+    def test_refresh_updates_last_seen(self, patch_paths, patch_flock, presence_file):
+        presence_file.write_text(
+            json.dumps(
+                {
+                    "hooks": {
+                        "pid": 1000,
+                        "session_id": "a",
+                        "work_dir": "/w",
+                        "session_type": "interactive",
+                        "attach_handle": "",
+                        "started": "2026-01-01T00:00:00",
+                        "last_seen": "2026-01-01T00:00:00",
+                    }
+                }
+            )
+        )
+        presence.refresh("hooks")
+        data = json.loads(presence_file.read_text())
+        assert data["hooks"]["last_seen"] != "2026-01-01T00:00:00"
+
+    def test_refresh_nonexistent_noop(self, patch_paths, patch_flock, presence_file):
+        presence_file.write_text(json.dumps({}))
+        presence.refresh("hooks")
+        data = json.loads(presence_file.read_text())
+        assert data == {}
+
+
+# ── read_all tests ───────────────────────────────────────────────────────
+
+
+class TestReadAll:
+    def test_read_all_returns_data(self, patch_paths, patch_flock, presence_file):
+        expected = {
+            "hooks": {
+                "pid": 1000,
+                "session_id": "a",
+                "work_dir": "/w",
+                "session_type": "interactive",
+                "attach_handle": "",
+                "started": "2026-01-01T00:00:00",
+                "last_seen": "2026-01-01T00:00:00",
+            }
+        }
+        presence_file.write_text(json.dumps(expected))
+        result = presence.read_all()
+        assert result == expected
+
+    def test_read_all_empty(self, patch_paths, patch_flock):
+        result = presence.read_all()
+        assert result == {}
+
+
+# ── liveness tests ───────────────────────────────────────────────────────
+
+
+class TestLiveness:
+    def test_is_pid_alive_true(self):
+        with patch("os.kill") as mock_kill:
+            assert presence._is_pid_alive(1234) is True
+            mock_kill.assert_called_once_with(1234, 0)
+
+    def test_is_pid_alive_dead(self):
+        with patch("os.kill", side_effect=ProcessLookupError):
+            assert presence._is_pid_alive(1234) is False
+
+    def test_is_pid_alive_permission_error(self):
+        with patch("os.kill", side_effect=PermissionError):
+            assert presence._is_pid_alive(1234) is True
+
+    def test_cwd_matches_linux(self):
+        with (
+            patch("sys.platform", "linux"),
+            patch("os.readlink", return_value="/tmp/project/src/aipass/hooks"),
+        ):
+            assert presence._cwd_matches(1234, "/tmp/project/src/aipass/hooks") is True
+
+    def test_cwd_mismatch_linux(self):
+        with (
+            patch("sys.platform", "linux"),
+            patch("os.readlink", return_value="/tmp/project/src/aipass/api"),
+        ):
+            assert presence._cwd_matches(1234, "/tmp/project/src/aipass/hooks") is False
+
+    def test_cwd_matches_non_linux_skips(self):
+        with patch("sys.platform", "win32"):
+            assert presence._cwd_matches(1234, "/anything") is True
+
+    def test_cwd_read_fails_treats_as_stale(self):
+        with (
+            patch("sys.platform", "linux"),
+            patch("os.readlink", side_effect=OSError("no proc")),
+        ):
+            assert presence._cwd_matches(1234, "/w") is False
+
+    def test_is_holder_alive_full_check(self):
+        entry = {"pid": 1234, "work_dir": "/w"}
+        with (
+            patch.object(presence, "_is_pid_alive", return_value=True),
+            patch.object(presence, "_cwd_matches", return_value=True),
+        ):
+            assert presence._is_holder_alive(entry) is True
+
+    def test_is_holder_alive_dead_pid(self):
+        entry = {"pid": 1234, "work_dir": "/w"}
+        with patch.object(presence, "_is_pid_alive", return_value=False):
+            assert presence._is_holder_alive(entry) is False
+
+    def test_is_holder_alive_no_pid(self):
+        assert presence._is_holder_alive({}) is False
+
+    def test_is_holder_alive_no_work_dir(self):
+        entry = {"pid": 1234, "work_dir": ""}
+        with patch.object(presence, "_is_pid_alive", return_value=True):
+            assert presence._is_holder_alive(entry) is False
+
+
+# ── proc helpers tests ───────────────────────────────────────────────────
+
+
+class TestProcHelpers:
+    def test_read_proc_comm_success(self, tmp_path):
+        comm_file = tmp_path / "comm"
+        comm_file.write_text("claude\n")
+        with patch("pathlib.Path.__truediv__", return_value=comm_file):
+            pass
+        with patch.object(presence.Path, "__new__", return_value=comm_file):
+            pass
+        result = presence._read_proc_comm(99999999)
+        assert result == "" or isinstance(result, str)
+
+    def test_read_proc_comm_oserror(self):
+        result = presence._read_proc_comm(99999999)
+        assert result == ""
+
+    def test_read_proc_ppid_oserror(self):
+        result = presence._read_proc_ppid(99999999)
+        assert result is None
+
+
+# ── file locking tests ──────────────────────────────────────────────────
+
+
+class TestFileLocking:
+    @pytest.mark.skipif(sys.platform == "win32", reason="fcntl is POSIX-only")
+    def test_presence_lock_acquires_flock(self, patch_paths):
+        with patch("aipass.hooks.apps.modules.presence.fcntl") as mock_fcntl:
+            mock_fcntl.LOCK_EX = 2
+            mock_fcntl.LOCK_UN = 8
+            with presence._presence_lock():
+                pass
+            mock_fcntl.flock.assert_called()
+
+    def test_corrupt_json_returns_empty(self, patch_paths, patch_flock, presence_file):
+        presence_file.write_text("not json {{{")
+        result = presence._read_presence()
+        assert result == {}
diff --git a/src/aipass/hooks/tests/test_presence_gate.py b/src/aipass/hooks/tests/test_presence_gate.py
new file mode 100644
index 00000000..a0cf924f
--- /dev/null
+++ b/src/aipass/hooks/tests/test_presence_gate.py
@@ -0,0 +1,156 @@
+"""Tests for the presence gate handler."""
+
+import json
+import os
+from unittest.mock import MagicMock, patch
+
+from aipass.hooks.apps.handlers.security import presence_gate
+
+
+def _make_mocks(our_pid: int | None = 1000, occupant=None):
+    """Build presence + cc_sessions mocks for the gate."""
+    presence_mock = MagicMock()
+    presence_mock._resolve_session_pid.return_value = our_pid
+
+    cc_mock = MagicMock()
+    cc_mock.find_occupant.return_value = occupant
+
+    def import_router(name):
+        if "presence" in name and "cc_sessions" not in name:
+            return presence_mock
+        if "cc_sessions" in name:
+            return cc_mock
+        raise ImportError(name)
+
+    return presence_mock, cc_mock, import_router
+
+
+_OCCUPANT = {
+    "pid": 5000,
+    "sessionId": "existing-session",
+    "cwd": "/tmp/branch",
+    "kind": "interactive",
+    "name": "hooks-ab",
+}
+
+
+class TestResolveBranch:
+    def test_uses_hook_data_cwd(self, tmp_path):
+        branch_dir = tmp_path / "devpulse"
+        branch_dir.mkdir()
+        (branch_dir / ".trinity").mkdir()
+        assert presence_gate._resolve_branch({"cwd": str(branch_dir)}) == "devpulse"
+
+    def test_walks_up_to_branch_root(self, tmp_path):
+        branch_dir = tmp_path / "hooks"
+        (branch_dir / "apps" / "modules").mkdir(parents=True)
+        sub = branch_dir / "apps" / "modules"
+        assert presence_gate._resolve_branch({"cwd": str(sub)}) == "hooks"
+
+    def test_stops_at_repo_root(self, tmp_path):
+        (tmp_path / ".git").mkdir()
+        assert presence_gate._resolve_branch({"cwd": str(tmp_path)}) == tmp_path.name
+
+    def test_fallback_to_path_cwd_when_no_cwd_in_hook_data(self):
+        result = presence_gate._resolve_branch({})
+        assert isinstance(result, str)
+        assert len(result) > 0
+
+
+class TestHandle:
+    def test_no_occupant_allows(self):
+        _, _, router = _make_mocks(our_pid=1000, occupant=None)
+        with patch.dict(os.environ, {"AIPASS_SESSION_TYPE": "interactive"}, clear=True):
+            with patch("importlib.import_module", side_effect=router):
+                result = presence_gate.handle({})
+        assert result["exit_code"] == 0
+
+    def test_occupant_blocks(self):
+        _, _, router = _make_mocks(our_pid=1000, occupant=_OCCUPANT)
+        with patch.dict(os.environ, {"AIPASS_SESSION_TYPE": "interactive"}, clear=True):
+            with patch("importlib.import_module", side_effect=router):
+                result = presence_gate.handle({})
+        assert result["exit_code"] == 2
+        parsed = json.loads(result["stdout"])
+        assert parsed["decision"] == "block"
+        assert "5000" in parsed["reason"]
+
+    def test_block_includes_session_name(self):
+        _, _, router = _make_mocks(our_pid=1000, occupant=_OCCUPANT)
+        with patch.dict(os.environ, {"AIPASS_SESSION_TYPE": "interactive"}, clear=True):
+            with patch("importlib.import_module", side_effect=router):
+                result = presence_gate.handle({})
+        parsed = json.loads(result["stdout"])
+        assert "hooks-ab" in parsed["reason"]
+
+    def test_subagent_skipped(self):
+        result = presence_gate.handle({"agent_type": "sub"})
+        assert result["exit_code"] == 0
+        assert result["stdout"] == ""
+
+    def test_main_agent_not_skipped(self):
+        _, _, router = _make_mocks(our_pid=1000, occupant=None)
+        with patch.dict(os.environ, {"AIPASS_SESSION_TYPE": "interactive"}, clear=True):
+            with patch("importlib.import_module", side_effect=router):
+                result = presence_gate.handle({"agent_type": "main"})
+        assert result["exit_code"] == 0
+
+    def test_dispatched_session_skipped(self):
+        with patch.dict(os.environ, {"AIPASS_SESSION_TYPE": "dispatched"}, clear=True):
+            result = presence_gate.handle({})
+        assert result["exit_code"] == 0
+        assert result["stdout"] == ""
+
+    def test_daemon_session_skipped(self):
+        with patch.dict(os.environ, {"AIPASS_SESSION_TYPE": "daemon"}, clear=True):
+            result = presence_gate.handle({})
+        assert result["exit_code"] == 0
+        assert result["stdout"] == ""
+
+    def test_exclude_pid_passed_to_find_occupant(self):
+        _, cc_mock, router = _make_mocks(our_pid=1000, occupant=None)
+        with patch.dict(os.environ, {"AIPASS_SESSION_TYPE": "interactive"}, clear=True):
+            with patch("importlib.import_module", side_effect=router):
+                presence_gate.handle({})
+        cc_mock.find_occupant.assert_called_once()
+        assert cc_mock.find_occupant.call_args[1]["exclude_pid"] == 1000
+
+    def test_no_session_pid_allows(self):
+        _, _, router = _make_mocks(our_pid=None, occupant=None)
+        with patch.dict(os.environ, {"AIPASS_SESSION_TYPE": "interactive"}, clear=True):
+            with patch("importlib.import_module", side_effect=router):
+                result = presence_gate.handle({})
+        assert result["exit_code"] == 0
+
+    def test_block_message_includes_branch(self, tmp_path):
+        branch_dir = tmp_path / "devpulse"
+        branch_dir.mkdir()
+        (branch_dir / ".trinity").mkdir()
+        _, _, router = _make_mocks(our_pid=1000, occupant=_OCCUPANT)
+        with patch.dict(os.environ, {"AIPASS_SESSION_TYPE": "interactive"}, clear=True):
+            with patch("importlib.import_module", side_effect=router):
+                result = presence_gate.handle({"cwd": str(branch_dir)})
+        parsed = json.loads(result["stdout"])
+        assert "devpulse" in parsed["reason"]
+        assert "attach" in parsed["reason"].lower()
+
+    def test_gate_error_allows(self):
+        with patch.dict(os.environ, {"AIPASS_SESSION_TYPE": "interactive"}, clear=True):
+            with patch("importlib.import_module", side_effect=ImportError("boom")):
+                result = presence_gate.handle({})
+        assert result["exit_code"] == 0
+
+
+class TestHandleStop:
+    def test_stop_is_noop(self):
+        result = presence_gate.handle_stop({})
+        assert result["exit_code"] == 0
+        assert result["stdout"] == ""
+
+    def test_stop_does_not_call_anything(self):
+        mock = MagicMock()
+        with patch("importlib.import_module", return_value=mock):
+            presence_gate.handle_stop({})
+        mock.release.assert_not_called()
+        mock.claim.assert_not_called()
+        mock.find_occupant.assert_not_called()
diff --git a/src/aipass/hooks/tests/test_session_boot.py b/src/aipass/hooks/tests/test_session_boot.py
new file mode 100644
index 00000000..29a9f168
--- /dev/null
+++ b/src/aipass/hooks/tests/test_session_boot.py
@@ -0,0 +1,212 @@
+"""Tests for session boot wrapper (attach-if-live / start-in-tmux)."""
+
+from unittest.mock import MagicMock, patch
+
+from aipass.hooks.apps.handlers.lifecycle import session_boot
+
+_MOD = "aipass.hooks.apps.handlers.lifecycle.session_boot"
+
+
+class TestResolveClaudeBinary:
+    def test_found_on_path(self):
+        with patch(f"{_MOD}.shutil.which", return_value="/usr/local/bin/claude"):
+            assert session_boot._resolve_claude_binary() == "/usr/local/bin/claude"
+
+    def test_not_found_fallback(self):
+        with patch(f"{_MOD}.shutil.which", return_value=None):
+            assert session_boot._resolve_claude_binary() == "claude"
+
+
+class TestFindTmux:
+    def test_found(self):
+        with patch("shutil.which", return_value="/usr/bin/tmux"):
+            assert session_boot._find_tmux() == "/usr/bin/tmux"
+
+    def test_not_found(self):
+        with patch("shutil.which", return_value=None):
+            assert session_boot._find_tmux() is None
+
+
+class TestTmuxSessionExists:
+    def test_exists(self):
+        with patch(f"{_MOD}.subprocess.run", return_value=MagicMock(returncode=0)):
+            assert session_boot._tmux_session_exists("hooks") is True
+
+    def test_not_exists(self):
+        with patch(f"{_MOD}.subprocess.run", return_value=MagicMock(returncode=1)):
+            assert session_boot._tmux_session_exists("hooks") is False
+
+
+class TestFindTmuxSessionForPid:
+    def test_finds_session(self):
+        output = "1234 hooks\n5678 devpulse\n"
+        with (
+            patch(f"{_MOD}.subprocess.run", return_value=MagicMock(returncode=0, stdout=output)),
+            patch.object(session_boot, "_is_descendant", side_effect=lambda t, a: t == 9999 and a == 1234),
+        ):
+            assert session_boot._find_tmux_session_for_pid(9999) == "hooks"
+
+    def test_not_found(self):
+        output = "1234 hooks\n"
+        with (
+            patch(f"{_MOD}.subprocess.run", return_value=MagicMock(returncode=0, stdout=output)),
+            patch.object(session_boot, "_is_descendant", return_value=False),
+        ):
+            assert session_boot._find_tmux_session_for_pid(9999) is None
+
+    def test_tmux_not_running(self):
+        with patch(f"{_MOD}.subprocess.run", return_value=MagicMock(returncode=1)):
+            assert session_boot._find_tmux_session_for_pid(9999) is None
+
+
+class TestIsDescendant:
+    def test_direct_match(self):
+        assert session_boot._is_descendant(100, 100) is True
+
+    def test_pid_one_not_descendant(self):
+        assert session_boot._is_descendant(1, 999) is False
+
+    def test_proc_walk(self):
+        statuses = {200: "Name:\tpython3\nPPid:\t100\n"}
+        with patch("pathlib.Path.read_text", side_effect=lambda: statuses.get(200, "")):
+            assert session_boot._is_descendant(200, 100) is True
+
+    def test_proc_not_found(self):
+        with patch("pathlib.Path.read_text", side_effect=OSError("no such file")):
+            assert session_boot._is_descendant(200, 100) is False
+
+
+class TestBoot:
+    def test_already_in_tmux_execs_directly(self, tmp_path):
+        with (
+            patch.dict("os.environ", {"TMUX": "/tmp/tmux-1000/default,123,0"}),
+            patch.object(session_boot, "_resolve_claude_binary", return_value="/usr/local/bin/claude"),
+            patch(f"{_MOD}.os.execvp") as mock_exec,
+        ):
+            session_boot.boot(cwd=str(tmp_path))
+        mock_exec.assert_called_once()
+        args = mock_exec.call_args[0]
+        assert args[0] == "/usr/local/bin/claude"
+        assert "--permission-mode" in args[1]
+        assert "bypassPermissions" in args[1]
+
+    def test_already_in_tmux_passes_extra_args(self, tmp_path):
+        with (
+            patch.dict("os.environ", {"TMUX": "/tmp/tmux-1000/default,123,0"}),
+            patch.object(session_boot, "_resolve_claude_binary", return_value="/usr/local/bin/claude"),
+            patch(f"{_MOD}.os.execvp") as mock_exec,
+        ):
+            session_boot.boot(cwd=str(tmp_path), extra_args=["--resume"])
+        args = mock_exec.call_args[0][1]
+        assert "--resume" in args
+
+    def test_no_tmux_errors(self, tmp_path):
+        with (
+            patch.dict("os.environ", {}, clear=True),
+            patch.object(session_boot, "_resolve_claude_binary", return_value="/usr/local/bin/claude"),
+            patch.object(session_boot, "_find_tmux", return_value=None),
+        ):
+            result = session_boot.boot(cwd=str(tmp_path))
+        assert result["exit_code"] == 1
+        assert "tmux not found" in result["error"]
+
+    def test_live_session_in_tmux_attaches(self, tmp_path):
+        live = [{"pid": 1234, "sessionId": "abc", "cwd": str(tmp_path), "name": "hooks-ab"}]
+        with (
+            patch.dict("os.environ", {}, clear=True),
+            patch.object(session_boot, "_resolve_claude_binary", return_value="/usr/local/bin/claude"),
+            patch.object(session_boot, "_find_tmux", return_value="/usr/bin/tmux"),
+            patch.object(session_boot, "_find_live_sessions", return_value=live),
+            patch.object(session_boot, "_find_tmux_session_for_pid", return_value="hooks"),
+            patch(f"{_MOD}.os.execvp") as mock_exec,
+        ):
+            session_boot.boot(cwd=str(tmp_path))
+        mock_exec.assert_called_once_with("tmux", ["tmux", "attach-session", "-t", "hooks"])
+
+    def test_live_session_not_in_tmux_warns(self, tmp_path):
+        live = [{"pid": 1234, "sessionId": "abc", "cwd": str(tmp_path)}]
+        with (
+            patch.dict("os.environ", {}, clear=True),
+            patch.object(session_boot, "_resolve_claude_binary", return_value="/usr/local/bin/claude"),
+            patch.object(session_boot, "_find_tmux", return_value="/usr/bin/tmux"),
+            patch.object(session_boot, "_find_live_sessions", return_value=live),
+            patch.object(session_boot, "_find_tmux_session_for_pid", return_value=None),
+        ):
+            result = session_boot.boot(cwd=str(tmp_path))
+        assert result["exit_code"] == 1
+        assert result["action"] == "warn"
+
+    def test_no_live_session_starts_fresh(self, tmp_path):
+        with (
+            patch.dict("os.environ", {}, clear=True),
+            patch.object(session_boot, "_resolve_claude_binary", return_value="/usr/local/bin/claude"),
+            patch.object(session_boot, "_find_tmux", return_value="/usr/bin/tmux"),
+            patch.object(session_boot, "_find_live_sessions", return_value=[]),
+            patch.object(session_boot, "_tmux_session_exists", return_value=False),
+            patch(f"{_MOD}.os.execvp") as mock_exec,
+        ):
+            session_boot.boot(cwd=str(tmp_path))
+        args = mock_exec.call_args[0]
+        assert args[0] == "tmux"
+        assert "new-session" in args[1]
+        assert "/usr/local/bin/claude" in args[1]
+        assert "--permission-mode" in args[1]
+        assert "bypassPermissions" in args[1]
+
+    def test_stale_tmux_session_killed(self, tmp_path):
+        with (
+            patch.dict("os.environ", {}, clear=True),
+            patch.object(session_boot, "_resolve_claude_binary", return_value="/usr/local/bin/claude"),
+            patch.object(session_boot, "_find_tmux", return_value="/usr/bin/tmux"),
+            patch.object(session_boot, "_find_live_sessions", return_value=[]),
+            patch.object(session_boot, "_tmux_session_exists", return_value=True),
+            patch(f"{_MOD}.subprocess.run") as mock_run,
+            patch(f"{_MOD}.os.execvp"),
+        ):
+            session_boot.boot(cwd=str(tmp_path))
+        kill_calls = [c for c in mock_run.call_args_list if "kill-session" in str(c)]
+        assert len(kill_calls) == 1
+
+    def test_extra_args_passed(self, tmp_path):
+        with (
+            patch.dict("os.environ", {}, clear=True),
+            patch.object(session_boot, "_resolve_claude_binary", return_value="/usr/local/bin/claude"),
+            patch.object(session_boot, "_find_tmux", return_value="/usr/bin/tmux"),
+            patch.object(session_boot, "_find_live_sessions", return_value=[]),
+            patch.object(session_boot, "_tmux_session_exists", return_value=False),
+            patch(f"{_MOD}.os.execvp") as mock_exec,
+        ):
+            session_boot.boot(cwd=str(tmp_path), extra_args=["--resume"])
+        args = mock_exec.call_args[0][1]
+        assert "--resume" in args
+
+
+class TestMain:
+    def test_success(self):
+        with patch.object(session_boot, "boot", return_value={"exit_code": 0, "action": "started"}):
+            session_boot.main()
+
+    def test_failure_exits(self):
+        import pytest
+
+        with (
+            patch.object(session_boot, "boot", return_value={"exit_code": 1, "error": "tmux not found"}),
+            pytest.raises(SystemExit, match="1"),
+        ):
+            session_boot.main()
+
+    def test_passes_sys_argv(self):
+        with (
+            patch.object(session_boot, "boot", return_value={"exit_code": 0}) as mock_boot,
+            patch(f"{_MOD}.sys.argv", ["session_boot", "--resume", "--verbose"]),
+        ):
+            session_boot.main()
+        mock_boot.assert_called_once_with(extra_args=["--resume", "--verbose"])
+
+    def test_no_extra_args_when_no_argv(self):
+        with (
+            patch.object(session_boot, "boot", return_value={"exit_code": 0}) as mock_boot,
+            patch(f"{_MOD}.sys.argv", ["session_boot"]),
+        ):
+            session_boot.main()
+        mock_boot.assert_called_once_with(extra_args=None)
diff --git a/src/aipass/hooks/tests/test_telegram_response.py b/src/aipass/hooks/tests/test_telegram_response.py
index 1d190691..3ca3ff9d 100644
--- a/src/aipass/hooks/tests/test_telegram_response.py
+++ b/src/aipass/hooks/tests/test_telegram_response.py
@@ -1,11 +1,11 @@
 # =================== AIPass ====================
 # Name: test_telegram_response.py
-# Version: 1.0.0
+# Version: 2.0.0
 # Description: Tests for telegram_response notification handler
 # Branch: hooks
 # Layer: tests
 # Created: 2026-06-15
-# Modified: 2026-06-15
+# Modified: 2026-06-29
 # =============================================
 
 """Tests for handlers/notification/telegram_response.py."""
@@ -56,10 +56,10 @@ def _make_pending(tmp_path: Path, name: str = "bot-123.json", **overrides) -> Pa
     return path
 
 
-def _mock_urlopen_ok():
+def _mock_urlopen_ok(message_id=100, text="mocked"):
     """Return a context-manager mock whose read() returns Telegram ok response."""
     resp = MagicMock()
-    resp.read.return_value = json.dumps({"ok": True}).encode()
+    resp.read.return_value = json.dumps({"ok": True, "result": {"message_id": message_id, "text": text}}).encode()
     resp.__enter__ = MagicMock(return_value=resp)
     resp.__exit__ = MagicMock(return_value=False)
     return resp
@@ -74,6 +74,16 @@ def _mock_urlopen_fail():
     return resp
 
 
+def _ok_result(message_id=100, text="mocked"):
+    """Build a successful send/edit result dict."""
+    return {"ok": True, "message_id": message_id, "text": text}
+
+
+def _fail_result():
+    """Build a failed send/edit result dict."""
+    return {"ok": False}
+
+
 # ===========================================================================
 # Layer 1 defense — handle() early returns
 # ===========================================================================
@@ -98,7 +108,7 @@ class TestHandleLayer1Defense:
                 {
                     "hook_event_name": "Stop",
                     "session_id": "abc",
-                    "transcript_path": "/home/user/.claude/sessions/subagents/12345.jsonl",
+                    "transcript_path": str(Path.home() / ".claude/sessions/subagents/12345.jsonl"),
                 }
             )
 
@@ -163,7 +173,6 @@ class TestFindPendingFile:
             patch.dict("os.environ", {}, clear=True),
             patch(f"{MOD}.Path.cwd", return_value=work / "subdir"),
         ):
-            # subdir is relative to work_dir, so it should match
             result = find_pending_file("session-abc")
 
         assert result is not None
@@ -650,7 +659,8 @@ class TestSendToTelegram:
         with patch(LOGGER_PATCH), patch(f"{MOD}.urlopen", return_value=_mock_urlopen_ok()):
             result = send_to_telegram("tok:ABC", 123, "Hello")
 
-        assert result is True
+        assert result["ok"] is True
+        assert result["message_id"] == 100
 
     def test_html_fails_plain_text_fallback_succeeds(self):
         from aipass.hooks.apps.handlers.notification.telegram_response import send_to_telegram
@@ -667,7 +677,7 @@ class TestSendToTelegram:
         with patch(LOGGER_PATCH), patch(f"{MOD}.urlopen", side_effect=urlopen_side_effect):
             result = send_to_telegram("tok:ABC", 123, "Hello **bold**")
 
-        assert result is True
+        assert result["ok"] is True
         assert call_count == 2
 
     def test_html_fails_plain_text_also_fails(self):
@@ -676,7 +686,7 @@ class TestSendToTelegram:
         with patch(LOGGER_PATCH), patch(f"{MOD}.urlopen", side_effect=Exception("network error")):
             result = send_to_telegram("tok:ABC", 123, "Hello")
 
-        assert result is False
+        assert result["ok"] is False
 
     def test_http_error_handling(self):
         from aipass.hooks.apps.handlers.notification.telegram_response import send_to_telegram
@@ -701,7 +711,7 @@ class TestSendToTelegram:
         with patch(LOGGER_PATCH), patch(f"{MOD}.urlopen", side_effect=urlopen_side_effect):
             result = send_to_telegram("tok:ABC", 123, "Hello")
 
-        assert result is False
+        assert result["ok"] is False
 
     def test_url_error_handling(self):
         from aipass.hooks.apps.handlers.notification.telegram_response import send_to_telegram
@@ -719,7 +729,7 @@ class TestSendToTelegram:
         with patch(LOGGER_PATCH), patch(f"{MOD}.urlopen", side_effect=urlopen_side_effect):
             result = send_to_telegram("tok:ABC", 123, "Hello")
 
-        assert result is False
+        assert result["ok"] is False
 
     def test_reply_to_message_id_included(self):
         from aipass.hooks.apps.handlers.notification.telegram_response import send_to_telegram
@@ -735,6 +745,14 @@ class TestSendToTelegram:
 
         assert captured_requests[0]["reply_to_message_id"] == 456
 
+    def test_returns_message_text_from_api(self):
+        from aipass.hooks.apps.handlers.notification.telegram_response import send_to_telegram
+
+        with patch(LOGGER_PATCH), patch(f"{MOD}.urlopen", return_value=_mock_urlopen_ok(text="returned")):
+            result = send_to_telegram("tok:ABC", 123, "Hello")
+
+        assert result["text"] == "returned"
+
 
 # ===========================================================================
 # edit_telegram_message
@@ -750,7 +768,8 @@ class TestEditTelegramMessage:
         with patch(LOGGER_PATCH), patch(f"{MOD}.urlopen", return_value=_mock_urlopen_ok()):
             result = edit_telegram_message("tok:ABC", 123, 789, "Updated text")
 
-        assert result is True
+        assert result["ok"] is True
+        assert result["message_id"] == 100
 
     def test_html_edit_fails_plain_text_fallback(self):
         from aipass.hooks.apps.handlers.notification.telegram_response import edit_telegram_message
@@ -767,7 +786,7 @@ class TestEditTelegramMessage:
         with patch(LOGGER_PATCH), patch(f"{MOD}.urlopen", side_effect=urlopen_side_effect):
             result = edit_telegram_message("tok:ABC", 123, 789, "Updated")
 
-        assert result is True
+        assert result["ok"] is True
 
     def test_both_fail_returns_false(self):
         from aipass.hooks.apps.handlers.notification.telegram_response import edit_telegram_message
@@ -775,7 +794,7 @@ class TestEditTelegramMessage:
         with patch(LOGGER_PATCH), patch(f"{MOD}.urlopen", side_effect=Exception("total failure")):
             result = edit_telegram_message("tok:ABC", 123, 789, "Text")
 
-        assert result is False
+        assert result["ok"] is False
 
     def test_edit_url_uses_editMessageText(self):
         from aipass.hooks.apps.handlers.notification.telegram_response import edit_telegram_message
@@ -800,11 +819,10 @@ class TestEditTelegramMessage:
 class TestHandleIntegration:
     """Full handle() flow integration tests."""
 
-    def test_happy_path_send_and_cleanup(self, tmp_path):
-        """Full flow: pending exists -> extract -> send -> cleanup."""
+    def test_happy_path_send_and_advance(self, tmp_path):
+        """Full flow: pending exists -> extract -> send -> advance cursor."""
         from aipass.hooks.apps.handlers.notification.telegram_response import handle
 
-        # Set up transcript
         transcript = tmp_path / "transcript.jsonl"
         lines = [
             _jsonl_line("user", "Hello"),
@@ -812,7 +830,6 @@ class TestHandleIntegration:
         ]
         transcript.write_text("\n".join(lines), encoding="utf-8")
 
-        # Set up pending file
         pending_dir = tmp_path / "telegram_pending"
         pending_dir.mkdir()
         pending_data = {
@@ -830,6 +847,7 @@ class TestHandleIntegration:
             patch(f"{MOD}.urlopen", return_value=_mock_urlopen_ok()),
             patch(f"{MOD}._check_log_streamer_active", return_value=False),
             patch(f"{MOD}.Path.cwd", return_value=tmp_path),
+            patch(f"{MOD}._write_delivery_log"),
         ):
             result = handle(
                 {
@@ -840,8 +858,10 @@ class TestHandleIntegration:
             )
 
         assert result == {"stdout": "", "exit_code": 0}
-        # Pending should be cleaned up on success
-        assert not pending_file.exists()
+        assert pending_file.exists()
+        updated = json.loads(pending_file.read_text(encoding="utf-8"))
+        assert updated["delivered"] is True
+        assert updated["transcript_line_after"] == 2
 
     def test_send_fails_pending_kept(self, tmp_path):
         """When delivery fails, pending file is kept for retry."""
@@ -872,6 +892,7 @@ class TestHandleIntegration:
             patch(f"{MOD}._check_log_streamer_active", return_value=False),
             patch(f"{MOD}.time.sleep"),
             patch(f"{MOD}.Path.cwd", return_value=tmp_path),
+            patch(f"{MOD}._write_delivery_log"),
         ):
             result = handle(
                 {
@@ -882,8 +903,9 @@ class TestHandleIntegration:
             )
 
         assert result == {"stdout": "", "exit_code": 0}
-        # Pending should still exist
         assert pending_file.exists()
+        updated = json.loads(pending_file.read_text(encoding="utf-8"))
+        assert "delivered" not in updated
 
     def test_no_response_text_pending_kept(self, tmp_path):
         """When no response text is extracted, pending is kept."""
@@ -944,7 +966,6 @@ class TestHandleIntegration:
         pending_file = pending_dir / "bot-1.json"
         pending_file.write_text(json.dumps(pending_data), encoding="utf-8")
 
-        # Import to get the original function reference
         from aipass.hooks.apps.handlers.notification.telegram_response import extract_assistant_response
 
         extract_call_count = 0
@@ -965,6 +986,7 @@ class TestHandleIntegration:
             patch(f"{MOD}._check_log_streamer_active", return_value=False),
             patch(f"{MOD}.time.sleep"),
             patch(f"{MOD}.Path.cwd", return_value=tmp_path),
+            patch(f"{MOD}._write_delivery_log"),
         ):
             result = handle(
                 {
@@ -976,7 +998,9 @@ class TestHandleIntegration:
 
         assert result == {"stdout": "", "exit_code": 0}
         assert extract_call_count >= 2
-        assert not pending_file.exists()
+        assert pending_file.exists()
+        updated = json.loads(pending_file.read_text(encoding="utf-8"))
+        assert updated["delivered"] is True
 
     def test_fallback_to_last_assistant_message(self, tmp_path):
         """When JSONL extraction fails, falls back to last_assistant_message from hook_data."""
@@ -1000,6 +1024,7 @@ class TestHandleIntegration:
             patch(f"{MOD}._check_log_streamer_active", return_value=False),
             patch(f"{MOD}.time.sleep"),
             patch(f"{MOD}.Path.cwd", return_value=tmp_path),
+            patch(f"{MOD}._write_delivery_log"),
         ):
             result = handle(
                 {
@@ -1013,6 +1038,45 @@ class TestHandleIntegration:
         assert result == {"stdout": "", "exit_code": 0}
         assert not pending_file.exists()
 
+    def test_already_delivered_skips_fallback(self, tmp_path):
+        """After first delivery, last_assistant_message fallback is skipped."""
+        from aipass.hooks.apps.handlers.notification.telegram_response import handle
+
+        transcript = tmp_path / "transcript.jsonl"
+        transcript.write_text("", encoding="utf-8")
+
+        pending_dir = tmp_path / "telegram_pending"
+        pending_dir.mkdir()
+        pending_data = {
+            "chat_id": 999,
+            "bot_token": "tok:ABC",
+            "timestamp": time.time(),
+            "work_dir": str(tmp_path),
+            "delivered": True,
+            "transcript_line_after": 5,
+        }
+        pending_file = pending_dir / "bot-1.json"
+        pending_file.write_text(json.dumps(pending_data), encoding="utf-8")
+
+        with (
+            patch(LOGGER_PATCH),
+            patch(f"{MOD}.find_pending_file", return_value=pending_file),
+            patch(f"{MOD}._check_log_streamer_active", return_value=False),
+            patch(f"{MOD}.time.sleep"),
+            patch(f"{MOD}.Path.cwd", return_value=tmp_path),
+        ):
+            result = handle(
+                {
+                    "hook_event_name": "Stop",
+                    "session_id": "session-abc",
+                    "transcript_path": str(transcript),
+                    "last_assistant_message": "Would be a duplicate",
+                }
+            )
+
+        assert result == {"stdout": "", "exit_code": 0}
+        assert pending_file.exists()
+
     def test_missing_chat_id_cleans_pending(self, tmp_path):
         """Pending with missing chat_id is cleaned up."""
         from aipass.hooks.apps.handlers.notification.telegram_response import handle
@@ -1070,10 +1134,10 @@ class TestSendWithRetry:
     def test_success_on_first_try(self):
         from aipass.hooks.apps.handlers.notification.telegram_response import _send_with_retry
 
-        with patch(LOGGER_PATCH), patch(f"{MOD}.send_to_telegram", return_value=True) as mock_send:
+        with patch(LOGGER_PATCH), patch(f"{MOD}.send_to_telegram", return_value=_ok_result()) as mock_send:
             result = _send_with_retry("tok:ABC", 123, "Hello")
 
-        assert result is True
+        assert result["ok"] is True
         assert mock_send.call_count == 1
 
     def test_success_on_retry(self):
@@ -1081,12 +1145,12 @@ class TestSendWithRetry:
 
         with (
             patch(LOGGER_PATCH),
-            patch(f"{MOD}.send_to_telegram", side_effect=[False, True]) as mock_send,
+            patch(f"{MOD}.send_to_telegram", side_effect=[_fail_result(), _ok_result()]) as mock_send,
             patch(f"{MOD}.time.sleep"),
         ):
             result = _send_with_retry("tok:ABC", 123, "Hello")
 
-        assert result is True
+        assert result["ok"] is True
         assert mock_send.call_count == 2
 
     def test_all_retries_fail(self):
@@ -1094,12 +1158,12 @@ class TestSendWithRetry:
 
         with (
             patch(LOGGER_PATCH),
-            patch(f"{MOD}.send_to_telegram", return_value=False) as mock_send,
+            patch(f"{MOD}.send_to_telegram", return_value=_fail_result()) as mock_send,
             patch(f"{MOD}.time.sleep"),
         ):
             result = _send_with_retry("tok:ABC", 123, "Hello", retries=3)
 
-        assert result is False
+        assert result["ok"] is False
         assert mock_send.call_count == 3
 
 
@@ -1139,19 +1203,22 @@ class TestDeliverChunks:
     def test_single_chunk_no_processing_msg(self):
         from aipass.hooks.apps.handlers.notification.telegram_response import _deliver_chunks
 
-        with patch(LOGGER_PATCH), patch(f"{MOD}._send_with_retry", return_value=True) as mock_send:
-            result = _deliver_chunks(["Hello"], "tok", 123, None, False)
+        with patch(LOGGER_PATCH), patch(f"{MOD}._send_with_retry", return_value=_ok_result()) as mock_send:
+            all_sent, chunk_results = _deliver_chunks(["Hello"], "tok", 123, None, False)
 
-        assert result is True
+        assert all_sent is True
+        assert len(chunk_results) == 1
+        assert chunk_results[0]["method"] == "send"
         mock_send.assert_called_once_with("tok", 123, "Hello")
 
     def test_single_chunk_with_processing_msg_edits(self):
         from aipass.hooks.apps.handlers.notification.telegram_response import _deliver_chunks
 
-        with patch(LOGGER_PATCH), patch(f"{MOD}.edit_telegram_message", return_value=True) as mock_edit:
-            result = _deliver_chunks(["Hello"], "tok", 123, 789, False)
+        with patch(LOGGER_PATCH), patch(f"{MOD}.edit_telegram_message", return_value=_ok_result()) as mock_edit:
+            all_sent, chunk_results = _deliver_chunks(["Hello"], "tok", 123, 789, False)
 
-        assert result is True
+        assert all_sent is True
+        assert chunk_results[0]["method"] == "edit"
         mock_edit.assert_called_once_with("tok", 123, 789, "Hello")
 
     def test_single_chunk_edit_fails_falls_back_to_send(self):
@@ -1159,12 +1226,13 @@ class TestDeliverChunks:
 
         with (
             patch(LOGGER_PATCH),
-            patch(f"{MOD}.edit_telegram_message", return_value=False),
-            patch(f"{MOD}._send_with_retry", return_value=True) as mock_send,
+            patch(f"{MOD}.edit_telegram_message", return_value=_fail_result()),
+            patch(f"{MOD}._send_with_retry", return_value=_ok_result()) as mock_send,
         ):
-            result = _deliver_chunks(["Hello"], "tok", 123, 789, False)
+            all_sent, chunk_results = _deliver_chunks(["Hello"], "tok", 123, 789, False)
 
-        assert result is True
+        assert all_sent is True
+        assert chunk_results[0]["method"] == "send"
         mock_send.assert_called_once()
 
     def test_logs_active_sends_done_then_sends_new(self):
@@ -1173,28 +1241,784 @@ class TestDeliverChunks:
 
         with (
             patch(LOGGER_PATCH),
-            patch(f"{MOD}.edit_telegram_message", return_value=True) as mock_edit,
-            patch(f"{MOD}._send_with_retry", return_value=True) as mock_send,
+            patch(f"{MOD}.edit_telegram_message", return_value=_ok_result()) as mock_edit,
+            patch(f"{MOD}._send_with_retry", return_value=_ok_result()) as mock_send,
         ):
-            result = _deliver_chunks(["Hello"], "tok", 123, 789, True)
+            all_sent, chunk_results = _deliver_chunks(["Hello"], "tok", 123, 789, True)
 
-        assert result is True
+        assert all_sent is True
         mock_edit.assert_called_once_with("tok", 123, 789, "Done.")
         mock_send.assert_called_once()
 
-    def test_multiple_chunks_numbering(self):
+    def test_multiple_chunks_clears_placeholder_sends_all_fresh(self):
+        """Multi-chunk: clears placeholder and sends ALL chunks as fresh messages."""
         from aipass.hooks.apps.handlers.notification.telegram_response import _deliver_chunks
 
         sent_texts = []
 
         def capture_send(bot_token, chat_id, text):
             sent_texts.append(text)
-            return True
+            return _ok_result()
 
-        with patch(LOGGER_PATCH), patch(f"{MOD}._send_with_retry", side_effect=capture_send):
-            result = _deliver_chunks(["Part A", "Part B", "Part C"], "tok", 123, None, False)
+        with (
+            patch(LOGGER_PATCH),
+            patch(f"{MOD}.edit_telegram_message", return_value=_ok_result()) as mock_edit,
+            patch(f"{MOD}._send_with_retry", side_effect=capture_send),
+        ):
+            all_sent, chunk_results = _deliver_chunks(["Part A", "Part B", "Part C"], "tok", 123, 789, False)
 
-        assert result is True
+        assert all_sent is True
+        mock_edit.assert_called_once_with("tok", 123, 789, "Done.")
+        assert len(sent_texts) == 3
         assert "[1/3]" in sent_texts[0]
         assert "[2/3]" in sent_texts[1]
         assert "[3/3]" in sent_texts[2]
+
+    def test_multiple_chunks_no_processing_msg(self):
+        from aipass.hooks.apps.handlers.notification.telegram_response import _deliver_chunks
+
+        sent_texts = []
+
+        def capture_send(bot_token, chat_id, text):
+            sent_texts.append(text)
+            return _ok_result()
+
+        with patch(LOGGER_PATCH), patch(f"{MOD}._send_with_retry", side_effect=capture_send):
+            all_sent, chunk_results = _deliver_chunks(["Part A", "Part B", "Part C"], "tok", 123, None, False)
+
+        assert all_sent is True
+        assert "[1/3]" in sent_texts[0]
+        assert "[2/3]" in sent_texts[1]
+        assert "[3/3]" in sent_texts[2]
+
+    def test_chunk_results_contain_message_ids(self):
+        from aipass.hooks.apps.handlers.notification.telegram_response import _deliver_chunks
+
+        call_idx = 0
+
+        def mock_send_with_ids(bot_token, chat_id, text):
+            nonlocal call_idx
+            call_idx += 1
+            return _ok_result(message_id=200 + call_idx)
+
+        with patch(LOGGER_PATCH), patch(f"{MOD}._send_with_retry", side_effect=mock_send_with_ids):
+            _, chunk_results = _deliver_chunks(["A", "B"], "tok", 123, None, False)
+
+        assert chunk_results[0]["message_id"] == 201
+        assert chunk_results[1]["message_id"] == 202
+
+
+# ===========================================================================
+# _advance_pending
+# ===========================================================================
+
+
+class TestAdvancePending:
+    """Pending file cursor advancement."""
+
+    def test_advances_cursor(self, tmp_path):
+        from aipass.hooks.apps.handlers.notification.telegram_response import _advance_pending
+
+        transcript = tmp_path / "transcript.jsonl"
+        transcript.write_text("line1\nline2\nline3\n", encoding="utf-8")
+
+        pending_file = tmp_path / "pending.json"
+        pending_data = {"chat_id": 1, "bot_token": "tok"}
+        pending_file.write_text(json.dumps(pending_data), encoding="utf-8")
+
+        with patch(LOGGER_PATCH):
+            _advance_pending(pending_file, pending_data, str(transcript))
+
+        assert pending_file.exists()
+        updated = json.loads(pending_file.read_text(encoding="utf-8"))
+        assert updated["transcript_line_after"] == 3
+        assert updated["delivered"] is True
+
+    def test_no_transcript_removes_pending(self, tmp_path):
+        from aipass.hooks.apps.handlers.notification.telegram_response import _advance_pending
+
+        pending_file = tmp_path / "pending.json"
+        pending_data = {"chat_id": 1}
+        pending_file.write_text(json.dumps(pending_data), encoding="utf-8")
+
+        with patch(LOGGER_PATCH):
+            _advance_pending(pending_file, pending_data, "")
+
+        assert not pending_file.exists()
+
+    def test_transcript_read_failure_removes_pending(self, tmp_path):
+        from aipass.hooks.apps.handlers.notification.telegram_response import _advance_pending
+
+        pending_file = tmp_path / "pending.json"
+        pending_data = {"chat_id": 1}
+        pending_file.write_text(json.dumps(pending_data), encoding="utf-8")
+
+        with patch(LOGGER_PATCH):
+            _advance_pending(pending_file, pending_data, "/nonexistent/transcript.jsonl")
+
+        assert not pending_file.exists()
+
+
+# ===========================================================================
+# _write_delivery_log
+# ===========================================================================
+
+
+class TestWriteDeliveryLog:
+    """Delivery match log JSONL output."""
+
+    def test_writes_jsonl_record(self, tmp_path):
+        from aipass.hooks.apps.handlers.notification.telegram_response import _write_delivery_log
+
+        log_path = tmp_path / "delivery.jsonl"
+
+        with patch(LOGGER_PATCH), patch(f"{MOD}._DELIVERY_LOG", log_path):
+            _write_delivery_log(
+                "hello",
+                ["hello"],
+                [{"idx": 0, "method": "send", "ok": True, "message_id": 1, "text": "hello"}],
+                "session123",
+            )
+
+        assert log_path.exists()
+        record = json.loads(log_path.read_text(encoding="utf-8").strip())
+        assert record["intended_len"] == 5
+        assert record["match"] is True
+        assert record["session"] == "session1"
+        assert len(record["chunks"]) == 1
+
+    def test_mismatch_reports_culprit(self, tmp_path):
+        from aipass.hooks.apps.handlers.notification.telegram_response import _write_delivery_log
+
+        log_path = tmp_path / "delivery.jsonl"
+
+        with patch(LOGGER_PATCH), patch(f"{MOD}._DELIVERY_LOG", log_path):
+            _write_delivery_log(
+                "**bold text**",
+                ["**bold text**"],
+                [{"idx": 0, "method": "send", "ok": True, "message_id": 1, "text": "bold text"}],
+                "session123",
+            )
+
+        record = json.loads(log_path.read_text(encoding="utf-8").strip())
+        assert record["match"] is False
+        assert "culprit" in record
+
+    def test_failed_chunk_culprit(self, tmp_path):
+        from aipass.hooks.apps.handlers.notification.telegram_response import _write_delivery_log
+
+        log_path = tmp_path / "delivery.jsonl"
+
+        with patch(LOGGER_PATCH), patch(f"{MOD}._DELIVERY_LOG", log_path):
+            _write_delivery_log(
+                "hello",
+                ["hello"],
+                [{"idx": 0, "method": "send", "ok": False, "text": ""}],
+                "sess",
+            )
+
+        record = json.loads(log_path.read_text(encoding="utf-8").strip())
+        assert record["match"] is False
+        assert "delivery_failed" in record["culprit"]
+
+    def test_log_write_failure_does_not_raise(self):
+        from aipass.hooks.apps.handlers.notification.telegram_response import _write_delivery_log
+
+        impossible = Path("/dev/null/impossible/log.jsonl")
+        with patch(LOGGER_PATCH), patch(f"{MOD}._DELIVERY_LOG", impossible):
+            _write_delivery_log("hi", ["hi"], [{"idx": 0, "ok": True, "text": "hi"}], "s")
+
+
+# ===========================================================================
+# _is_expired — mirror files
+# ===========================================================================
+
+
+class TestIsExpiredMirror:
+    """Mirror files are never expired."""
+
+    def test_mirror_file_never_expired(self):
+        from aipass.hooks.apps.handlers.notification.telegram_response import _is_expired
+
+        with patch(LOGGER_PATCH):
+            assert _is_expired({"timestamp": 0, "mirror": True}) is False
+
+    def test_mirror_file_old_timestamp_not_expired(self):
+        from aipass.hooks.apps.handlers.notification.telegram_response import _is_expired
+
+        with patch(LOGGER_PATCH):
+            assert _is_expired({"timestamp": 1000, "mirror": True}) is False
+
+
+# ===========================================================================
+# _extract_user_text
+# ===========================================================================
+
+
+class TestExtractUserText:
+    """User message text extraction."""
+
+    def test_text_block(self):
+        from aipass.hooks.apps.handlers.notification.telegram_response import _extract_user_text
+
+        content = [{"type": "text", "text": "Hello world"}]
+        assert _extract_user_text(content) == "Hello world"
+
+    def test_tool_result_only_returns_none(self):
+        from aipass.hooks.apps.handlers.notification.telegram_response import _extract_user_text
+
+        content = [{"type": "tool_result", "content": "ok"}]
+        assert _extract_user_text(content) is None
+
+    def test_string_content(self):
+        from aipass.hooks.apps.handlers.notification.telegram_response import _extract_user_text
+
+        assert _extract_user_text("Hello") == "Hello"
+
+    def test_empty_string_returns_none(self):
+        from aipass.hooks.apps.handlers.notification.telegram_response import _extract_user_text
+
+        assert _extract_user_text("") is None
+
+    def test_empty_list_returns_none(self):
+        from aipass.hooks.apps.handlers.notification.telegram_response import _extract_user_text
+
+        assert _extract_user_text([]) is None
+
+    def test_non_list_non_string_returns_none(self):
+        from aipass.hooks.apps.handlers.notification.telegram_response import _extract_user_text
+
+        assert _extract_user_text(42) is None  # type: ignore[arg-type]
+
+    def test_mixed_text_and_tool_result(self):
+        from aipass.hooks.apps.handlers.notification.telegram_response import _extract_user_text
+
+        content = [{"type": "text", "text": "Question"}, {"type": "tool_result", "content": "ok"}]
+        assert _extract_user_text(content) == "Question"
+
+
+# ===========================================================================
+# extract_mirror_turn
+# ===========================================================================
+
+
+class TestExtractMirrorTurn:
+    """Mirror transcript extraction — user input + assistant response."""
+
+    def test_single_turn_user_and_assistant(self, tmp_path):
+        from aipass.hooks.apps.handlers.notification.telegram_response import extract_mirror_turn
+
+        transcript = tmp_path / "transcript.jsonl"
+        lines = [
+            _jsonl_line("user", "What is AIPass?"),
+            _jsonl_line("assistant", "AIPass is a multi-agent framework."),
+        ]
+        transcript.write_text("\n".join(lines), encoding="utf-8")
+
+        with patch(LOGGER_PATCH):
+            result = extract_mirror_turn(str(transcript))
+
+        assert result is not None
+        assert "You: What is AIPass?" in result
+        assert "AIPass is a multi-agent framework." in result
+
+    def test_multiple_turns_separated_by_divider(self, tmp_path):
+        from aipass.hooks.apps.handlers.notification.telegram_response import extract_mirror_turn
+
+        transcript = tmp_path / "transcript.jsonl"
+        lines = [
+            _jsonl_line("user", "First question"),
+            _jsonl_line("assistant", "First answer"),
+            _jsonl_line("user", "Second question"),
+            _jsonl_line("assistant", "Second answer"),
+        ]
+        transcript.write_text("\n".join(lines), encoding="utf-8")
+
+        with patch(LOGGER_PATCH):
+            result = extract_mirror_turn(str(transcript))
+
+        assert result is not None
+        assert "You: First question" in result
+        assert "First answer" in result
+        assert "---" in result
+        assert "You: Second question" in result
+        assert "Second answer" in result
+
+    def test_sidechain_entries_skipped(self, tmp_path):
+        from aipass.hooks.apps.handlers.notification.telegram_response import extract_mirror_turn
+
+        transcript = tmp_path / "transcript.jsonl"
+        lines = [
+            _jsonl_line("user", "Real question"),
+            _jsonl_line("assistant", "Sidechain noise", sidechain=True),
+            _jsonl_line("assistant", "Real answer"),
+        ]
+        transcript.write_text("\n".join(lines), encoding="utf-8")
+
+        with patch(LOGGER_PATCH):
+            result = extract_mirror_turn(str(transcript))
+
+        assert result is not None
+        assert "Sidechain noise" not in result
+        assert "Real answer" in result
+
+    def test_tool_result_user_messages_skipped(self, tmp_path):
+        from aipass.hooks.apps.handlers.notification.telegram_response import extract_mirror_turn
+
+        transcript = tmp_path / "transcript.jsonl"
+        lines = [
+            _jsonl_line("user", "Real question"),
+            _jsonl_line("assistant", "Working on it..."),
+            _jsonl_line("user", tool_result=True),
+            _jsonl_line("assistant", "Done with the work"),
+        ]
+        transcript.write_text("\n".join(lines), encoding="utf-8")
+
+        with patch(LOGGER_PATCH):
+            result = extract_mirror_turn(str(transcript))
+
+        assert result is not None
+        assert "You: Real question" in result
+        assert "Working on it..." in result
+        assert "Done with the work" in result
+        # tool_result should not create a second turn
+        assert "---" not in result
+
+    def test_start_line_skips_old_entries(self, tmp_path):
+        from aipass.hooks.apps.handlers.notification.telegram_response import extract_mirror_turn
+
+        transcript = tmp_path / "transcript.jsonl"
+        lines = [
+            _jsonl_line("user", "Old question"),
+            _jsonl_line("assistant", "Old answer"),
+            _jsonl_line("user", "New question"),
+            _jsonl_line("assistant", "New answer"),
+        ]
+        transcript.write_text("\n".join(lines), encoding="utf-8")
+
+        with patch(LOGGER_PATCH):
+            result = extract_mirror_turn(str(transcript), start_line=2)
+
+        assert result is not None
+        assert "Old question" not in result
+        assert "New question" in result
+        assert "New answer" in result
+
+    def test_no_new_entries_returns_none(self, tmp_path):
+        from aipass.hooks.apps.handlers.notification.telegram_response import extract_mirror_turn
+
+        transcript = tmp_path / "transcript.jsonl"
+        lines = [
+            _jsonl_line("user", "Question"),
+            _jsonl_line("assistant", "Answer"),
+        ]
+        transcript.write_text("\n".join(lines), encoding="utf-8")
+
+        with patch(LOGGER_PATCH):
+            result = extract_mirror_turn(str(transcript), start_line=2)
+
+        assert result is None
+
+    def test_missing_transcript_returns_none(self):
+        from aipass.hooks.apps.handlers.notification.telegram_response import extract_mirror_turn
+
+        with patch(LOGGER_PATCH):
+            result = extract_mirror_turn("/nonexistent/path.jsonl")
+
+        assert result is None
+
+    def test_corrupt_lines_skipped(self, tmp_path):
+        from aipass.hooks.apps.handlers.notification.telegram_response import extract_mirror_turn
+
+        transcript = tmp_path / "transcript.jsonl"
+        lines = [
+            _jsonl_line("user", "Question"),
+            "this is {{{ not json",
+            _jsonl_line("assistant", "Answer"),
+        ]
+        transcript.write_text("\n".join(lines), encoding="utf-8")
+
+        with patch(LOGGER_PATCH):
+            result = extract_mirror_turn(str(transcript))
+
+        assert result is not None
+        assert "You: Question" in result
+        assert "Answer" in result
+
+    def test_assistant_only_no_user_text(self, tmp_path):
+        """Assistant text after cursor with no user message — still delivered."""
+        from aipass.hooks.apps.handlers.notification.telegram_response import extract_mirror_turn
+
+        transcript = tmp_path / "transcript.jsonl"
+        lines = [
+            _jsonl_line("assistant", "Continuation text"),
+        ]
+        transcript.write_text("\n".join(lines), encoding="utf-8")
+
+        with patch(LOGGER_PATCH):
+            result = extract_mirror_turn(str(transcript))
+
+        assert result is not None
+        assert "Continuation text" in result
+        assert "You:" not in result
+
+    def test_stale_cursor_clamps_to_latest_turn(self, tmp_path):
+        """Cursor ahead of transcript self-heals by clamping to latest turn."""
+        from aipass.hooks.apps.handlers.notification.telegram_response import extract_mirror_turn
+
+        transcript = tmp_path / "transcript.jsonl"
+        lines = [
+            _jsonl_line("user", "Old question"),
+            _jsonl_line("assistant", "Old answer"),
+            _jsonl_line("user", "Latest question"),
+            _jsonl_line("assistant", "Latest answer"),
+        ]
+        transcript.write_text("\n".join(lines), encoding="utf-8")
+
+        with patch(LOGGER_PATCH):
+            result = extract_mirror_turn(str(transcript), start_line=50)
+
+        assert result is not None
+        assert "You: Latest question" in result
+        assert "Latest answer" in result
+
+    def test_stale_cursor_no_user_msg_delivers_all(self, tmp_path):
+        """Stale cursor with no user messages — delivers all assistant text."""
+        from aipass.hooks.apps.handlers.notification.telegram_response import extract_mirror_turn
+
+        transcript = tmp_path / "transcript.jsonl"
+        lines = [
+            _jsonl_line("assistant", "Some output"),
+        ]
+        transcript.write_text("\n".join(lines), encoding="utf-8")
+
+        with patch(LOGGER_PATCH):
+            result = extract_mirror_turn(str(transcript), start_line=99)
+
+        assert result is not None
+        assert "Some output" in result
+
+
+# ===========================================================================
+# find_pending_file — mirror directory
+# ===========================================================================
+
+
+class TestFindPendingFileMirror:
+    """Mirror directory search for persistent mapping files."""
+
+    def test_mirror_dir_env_bot_id_match(self, tmp_path):
+        from aipass.hooks.apps.handlers.notification.telegram_response import find_pending_file
+
+        mirror_dir = tmp_path / "telegram_bots"
+        mirror_dir.mkdir()
+        data = {"timestamp": time.time(), "work_dir": str(tmp_path), "mirror": True}
+        (mirror_dir / "bot-42.json").write_text(json.dumps(data), encoding="utf-8")
+
+        with (
+            patch(LOGGER_PATCH),
+            patch(f"{MOD}.MIRROR_DIR", mirror_dir),
+            patch(f"{MOD}.PENDING_DIR", tmp_path / "nonexistent"),
+            patch.dict("os.environ", {"AIPASS_BOT_ID": "42"}),
+        ):
+            result = find_pending_file("session-xyz")
+
+        assert result is not None
+        assert result.name == "bot-42.json"
+
+    def test_mirror_dir_preferred_over_pending_for_env(self, tmp_path):
+        """Mirror dir is checked before pending dir for AIPASS_BOT_ID match."""
+        from aipass.hooks.apps.handlers.notification.telegram_response import find_pending_file
+
+        mirror_dir = tmp_path / "telegram_bots"
+        mirror_dir.mkdir()
+        pending_dir = tmp_path / "telegram_pending"
+        pending_dir.mkdir()
+        mirror_data = {"timestamp": time.time(), "work_dir": str(tmp_path), "mirror": True}
+        pending_data = {"timestamp": time.time(), "work_dir": str(tmp_path)}
+        (mirror_dir / "bot-42.json").write_text(json.dumps(mirror_data), encoding="utf-8")
+        (pending_dir / "bot-42.json").write_text(json.dumps(pending_data), encoding="utf-8")
+
+        with (
+            patch(LOGGER_PATCH),
+            patch(f"{MOD}.MIRROR_DIR", mirror_dir),
+            patch(f"{MOD}.PENDING_DIR", pending_dir),
+            patch.dict("os.environ", {"AIPASS_BOT_ID": "42"}),
+        ):
+            result = find_pending_file("session-xyz")
+
+        assert result is not None
+        assert str(mirror_dir) in str(result)
+
+    def test_mirror_dir_cwd_match(self, tmp_path):
+        from aipass.hooks.apps.handlers.notification.telegram_response import find_pending_file
+
+        mirror_dir = tmp_path / "telegram_bots"
+        mirror_dir.mkdir()
+        work = tmp_path / "project"
+        work.mkdir()
+        data = {"timestamp": time.time(), "work_dir": str(work), "mirror": True}
+        (mirror_dir / "bot-7.json").write_text(json.dumps(data), encoding="utf-8")
+
+        with (
+            patch(LOGGER_PATCH),
+            patch(f"{MOD}.MIRROR_DIR", mirror_dir),
+            patch(f"{MOD}.PENDING_DIR", tmp_path / "nonexistent"),
+            patch.dict("os.environ", {}, clear=True),
+            patch(f"{MOD}.Path.cwd", return_value=work / "subdir"),
+        ):
+            result = find_pending_file("session-abc")
+
+        assert result is not None
+        assert result.name == "bot-7.json"
+
+
+# ===========================================================================
+# handle — mirror integration tests
+# ===========================================================================
+
+
+class TestHandleMirrorIntegration:
+    """Full handle() flow for mirror sessions."""
+
+    def test_mirror_user_typed_directly_delivered(self, tmp_path):
+        """User types directly in terminal — mirror delivers to TG."""
+        from aipass.hooks.apps.handlers.notification.telegram_response import handle
+
+        transcript = tmp_path / "transcript.jsonl"
+        lines = [
+            _jsonl_line("user", "Old question"),
+            _jsonl_line("assistant", "Old answer"),
+            _jsonl_line("user", "What is this?"),
+            _jsonl_line("assistant", "This is the answer."),
+        ]
+        transcript.write_text("\n".join(lines), encoding="utf-8")
+
+        mirror_dir = tmp_path / "telegram_bots"
+        mirror_dir.mkdir()
+        mirror_data = {
+            "chat_id": 999,
+            "bot_token": "tok:ABC",
+            "session_name": "devpulse",
+            "work_dir": str(tmp_path),
+            "mirror": True,
+            "transcript_line_after": 2,
+        }
+        mirror_file = mirror_dir / "bot-1.json"
+        mirror_file.write_text(json.dumps(mirror_data), encoding="utf-8")
+
+        sent_texts = []
+
+        def capture_send(bot_token, chat_id, text):
+            sent_texts.append(text)
+            return _ok_result()
+
+        with (
+            patch(LOGGER_PATCH),
+            patch(f"{MOD}.find_pending_file", return_value=mirror_file),
+            patch(f"{MOD}._send_with_retry", side_effect=capture_send),
+            patch(f"{MOD}._check_log_streamer_active", return_value=False),
+            patch(f"{MOD}.Path.cwd", return_value=tmp_path),
+            patch(f"{MOD}._write_delivery_log"),
+        ):
+            result = handle(
+                {
+                    "hook_event_name": "Stop",
+                    "session_id": "session-abc",
+                    "transcript_path": str(transcript),
+                }
+            )
+
+        assert result == {"stdout": "", "exit_code": 0}
+        assert len(sent_texts) == 1
+        assert "You: What is this?" in sent_texts[0]
+        assert "This is the answer." in sent_texts[0]
+
+    def test_mirror_tg_injected_no_double_send(self, tmp_path):
+        """TG-injected turn — cursor advancement prevents re-delivery."""
+        from aipass.hooks.apps.handlers.notification.telegram_response import handle
+
+        transcript = tmp_path / "transcript.jsonl"
+        lines = [
+            _jsonl_line("user", "Injected from TG"),
+            _jsonl_line("assistant", "Response to TG"),
+        ]
+        transcript.write_text("\n".join(lines), encoding="utf-8")
+
+        mirror_dir = tmp_path / "telegram_bots"
+        mirror_dir.mkdir()
+        mirror_data = {
+            "chat_id": 999,
+            "bot_token": "tok:ABC",
+            "session_name": "devpulse",
+            "work_dir": str(tmp_path),
+            "mirror": True,
+            "transcript_line_after": 2,
+            "delivered": True,
+        }
+        mirror_file = mirror_dir / "bot-1.json"
+        mirror_file.write_text(json.dumps(mirror_data), encoding="utf-8")
+
+        with (
+            patch(LOGGER_PATCH),
+            patch(f"{MOD}.find_pending_file", return_value=mirror_file),
+            patch(f"{MOD}._check_log_streamer_active", return_value=False),
+            patch(f"{MOD}.time.sleep"),
+            patch(f"{MOD}.Path.cwd", return_value=tmp_path),
+        ):
+            result = handle(
+                {
+                    "hook_event_name": "Stop",
+                    "session_id": "session-abc",
+                    "transcript_path": str(transcript),
+                }
+            )
+
+        assert result == {"stdout": "", "exit_code": 0}
+        assert mirror_file.exists()
+
+    def test_mirror_cursor_advances_no_redelivery(self, tmp_path):
+        """Cursor advances after mirror delivery — old turns not re-sent."""
+        from aipass.hooks.apps.handlers.notification.telegram_response import handle
+
+        transcript = tmp_path / "transcript.jsonl"
+        lines = [
+            _jsonl_line("user", "Question"),
+            _jsonl_line("assistant", "Answer"),
+        ]
+        transcript.write_text("\n".join(lines), encoding="utf-8")
+
+        mirror_dir = tmp_path / "telegram_bots"
+        mirror_dir.mkdir()
+        mirror_data = {
+            "chat_id": 999,
+            "bot_token": "tok:ABC",
+            "session_name": "devpulse",
+            "work_dir": str(tmp_path),
+            "mirror": True,
+            "transcript_line_after": 0,
+        }
+        mirror_file = mirror_dir / "bot-1.json"
+        mirror_file.write_text(json.dumps(mirror_data), encoding="utf-8")
+
+        with (
+            patch(LOGGER_PATCH),
+            patch(f"{MOD}.find_pending_file", return_value=mirror_file),
+            patch(f"{MOD}._send_with_retry", return_value=_ok_result()),
+            patch(f"{MOD}._check_log_streamer_active", return_value=False),
+            patch(f"{MOD}.Path.cwd", return_value=tmp_path),
+            patch(f"{MOD}._write_delivery_log"),
+        ):
+            handle(
+                {
+                    "hook_event_name": "Stop",
+                    "session_id": "session-abc",
+                    "transcript_path": str(transcript),
+                }
+            )
+
+        updated = json.loads(mirror_file.read_text(encoding="utf-8"))
+        assert updated["transcript_line_after"] == 2
+        assert updated["delivered"] is True
+        assert mirror_file.exists()
+
+    def test_mirror_file_never_deleted_on_error(self, tmp_path):
+        """Mirror mapping files are never deleted, even on validation errors."""
+        from aipass.hooks.apps.handlers.notification.telegram_response import handle
+
+        mirror_dir = tmp_path / "telegram_bots"
+        mirror_dir.mkdir()
+        mirror_data = {
+            "mirror": True,
+            "session_name": "devpulse",
+            "work_dir": str(tmp_path),
+        }
+        mirror_file = mirror_dir / "bot-1.json"
+        mirror_file.write_text(json.dumps(mirror_data), encoding="utf-8")
+
+        with patch(LOGGER_PATCH), patch(f"{MOD}.find_pending_file", return_value=mirror_file):
+            handle(
+                {
+                    "hook_event_name": "Stop",
+                    "session_id": "session-abc",
+                }
+            )
+
+        assert mirror_file.exists()
+
+    def test_mirror_no_processing_message_sends_fresh(self, tmp_path):
+        """Mirror sessions have no processing_message_id — always send fresh."""
+        from aipass.hooks.apps.handlers.notification.telegram_response import handle
+
+        transcript = tmp_path / "transcript.jsonl"
+        lines = [
+            _jsonl_line("user", "Hello"),
+            _jsonl_line("assistant", "Hi there"),
+        ]
+        transcript.write_text("\n".join(lines), encoding="utf-8")
+
+        mirror_dir = tmp_path / "telegram_bots"
+        mirror_dir.mkdir()
+        mirror_data = {
+            "chat_id": 999,
+            "bot_token": "tok:ABC",
+            "session_name": "devpulse",
+            "work_dir": str(tmp_path),
+            "mirror": True,
+            "transcript_line_after": 0,
+        }
+        mirror_file = mirror_dir / "bot-1.json"
+        mirror_file.write_text(json.dumps(mirror_data), encoding="utf-8")
+
+        with (
+            patch(LOGGER_PATCH),
+            patch(f"{MOD}.find_pending_file", return_value=mirror_file),
+            patch(f"{MOD}._send_with_retry", return_value=_ok_result()) as mock_send,
+            patch(f"{MOD}.edit_telegram_message") as mock_edit,
+            patch(f"{MOD}._check_log_streamer_active", return_value=False),
+            patch(f"{MOD}.Path.cwd", return_value=tmp_path),
+            patch(f"{MOD}._write_delivery_log"),
+        ):
+            handle(
+                {
+                    "hook_event_name": "Stop",
+                    "session_id": "session-abc",
+                    "transcript_path": str(transcript),
+                }
+            )
+
+        mock_send.assert_called_once()
+        mock_edit.assert_not_called()
+
+
+# ===========================================================================
+# _advance_pending — mirror protection
+# ===========================================================================
+
+
+class TestAdvancePendingMirror:
+    """Mirror files are never deleted by _advance_pending."""
+
+    def test_mirror_no_transcript_kept(self, tmp_path):
+        from aipass.hooks.apps.handlers.notification.telegram_response import _advance_pending
+
+        pending_file = tmp_path / "pending.json"
+        pending_data = {"chat_id": 1, "mirror": True}
+        pending_file.write_text(json.dumps(pending_data), encoding="utf-8")
+
+        with patch(LOGGER_PATCH):
+            _advance_pending(pending_file, pending_data, "")
+
+        assert pending_file.exists()
+
+    def test_mirror_transcript_failure_kept(self, tmp_path):
+        from aipass.hooks.apps.handlers.notification.telegram_response import _advance_pending
+
+        pending_file = tmp_path / "pending.json"
+        pending_data = {"chat_id": 1, "mirror": True}
+        pending_file.write_text(json.dumps(pending_data), encoding="utf-8")
+
+        with patch(LOGGER_PATCH):
+            _advance_pending(pending_file, pending_data, "/nonexistent/transcript.jsonl")
+
+        assert pending_file.exists()
diff --git a/src/aipass/memory/.seedgo/bypass.json b/src/aipass/memory/.seedgo/bypass.json
index bb398233..2bff3ff9 100644
--- a/src/aipass/memory/.seedgo/bypass.json
+++ b/src/aipass/memory/.seedgo/bypass.json
@@ -141,6 +141,11 @@
       "standard": "handlers",
       "reason": "Architectural: imports json.memory_files for metadata updates and monitor.detector for registry reading."
     },
+    {
+      "file": "apps/handlers/tracking/tab_renderer.py",
+      "standard": "handlers",
+      "reason": "Architectural: imports json.memory_files, json.config_loader, and monitor.detector for config-driven tab rendering across all branches."
+    },
     {
       "file": "apps/handlers/search/vector_search.py",
       "standard": "handlers",
@@ -451,6 +456,12 @@
       "standard": "unused_function",
       "reason": "is_plan_vectorized is a public API function for external callers."
     },
+    {
+      "file": "apps/handlers/tracking/tab_renderer.py",
+      "standard": "unused_function",
+      "functions": ["render_all_meta_tabs"],
+      "reason": "Cross-branch public API — called by @spawn's build_replacements_dict to resolve {{*_META}} placeholders at branch creation."
+    },
     {
       "file": "apps/modules/templates.py",
       "standard": "deep_nesting",
@@ -559,31 +570,13 @@
     {
       "file": "apps/handlers/learnings/manager.py",
       "standard": "unused_function",
-      "lines": [759],
+      "functions": ["update_status_counts"],
       "reason": "Public API for learning extraction pipeline — called dynamically by symbolic extraction."
     },
-    {
-      "file": "apps/handlers/search/vector_search.py",
-      "standard": "unused_function",
-      "lines": [247],
-      "reason": "Public API surface for vector search — legacy handler retained for direct-import consumers."
-    },
-    {
-      "file": "apps/handlers/search/vector_search.py",
-      "standard": "unused_function",
-      "lines": [316],
-      "reason": "Public API surface for vector search — legacy handler retained for direct-import consumers."
-    },
-    {
-      "file": "apps/handlers/search/vector_search.py",
-      "standard": "unused_function",
-      "lines": [380],
-      "reason": "Public API surface for vector search — legacy handler retained for direct-import consumers."
-    },
     {
       "file": "apps/handlers/symbolic/extractor.py",
       "standard": "unused_function",
-      "lines": [455],
+      "functions": ["analyze_conversation_llm"],
       "reason": "LLM-based extraction function — called conditionally when API key is available."
     },
     {
@@ -711,6 +704,16 @@
       "standard": "meta",
       "reason": "Test file — META block present at lines 1-7; hook false-positive on test file format."
     },
+    {
+      "file": "tests/test_tab_renderer.py",
+      "standard": "architecture",
+      "reason": "Test file — lives in tests/ by design, not in 3-layer apps/ structure."
+    },
+    {
+      "file": "tests/test_tab_renderer.py",
+      "standard": "documentation",
+      "reason": "Test file — test functions don't require docstrings."
+    },
     {
       "file": "tests/test_handlers.py",
       "standard": "architecture",
diff --git a/src/aipass/memory/README.md b/src/aipass/memory/README.md
index 0bd04cbf..abe78592 100644
--- a/src/aipass/memory/README.md
+++ b/src/aipass/memory/README.md
@@ -64,11 +64,11 @@ memory/
 │       ├── storage/             # chroma.py, chroma_subprocess.py
 │       ├── symbolic/            # chroma_client, deduplicator, extractor, hook, retriever, storage
 │       ├── templates/           # pusher.py, differ.py, spawn_pusher.py
-│       ├── tracking/            # line_counter.py
+│       ├── tracking/            # line_counter.py, tab_renderer.py
 │       ├── vector/              # embedder.py, embed_subprocess.py
 │       └── central_writer.py
 ├── templates/                   # LOCAL.template.json, OBSERVATIONS.template.json
-├── tests/                       # 949 tests (31 test files)
+├── tests/                       # 978 tests
 ├── .chroma/                     # ChromaDB vector store
 └── memory_json/                 # Operation logs + custom_config/memory.config.json
 ```
@@ -87,12 +87,46 @@ detector.check_all_branches()        # scan AIPASS_REGISTRY.json + external regi
   → trim source file                 # write back with oldest removed
 ```
 
+Rollover writes safety copies (`rollover_backup_*.json`) into `<branch>/.backup/` — a shared runtime namespace (see `@backup`'s README for all writers).
+
 ### Subprocess Isolation
 
 All ML operations (fastembed, chromadb) run via subprocess. The main process never imports these libraries. Python interpreter resolved via `_get_memory_python()` (env var `AIPASS_MEMORY_PYTHON` → `memory/.venv/bin/python` → `sys.executable`).
 
 ---
 
+## State-Tabs (`*_meta` keys)
+
+Every `.trinity/local.json` and `.trinity/observations.json` carries inline `*_meta` banner strings that tell the editing agent what rollover rules apply to each section. Example:
+
+```
+"sessions_meta": "⟦ rollover ON → oldest archived to @memory · keep 15 · summary ≤300 chars ⟧"
+```
+
+**Source of truth:** `memory.config.json` — rollover counts (defaults + per-branch overrides) and entry char limits. Tab strings are *generated*, never hand-written.
+
+**Sections:** `todos_meta` (rollover OFF — operational, never trimmed), `key_learnings_meta`, `sessions_meta`, `observations_meta` (all rollover ON).
+
+### Two value flows
+
+| Scenario | How tabs arrive |
+|---|---|
+| **Live branches** | `refresh_all_tabs()` walks the registry, renders tabs from config with per-branch overrides, writes them into `.trinity/` files. Wired after rollover, sync-lines, and push-templates. |
+| **New branches** | Templates carry `{{TODOS_META}}`, `{{KEY_LEARNINGS_META}}`, `{{SESSIONS_META}}`, `{{OBSERVATIONS_META}}` placeholders. `spawn_pusher` propagates these (unresolved) from memory templates → spawn template sets. At branch creation, @spawn calls `render_all_meta_tabs()` to get rendered defaults and resolves the placeholders. |
+
+### Public API
+
+```python
+from aipass.memory.apps.handlers.tracking.tab_renderer import render_all_meta_tabs
+
+tabs = render_all_meta_tabs()
+# → {"TODOS_META": "⟦ rollover OFF ...", "KEY_LEARNINGS_META": "⟦ rollover ON ...", ...}
+```
+
+Returns defaults (not per-branch overrides) — appropriate for template resolution at branch creation.
+
+---
+
 ## Integration Points
 
 **Depends on:**
@@ -115,9 +149,8 @@ All ML operations (fastembed, chromadb) run via subprocess. The main process nev
 
 ## Quality
 
-- **Tests:** 949 passed, 0 failures, 0 skips
-- **Test files:** 31
-- **Seedgo:** 100% — maintained since s12
+- **Tests:** 978 passed, 0 failures, 0 skips
+- **Seedgo:** 100%
 
 ---
 
@@ -129,7 +162,7 @@ All ML operations (fastembed, chromadb) run via subprocess. The main process nev
 
 ---
 
-*Last Updated: 2026-05-16*
+*Last Updated: 2026-06-25*
 
 ---
 [← Back to AIPass](../../../README.md)
diff --git a/src/aipass/memory/apps/handlers/json/config_loader.py b/src/aipass/memory/apps/handlers/json/config_loader.py
index 423229f8..cb22aa25 100644
--- a/src/aipass/memory/apps/handlers/json/config_loader.py
+++ b/src/aipass/memory/apps/handlers/json/config_loader.py
@@ -114,7 +114,6 @@ DEFAULT_CONFIG: dict[str, Any] = {
             "local": {
                 "sessions": {"count": 20},
                 "key_learnings": {"count": 25},
-                "todos": {"count": 10},
             },
             "observations": {
                 "observations": {"count": 25},
diff --git a/src/aipass/memory/apps/handlers/templates/pusher.py b/src/aipass/memory/apps/handlers/templates/pusher.py
index f1c63a67..8fcecc0c 100644
--- a/src/aipass/memory/apps/handlers/templates/pusher.py
+++ b/src/aipass/memory/apps/handlers/templates/pusher.py
@@ -160,6 +160,12 @@ def _merge_metadata(curr_meta: dict, tmpl_meta: dict) -> List[str]:
             curr_meta[key] = tmpl_val
             changes.append(f"document_metadata.{key}: {old} -> {tmpl_val}")
 
+    # _usage
+    tmpl_usage = tmpl_meta.get("_usage")
+    if tmpl_usage and curr_meta.get("_usage") != tmpl_usage:
+        curr_meta["_usage"] = tmpl_usage
+        changes.append("document_metadata._usage: updated from template")
+
     # Tags
     tmpl_tags = tmpl_meta.get("tags", [])
     if tmpl_tags and set(curr_meta.get("tags", [])) != set(tmpl_tags):
diff --git a/src/aipass/memory/apps/handlers/tracking/tab_renderer.py b/src/aipass/memory/apps/handlers/tracking/tab_renderer.py
new file mode 100644
index 00000000..aec86f24
--- /dev/null
+++ b/src/aipass/memory/apps/handlers/tracking/tab_renderer.py
@@ -0,0 +1,332 @@
+# =================== AIPass ====================
+# Name: tab_renderer.py
+# Description: Config-generated state-tabs for .trinity memory files
+# Version: 1.0.0
+# Created: 2026-06-25
+# Modified: 2026-06-25
+# =============================================
+
+"""
+Tab Renderer Handler
+
+Generates per-section state-tab strings (e.g. ``⟦ rollover ON ... ⟧``) from
+``memory.config.json`` and writes them as ``*_meta`` keys into every branch's
+``.trinity/local.json`` and ``.trinity/observations.json``.
+
+Purpose:
+    Make memory files self-documenting.  Each section carries a single-line
+    banner that tells the editing agent whether rollover is ON/OFF, the keep
+    count, and the char cap — all derived from config so they never drift.
+
+Independence:
+    Uses config_loader for config, detector helpers for branch discovery,
+    and memory_files for safe I/O.  No service or module dependencies.
+"""
+
+from typing import Any, Dict
+
+from aipass.prax.apps.modules.logger import get_system_logger
+from aipass.memory.apps.handlers.json import json_handler
+
+logger = get_system_logger()
+
+_CORRECTED_USAGE_LOCAL = (
+    "Automated file — add entries within your sections, newest on top. "
+    "Rollover auto-archives sessions/key_learnings (+ observations.json) to @memory; "
+    "todos[] are OPERATIONAL and NEVER rolled — prune done ones by hand at /prep. "
+    "Limits live in @memory’s memory.config.json."
+)
+_CORRECTED_USAGE_OBS = (
+    "Automated file — add entries within your sections, newest on top. "
+    "Rollover auto-archives the oldest observations to @memory. "
+    "Limits live in @memory’s memory.config.json."
+)
+
+
+# =============================================================================
+# KEY ORDERING
+# =============================================================================
+
+# Canonical key order for local.json
+_LOCAL_KEY_ORDER = [
+    "document_metadata",
+    "todos_meta",
+    "todos",
+    "key_learnings_meta",
+    "key_learnings",
+    "sessions_meta",
+    "sessions",
+]
+
+# Canonical key order for observations.json
+_OBSERVATIONS_KEY_ORDER = [
+    "document_metadata",
+    "guidelines",
+    "observations_meta",
+    "observations",
+]
+
+
+def _reorder_keys(data: Dict[str, Any], key_order: list[str]) -> Dict[str, Any]:
+    """Rebuild *data* with keys in *key_order* first, then any remaining keys."""
+    ordered: Dict[str, Any] = {}
+    for key in key_order:
+        if key in data:
+            ordered[key] = data[key]
+    # Append any keys not in the canonical order
+    for key in data:
+        if key not in ordered:
+            ordered[key] = data[key]
+    return ordered
+
+
+# =============================================================================
+# TAB RENDERING
+# =============================================================================
+
+
+def render_tab(
+    section_name: str,
+    rollover_cfg: dict,
+    entry_limits_cfg: dict,
+    branch_name: str,
+) -> str:
+    """Generate the state-tab string for a section.
+
+    Args:
+        section_name: One of 'key_learnings', 'sessions', 'observations', 'todos'.
+        rollover_cfg: The ``rollover`` section from memory.config.json.
+        entry_limits_cfg: The ``entry_limits`` section from memory.config.json.
+        branch_name: Branch name (lowercase) for per-branch overrides.
+
+    Returns:
+        The rendered tab string (e.g. ``⟦ rollover ON ... ⟧``).
+    """
+    # --- Resolve entry-limits for this section --------------------------------
+    entry_types = entry_limits_cfg.get("entry_types", {})
+    section_limits = entry_types.get(section_name, {})
+    max_chars = section_limits.get("max_chars", 300)
+    field = section_limits.get("field", "value")
+
+    # --- Todos are special: rollover OFF, static shape ------------------------
+    if section_name == "todos":
+        return (
+            f"⟦ rollover OFF — operational, never trimmed · "
+            f"cap ~10 entries · task ≤{max_chars} chars ⟧ "
+            f"RULE: DELETE each todo when done (never leave status:done) "
+            f"+ reconcile on load; proof goes in the session entry, "
+            f"not the todo. Add freely — BAU."
+        )
+
+    # --- Rollover sections: look up count -------------------------------------
+    per_branch = rollover_cfg.get("per_branch", {})
+    defaults = rollover_cfg.get("defaults", {})
+    branch_cfg = per_branch.get(branch_name, defaults)
+
+    # Determine which file-level block to read
+    if section_name == "observations":
+        file_block = branch_cfg.get("observations", {})
+    else:
+        file_block = branch_cfg.get("local", {})
+
+    section_cfg = file_block.get(section_name, {})
+    count = section_cfg.get("count", 15)
+
+    return f"⟦ rollover ON → oldest archived to @memory · keep {count} · {field} ≤{max_chars} chars ⟧"
+
+
+# =============================================================================
+# PER-FILE TAB WRITERS
+# =============================================================================
+
+
+def _refresh_local(branch_name, local_path, rollover_cfg, entry_limits_cfg):
+    """Inject *_meta tabs into a branch's local.json. Returns (ok, error_msg)."""
+    from aipass.memory.apps.handlers.json.memory_files import (
+        read_memory_file_data,
+        write_memory_file_simple,
+    )
+
+    data = read_memory_file_data(local_path)
+    if data is None:
+        return False, None  # file unreadable, skip silently
+
+    meta = data.get("document_metadata", {})
+    if meta.get("_usage") != _CORRECTED_USAGE_LOCAL:
+        meta["_usage"] = _CORRECTED_USAGE_LOCAL
+
+    data["todos_meta"] = render_tab(
+        "todos",
+        rollover_cfg,
+        entry_limits_cfg,
+        branch_name,
+    )
+    data["key_learnings_meta"] = render_tab(
+        "key_learnings",
+        rollover_cfg,
+        entry_limits_cfg,
+        branch_name,
+    )
+    data["sessions_meta"] = render_tab(
+        "sessions",
+        rollover_cfg,
+        entry_limits_cfg,
+        branch_name,
+    )
+    data = _reorder_keys(data, _LOCAL_KEY_ORDER)
+
+    if write_memory_file_simple(local_path, data):
+        return True, None
+    return False, f"{branch_name}/local.json: write failed"
+
+
+def _refresh_observations(branch_name, obs_path, rollover_cfg, entry_limits_cfg):
+    """Inject observations_meta tab into a branch's observations.json. Returns (ok, error_msg)."""
+    from aipass.memory.apps.handlers.json.memory_files import (
+        read_memory_file_data,
+        write_memory_file_simple,
+    )
+
+    data = read_memory_file_data(obs_path)
+    if data is None:
+        return False, None  # file unreadable, skip silently
+
+    meta = data.get("document_metadata", {})
+    if meta.get("_usage") != _CORRECTED_USAGE_OBS:
+        meta["_usage"] = _CORRECTED_USAGE_OBS
+
+    data["observations_meta"] = render_tab(
+        "observations",
+        rollover_cfg,
+        entry_limits_cfg,
+        branch_name,
+    )
+    data = _reorder_keys(data, _OBSERVATIONS_KEY_ORDER)
+
+    if write_memory_file_simple(obs_path, data):
+        return True, None
+    return False, f"{branch_name}/observations.json: write failed"
+
+
+# =============================================================================
+# REFRESH ALL BRANCHES
+# =============================================================================
+
+
+def refresh_all_tabs() -> dict:
+    """Render and write state-tabs to all branch .trinity files.
+
+    Walks the registry, reads each branch's memory files, computes tab
+    strings from config, injects them as ``*_meta`` keys, and writes back
+    with correct key ordering.
+
+    Returns:
+        Dict with success status and counts.
+    """
+    from aipass.memory.apps.handlers.json.config_loader import (
+        load as load_config,
+    )
+    from aipass.memory.apps.handlers.monitor.detector import (
+        _read_registry,
+        _get_memory_file_path,
+    )
+
+    config = load_config()
+    rollover_cfg = config.get("rollover", {})
+    entry_limits_cfg = config.get("entry_limits", {})
+
+    branches = _read_registry()
+    if not branches:
+        return {
+            "success": True,
+            "updated": 0,
+            "skipped": 0,
+            "message": "No branches in registry",
+        }
+
+    updated = 0
+    skipped = 0
+    errors: list[str] = []
+
+    for branch in branches:
+        branch_name = branch.get("name", "UNKNOWN").lower()
+        for mem_type in ("local", "observations"):
+            u, s, e = _refresh_one_file(
+                branch,
+                branch_name,
+                mem_type,
+                rollover_cfg,
+                entry_limits_cfg,
+                _get_memory_file_path,
+            )
+            updated += u
+            skipped += s
+            errors.extend(e)
+
+    json_handler.log_operation(
+        "refresh_all_tabs",
+        {"updated": updated, "skipped": skipped, "errors": len(errors)},
+        module_name="tab_renderer",
+    )
+    logger.info(
+        f"[tab_renderer] Refreshed tabs: {updated} updated, {skipped} skipped, {len(errors)} errors",
+    )
+
+    return {
+        "success": True,
+        "updated": updated,
+        "skipped": skipped,
+        "errors": errors,
+    }
+
+
+def render_all_meta_tabs() -> dict[str, str]:
+    """Render all four *_meta tab strings from memory.config.json defaults.
+
+    Public API for @spawn (and any other consumer) to resolve ``{{*_META}}``
+    placeholders at branch-creation time.
+
+    Returns:
+        Dict with keys TODOS_META, KEY_LEARNINGS_META, SESSIONS_META,
+        OBSERVATIONS_META — each a rendered state-tab string.
+    """
+    from aipass.memory.apps.handlers.json.config_loader import (
+        load as load_config,
+    )
+
+    config = load_config()
+    rollover_cfg = config.get("rollover", {})
+    entry_limits_cfg = config.get("entry_limits", {})
+
+    _default = "__template_default__"
+    return {
+        "TODOS_META": render_tab("todos", rollover_cfg, entry_limits_cfg, _default),
+        "KEY_LEARNINGS_META": render_tab("key_learnings", rollover_cfg, entry_limits_cfg, _default),
+        "SESSIONS_META": render_tab("sessions", rollover_cfg, entry_limits_cfg, _default),
+        "OBSERVATIONS_META": render_tab("observations", rollover_cfg, entry_limits_cfg, _default),
+    }
+
+
+def _refresh_one_file(branch, branch_name, mem_type, rollover_cfg, entry_limits_cfg, get_path_fn):
+    """Refresh tabs for a single memory file. Returns (updated, skipped, errors)."""
+    file_path = get_path_fn(branch, mem_type)
+    if file_path is None:
+        return 0, 1, []
+
+    refresher = _refresh_local if mem_type == "local" else _refresh_observations
+    try:
+        ok, err = refresher(
+            branch_name,
+            file_path,
+            rollover_cfg,
+            entry_limits_cfg,
+        )
+    except Exception as e:
+        logger.warning(f"[tab_renderer] {branch_name}/{mem_type}.json: {e}")
+        return 0, 0, [f"{branch_name}/{mem_type}.json: {e}"]
+
+    if ok:
+        return 1, 0, []
+    if err:
+        return 0, 0, [err]
+    return 0, 1, []
diff --git a/src/aipass/memory/apps/modules/rollover.py b/src/aipass/memory/apps/modules/rollover.py
index 7b29d034..e4014b85 100755
--- a/src/aipass/memory/apps/modules/rollover.py
+++ b/src/aipass/memory/apps/modules/rollover.py
@@ -236,6 +236,15 @@ def run_rollover() -> bool:
             error(f"{fail['trigger']} - {fail['stage']}: {fail['error']}")
 
     json_handler.log_operation("rollover_execute", {"triggers": triggers_count, "success_count": success_count})
+
+    # Refresh state-tabs after rollover (counts may have changed)
+    try:
+        from aipass.memory.apps.handlers.tracking.tab_renderer import refresh_all_tabs
+
+        refresh_all_tabs()
+    except Exception as e:
+        logger.warning(f"[rollover] Tab refresh failed: {e}")
+
     return success_count > 0
 
 
@@ -325,6 +334,14 @@ def sync_line_counts() -> None:
     else:
         error("Failed to sync line counts")
 
+    # Refresh state-tabs after line count sync
+    try:
+        from aipass.memory.apps.handlers.tracking.tab_renderer import refresh_all_tabs
+
+        refresh_all_tabs()
+    except Exception as e:
+        logger.warning(f"[rollover] Tab refresh failed: {e}")
+
     console.print()
 
 
diff --git a/src/aipass/memory/apps/modules/templates.py b/src/aipass/memory/apps/modules/templates.py
index e3437e36..4a8c80e8 100644
--- a/src/aipass/memory/apps/modules/templates.py
+++ b/src/aipass/memory/apps/modules/templates.py
@@ -119,6 +119,14 @@ def handle_command(command: str, args: List[str]) -> bool:
             except Exception as e:
                 error(f"Spawn template push crashed: {e}")
                 logger.error(f"[templates] spawn push crashed: {e}")
+            # Refresh state-tabs after template push
+            if not dry_run:
+                try:
+                    from aipass.memory.apps.handlers.tracking.tab_renderer import refresh_all_tabs
+
+                    refresh_all_tabs()
+                except Exception as e:
+                    logger.warning(f"[templates] Tab refresh failed: {e}")
             return True
 
         if sub == "diff-templates":
@@ -162,6 +170,14 @@ def handle_command(command: str, args: List[str]) -> bool:
         except Exception as e:
             error(f"Spawn template push crashed: {e}")
             logger.error(f"[templates] spawn push crashed: {e}")
+        # Refresh state-tabs after template push
+        if not dry_run:
+            try:
+                from aipass.memory.apps.handlers.tracking.tab_renderer import refresh_all_tabs
+
+                refresh_all_tabs()
+            except Exception as e:
+                logger.warning(f"[templates] Tab refresh failed: {e}")
         return True
 
     elif command == "diff-templates":
diff --git a/src/aipass/memory/templates/.template_version.json b/src/aipass/memory/templates/.template_version.json
index bf10ddd1..0d154e48 100644
--- a/src/aipass/memory/templates/.template_version.json
+++ b/src/aipass/memory/templates/.template_version.json
@@ -1,7 +1,11 @@
 {
-  "last_push": "2026-06-07 21:40:48",
+  "last_push": "2026-06-25 01:55:01",
   "last_push_branches": [
+    "COMMONS",
+    "DAEMON",
     "HOOKS",
+    "SKILLS",
+    "ai_mail",
     "aipass",
     "api",
     "cli",
diff --git a/src/aipass/memory/templates/LOCAL.template.json b/src/aipass/memory/templates/LOCAL.template.json
index 2613c10a..9fa49282 100644
--- a/src/aipass/memory/templates/LOCAL.template.json
+++ b/src/aipass/memory/templates/LOCAL.template.json
@@ -12,14 +12,17 @@
       "work_log",
       "{{BRANCHNAME}}"
     ],
-    "_usage": "Automated file — add entries within your sections; rollover trims automatically. Limits live in @memory's memory.config.json.",
+    "_usage": "Automated file — add entries within your sections, newest on top. Rollover auto-archives sessions/key_learnings (+ observations.json) to @memory; todos[] are OPERATIONAL and NEVER rolled — prune done ones by hand at /prep. Limits live in @memory's memory.config.json.",
     "status": {
       "health": "healthy",
       "last_health_check": "{{DATE}}"
     }
   },
-  "key_learnings": [],
+  "todos_meta": "{{TODOS_META}}",
   "todos": [],
+  "key_learnings_meta": "{{KEY_LEARNINGS_META}}",
+  "key_learnings": [],
+  "sessions_meta": "{{SESSIONS_META}}",
   "sessions": [
     {
       "number": 1,
diff --git a/src/aipass/memory/templates/OBSERVATIONS.template.json b/src/aipass/memory/templates/OBSERVATIONS.template.json
index 8184b599..1f3938e0 100644
--- a/src/aipass/memory/templates/OBSERVATIONS.template.json
+++ b/src/aipass/memory/templates/OBSERVATIONS.template.json
@@ -12,7 +12,7 @@
       "patterns",
       "{{BRANCHNAME}}"
     ],
-    "_usage": "Automated file — add entries within your sections; rollover trims automatically. Limits live in @memory's memory.config.json.",
+    "_usage": "Automated file — add entries within your sections, newest on top. Rollover auto-archives sessions/key_learnings (+ observations.json) to @memory; todos[] are OPERATIONAL and NEVER rolled — prune done ones by hand at /prep. Limits live in @memory's memory.config.json.",
     "status": {
       "health": "healthy",
       "last_health_check": "{{DATE}}"
@@ -22,6 +22,7 @@
     "purpose": "Capture collaboration patterns and experiential insights over time",
     "chronological_order": "Newest entries at TOP, oldest at BOTTOM - NEVER reorder"
   },
+  "observations_meta": "{{OBSERVATIONS_META}}",
   "observations": [
     {
       "number": 1,
diff --git a/src/aipass/memory/tests/test_tab_renderer.py b/src/aipass/memory/tests/test_tab_renderer.py
new file mode 100644
index 00000000..0937a2ce
--- /dev/null
+++ b/src/aipass/memory/tests/test_tab_renderer.py
@@ -0,0 +1,571 @@
+# =================== AIPass ====================
+# Name: test_tab_renderer.py
+# Description: Tests for tab_renderer handler (FPLAN-0285)
+# Version: 1.0.0
+# Created: 2026-06-25
+# Modified: 2026-06-25
+# =============================================
+
+"""
+Tests for the tab_renderer handler.
+
+Covers:
+  1. render_tab() — correct strings for each section type.
+  2. render_tab() — per-branch overrides from config.
+  3. render_tab() — fallback to defaults when branch not in per_branch.
+  4. _reorder_keys() — canonical key ordering.
+  5. refresh_all_tabs() — reads config and writes tabs (mocked I/O).
+  6. Key ordering verification after tab insertion.
+"""
+
+import importlib
+import json
+import sys
+from pathlib import Path
+from unittest.mock import patch
+
+import pytest
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+
+@pytest.fixture(autouse=True)
+def _fresh_tab_renderer(monkeypatch):
+    """Drop cached module so each test gets a fresh import."""
+    for mod_name in list(sys.modules):
+        if "tab_renderer" in mod_name:
+            sys.modules.pop(mod_name, None)
+    # Also clear json sub-modules that conftest replaces with MagicMock
+    sys.modules.pop("aipass.memory.apps.handlers.json", None)
+    sys.modules.pop("aipass.memory.apps.handlers.json.json_handler", None)
+    yield
+
+
+def _get_module():
+    """Import and return the tab_renderer module."""
+    return importlib.import_module(
+        "aipass.memory.apps.handlers.tracking.tab_renderer",
+    )
+
+
+# ---------------------------------------------------------------------------
+# Shared config fixtures
+# ---------------------------------------------------------------------------
+
+SAMPLE_ROLLOVER_CFG = {
+    "defaults": {
+        "local": {
+            "sessions": {"count": 15},
+            "key_learnings": {"count": 15},
+        },
+        "observations": {
+            "observations": {"count": 15},
+        },
+    },
+    "per_branch": {
+        "devpulse": {
+            "local": {
+                "sessions": {"count": 20},
+                "key_learnings": {"count": 25},
+            },
+            "observations": {
+                "observations": {"count": 30},
+            },
+        },
+    },
+}
+
+SAMPLE_ENTRY_LIMITS_CFG = {
+    "entry_types": {
+        "key_learnings": {"field": "value", "max_chars": 200},
+        "sessions": {"field": "summary", "max_chars": 300},
+        "todos": {"field": "task", "max_chars": 150},
+        "observations": {"field": "note", "max_chars": 300},
+    },
+}
+
+
+# ===========================================================================
+# 1. render_tab — key_learnings (rollover ON)
+# ===========================================================================
+
+
+class TestRenderTabKeyLearnings:
+    def test_default_branch(self):
+        mod = _get_module()
+        tab = mod.render_tab(
+            "key_learnings",
+            SAMPLE_ROLLOVER_CFG,
+            SAMPLE_ENTRY_LIMITS_CFG,
+            "memory",
+        )
+        assert tab.startswith("⟦")
+        assert tab.endswith("⟧")
+        assert "rollover ON" in tab
+        assert "keep 15" in tab
+        assert "value ≤20" in tab  # ≤200
+
+    def test_per_branch_override(self):
+        mod = _get_module()
+        tab = mod.render_tab(
+            "key_learnings",
+            SAMPLE_ROLLOVER_CFG,
+            SAMPLE_ENTRY_LIMITS_CFG,
+            "devpulse",
+        )
+        assert "keep 25" in tab
+
+
+# ===========================================================================
+# 2. render_tab — sessions (rollover ON)
+# ===========================================================================
+
+
+class TestRenderTabSessions:
+    def test_sessions_default(self):
+        mod = _get_module()
+        tab = mod.render_tab(
+            "sessions",
+            SAMPLE_ROLLOVER_CFG,
+            SAMPLE_ENTRY_LIMITS_CFG,
+            "memory",
+        )
+        assert "rollover ON" in tab
+        assert "keep 15" in tab
+        assert "summary" in tab
+        assert "≤30" in tab  # ≤300
+
+    def test_sessions_per_branch(self):
+        mod = _get_module()
+        tab = mod.render_tab(
+            "sessions",
+            SAMPLE_ROLLOVER_CFG,
+            SAMPLE_ENTRY_LIMITS_CFG,
+            "devpulse",
+        )
+        assert "keep 20" in tab
+
+
+# ===========================================================================
+# 3. render_tab — observations (rollover ON)
+# ===========================================================================
+
+
+class TestRenderTabObservations:
+    def test_observations_default(self):
+        mod = _get_module()
+        tab = mod.render_tab(
+            "observations",
+            SAMPLE_ROLLOVER_CFG,
+            SAMPLE_ENTRY_LIMITS_CFG,
+            "memory",
+        )
+        assert "rollover ON" in tab
+        assert "keep 15" in tab
+        assert "note" in tab
+
+    def test_observations_per_branch(self):
+        mod = _get_module()
+        tab = mod.render_tab(
+            "observations",
+            SAMPLE_ROLLOVER_CFG,
+            SAMPLE_ENTRY_LIMITS_CFG,
+            "devpulse",
+        )
+        assert "keep 30" in tab
+
+
+# ===========================================================================
+# 4. render_tab — todos (rollover OFF, static shape)
+# ===========================================================================
+
+
+class TestRenderTabTodos:
+    def test_todos_static(self):
+        mod = _get_module()
+        tab = mod.render_tab(
+            "todos",
+            SAMPLE_ROLLOVER_CFG,
+            SAMPLE_ENTRY_LIMITS_CFG,
+            "memory",
+        )
+        assert "rollover OFF" in tab
+        assert "cap ~10 entries" in tab
+        assert "task ≤15" in tab  # ≤150
+        assert "RULE: DELETE" in tab
+        assert "BAU" in tab
+
+    def test_todos_ignores_per_branch_rollover(self):
+        """Todos are always rollover OFF regardless of per_branch config."""
+        mod = _get_module()
+        tab = mod.render_tab(
+            "todos",
+            SAMPLE_ROLLOVER_CFG,
+            SAMPLE_ENTRY_LIMITS_CFG,
+            "devpulse",
+        )
+        assert "rollover OFF" in tab
+
+
+# ===========================================================================
+# 5. _reorder_keys — canonical key ordering
+# ===========================================================================
+
+
+class TestReorderKeys:
+    def test_local_key_order(self):
+        mod = _get_module()
+        data = {
+            "sessions": [],
+            "document_metadata": {},
+            "todos": [],
+            "key_learnings": [],
+            "extra_field": "preserved",
+        }
+        ordered = mod._reorder_keys(data, mod._LOCAL_KEY_ORDER)
+        keys = list(ordered.keys())
+        assert keys[0] == "document_metadata"
+        # todos before key_learnings before sessions
+        assert keys.index("todos") < keys.index("key_learnings")
+        assert keys.index("key_learnings") < keys.index("sessions")
+        # extra_field at the end
+        assert keys[-1] == "extra_field"
+
+    def test_observations_key_order(self):
+        mod = _get_module()
+        data = {
+            "observations": [],
+            "document_metadata": {},
+            "guidelines": {},
+            "observations_meta": "tab",
+        }
+        ordered = mod._reorder_keys(data, mod._OBSERVATIONS_KEY_ORDER)
+        keys = list(ordered.keys())
+        assert keys == [
+            "document_metadata",
+            "guidelines",
+            "observations_meta",
+            "observations",
+        ]
+
+    def test_meta_before_array(self):
+        """Meta key must appear immediately before its corresponding array."""
+        mod = _get_module()
+        data = {
+            "document_metadata": {},
+            "todos": [],
+            "todos_meta": "tab-todos",
+            "key_learnings": [],
+            "key_learnings_meta": "tab-kl",
+            "sessions": [],
+            "sessions_meta": "tab-sessions",
+        }
+        ordered = mod._reorder_keys(data, mod._LOCAL_KEY_ORDER)
+        keys = list(ordered.keys())
+        # Each *_meta must be immediately before its array
+        assert keys.index("todos_meta") + 1 == keys.index("todos")
+        assert keys.index("key_learnings_meta") + 1 == keys.index(
+            "key_learnings",
+        )
+        assert keys.index("sessions_meta") + 1 == keys.index("sessions")
+
+
+# ===========================================================================
+# 6. refresh_all_tabs — integration with mocked I/O
+# ===========================================================================
+
+
+class TestRefreshAllTabs:
+    def _make_local_data(self):
+        return {
+            "document_metadata": {"document_type": "session_history"},
+            "todos": [{"task": "test"}],
+            "key_learnings": [],
+            "sessions": [],
+        }
+
+    def _make_obs_data(self):
+        return {
+            "document_metadata": {
+                "document_type": "collaboration_patterns",
+            },
+            "guidelines": {},
+            "observations": [],
+        }
+
+    def test_writes_tabs_to_files(self, tmp_path):
+        """refresh_all_tabs reads config, walks branches, writes tabs."""
+        mod = _get_module()
+
+        # Set up branch dir with .trinity files
+        branch_dir = tmp_path / "src" / "aipass" / "test_branch"
+        trinity = branch_dir / ".trinity"
+        trinity.mkdir(parents=True)
+
+        local_path = trinity / "local.json"
+        obs_path = trinity / "observations.json"
+        local_path.write_text(
+            json.dumps(self._make_local_data(), indent=2),
+            encoding="utf-8",
+        )
+        obs_path.write_text(
+            json.dumps(self._make_obs_data(), indent=2),
+            encoding="utf-8",
+        )
+
+        # Mock registry to return our test branch
+        mock_branches = [
+            {"name": "test_branch", "path": str(branch_dir)},
+        ]
+
+        def mock_get_path(branch, mem_type):
+            p = Path(branch["path"]) / ".trinity" / f"{mem_type}.json"
+            return p if p.exists() else None
+
+        mock_config = {
+            "rollover": SAMPLE_ROLLOVER_CFG,
+            "entry_limits": SAMPLE_ENTRY_LIMITS_CFG,
+        }
+
+        with (
+            patch(
+                "aipass.memory.apps.handlers.json.config_loader.load",
+                return_value=mock_config,
+            ),
+            patch(
+                "aipass.memory.apps.handlers.monitor.detector._read_registry",
+                return_value=mock_branches,
+            ),
+            patch(
+                "aipass.memory.apps.handlers.monitor.detector._get_memory_file_path",
+                side_effect=mock_get_path,
+            ),
+        ):
+            result = mod.refresh_all_tabs()
+
+        assert result["success"] is True
+        assert result["updated"] == 2  # local + observations
+
+        # Verify local.json has tabs
+        local_data = json.loads(local_path.read_text(encoding="utf-8"))
+        assert "todos_meta" in local_data
+        assert "key_learnings_meta" in local_data
+        assert "sessions_meta" in local_data
+        assert "rollover OFF" in local_data["todos_meta"]
+        assert "rollover ON" in local_data["key_learnings_meta"]
+        assert "rollover ON" in local_data["sessions_meta"]
+
+        # Verify observations.json has tab
+        obs_data = json.loads(obs_path.read_text(encoding="utf-8"))
+        assert "observations_meta" in obs_data
+        assert "rollover ON" in obs_data["observations_meta"]
+
+    def test_key_order_after_refresh(self, tmp_path):
+        """After refresh, keys are in canonical order."""
+        mod = _get_module()
+
+        branch_dir = tmp_path / "src" / "aipass" / "ordered_branch"
+        trinity = branch_dir / ".trinity"
+        trinity.mkdir(parents=True)
+
+        local_path = trinity / "local.json"
+        local_path.write_text(
+            json.dumps(self._make_local_data(), indent=2),
+            encoding="utf-8",
+        )
+
+        obs_path = trinity / "observations.json"
+        obs_path.write_text(
+            json.dumps(self._make_obs_data(), indent=2),
+            encoding="utf-8",
+        )
+
+        mock_branches = [
+            {"name": "ordered_branch", "path": str(branch_dir)},
+        ]
+
+        def mock_get_path(branch, mem_type):
+            p = Path(branch["path"]) / ".trinity" / f"{mem_type}.json"
+            return p if p.exists() else None
+
+        mock_config = {
+            "rollover": SAMPLE_ROLLOVER_CFG,
+            "entry_limits": SAMPLE_ENTRY_LIMITS_CFG,
+        }
+
+        with (
+            patch(
+                "aipass.memory.apps.handlers.json.config_loader.load",
+                return_value=mock_config,
+            ),
+            patch(
+                "aipass.memory.apps.handlers.monitor.detector._read_registry",
+                return_value=mock_branches,
+            ),
+            patch(
+                "aipass.memory.apps.handlers.monitor.detector._get_memory_file_path",
+                side_effect=mock_get_path,
+            ),
+        ):
+            mod.refresh_all_tabs()
+
+        local_data = json.loads(local_path.read_text(encoding="utf-8"))
+        keys = list(local_data.keys())
+        expected_prefix = [
+            "document_metadata",
+            "todos_meta",
+            "todos",
+            "key_learnings_meta",
+            "key_learnings",
+            "sessions_meta",
+            "sessions",
+        ]
+        assert keys[: len(expected_prefix)] == expected_prefix
+
+    def test_empty_registry(self):
+        """refresh_all_tabs returns early if no branches in registry."""
+        mod = _get_module()
+
+        mock_config = {
+            "rollover": SAMPLE_ROLLOVER_CFG,
+            "entry_limits": SAMPLE_ENTRY_LIMITS_CFG,
+        }
+
+        with (
+            patch(
+                "aipass.memory.apps.handlers.json.config_loader.load",
+                return_value=mock_config,
+            ),
+            patch(
+                "aipass.memory.apps.handlers.monitor.detector._read_registry",
+                return_value=[],
+            ),
+        ):
+            result = mod.refresh_all_tabs()
+
+        assert result["success"] is True
+        assert result["updated"] == 0
+        assert "No branches" in result.get("message", "")
+
+    def test_no_templates_updated_key(self, tmp_path):
+        """refresh_all_tabs result dict has no templates_updated key (literal-baking removed)."""
+        mod = _get_module()
+        mock_config = {
+            "rollover": SAMPLE_ROLLOVER_CFG,
+            "entry_limits": SAMPLE_ENTRY_LIMITS_CFG,
+        }
+        with (
+            patch(
+                "aipass.memory.apps.handlers.json.config_loader.load",
+                return_value=mock_config,
+            ),
+            patch(
+                "aipass.memory.apps.handlers.monitor.detector._read_registry",
+                return_value=[],
+            ),
+        ):
+            result = mod.refresh_all_tabs()
+        assert "templates_updated" not in result
+
+    def test_missing_file_skipped(self, tmp_path):
+        """Branch with missing .trinity files is skipped, not errored."""
+        mod = _get_module()
+
+        branch_dir = tmp_path / "src" / "aipass" / "empty_branch"
+        branch_dir.mkdir(parents=True)
+        # No .trinity directory at all
+
+        mock_branches = [
+            {"name": "empty_branch", "path": str(branch_dir)},
+        ]
+
+        def mock_get_path(branch, mem_type):
+            p = Path(branch["path"]) / ".trinity" / f"{mem_type}.json"
+            return p if p.exists() else None
+
+        mock_config = {
+            "rollover": SAMPLE_ROLLOVER_CFG,
+            "entry_limits": SAMPLE_ENTRY_LIMITS_CFG,
+        }
+
+        with (
+            patch(
+                "aipass.memory.apps.handlers.json.config_loader.load",
+                return_value=mock_config,
+            ),
+            patch(
+                "aipass.memory.apps.handlers.monitor.detector._read_registry",
+                return_value=mock_branches,
+            ),
+            patch(
+                "aipass.memory.apps.handlers.monitor.detector._get_memory_file_path",
+                side_effect=mock_get_path,
+            ),
+        ):
+            result = mod.refresh_all_tabs()
+
+        assert result["success"] is True
+        assert result["skipped"] == 2  # local + observations
+        assert result["updated"] == 0
+
+
+# ===========================================================================
+# 8. render_all_meta_tabs — public API for spawn
+# ===========================================================================
+
+
+class TestRenderAllMetaTabs:
+    def test_returns_four_keys(self):
+        mod = _get_module()
+        mock_config = {
+            "rollover": SAMPLE_ROLLOVER_CFG,
+            "entry_limits": SAMPLE_ENTRY_LIMITS_CFG,
+        }
+        with patch(
+            "aipass.memory.apps.handlers.json.config_loader.load",
+            return_value=mock_config,
+        ):
+            tabs = mod.render_all_meta_tabs()
+
+        assert set(tabs.keys()) == {
+            "TODOS_META",
+            "KEY_LEARNINGS_META",
+            "SESSIONS_META",
+            "OBSERVATIONS_META",
+        }
+
+    def test_values_are_rendered_strings(self):
+        mod = _get_module()
+        mock_config = {
+            "rollover": SAMPLE_ROLLOVER_CFG,
+            "entry_limits": SAMPLE_ENTRY_LIMITS_CFG,
+        }
+        with patch(
+            "aipass.memory.apps.handlers.json.config_loader.load",
+            return_value=mock_config,
+        ):
+            tabs = mod.render_all_meta_tabs()
+
+        assert "rollover OFF" in tabs["TODOS_META"]
+        assert "rollover ON" in tabs["KEY_LEARNINGS_META"]
+        assert "rollover ON" in tabs["SESSIONS_META"]
+        assert "rollover ON" in tabs["OBSERVATIONS_META"]
+        assert "{{" not in tabs["TODOS_META"]
+
+    def test_uses_defaults_not_per_branch(self):
+        mod = _get_module()
+        mock_config = {
+            "rollover": SAMPLE_ROLLOVER_CFG,
+            "entry_limits": SAMPLE_ENTRY_LIMITS_CFG,
+        }
+        with patch(
+            "aipass.memory.apps.handlers.json.config_loader.load",
+            return_value=mock_config,
+        ):
+            tabs = mod.render_all_meta_tabs()
+
+        assert "keep 15" in tabs["KEY_LEARNINGS_META"]
+        assert "keep 15" in tabs["SESSIONS_META"]
diff --git a/src/aipass/prax/.backupignore b/src/aipass/prax/.backupignore
deleted file mode 100644
index aef1a733..00000000
--- a/src/aipass/prax/.backupignore
+++ /dev/null
@@ -1,39 +0,0 @@
-# Backup System ignore patterns (gitignore-style)
-# Lines starting with # are comments. Blank lines are ignored.
-
-# Backup system's own directory
-.backup_system/
-
-# Version control
-.git/
-.svn/
-.hg/
-
-# Python
-__pycache__/
-*.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
diff --git a/src/aipass/prax/CLOSED_PLANS.local.json b/src/aipass/prax/CLOSED_PLANS.local.json
index 48d24f15..b8f76701 100644
--- a/src/aipass/prax/CLOSED_PLANS.local.json
+++ b/src/aipass/prax/CLOSED_PLANS.local.json
@@ -73,25 +73,19 @@
   ],
   "document_metadata": {
     "version": "2.0.0",
-    "schema_version": "2.0.0",
+    "schema_version": "3.0.0",
     "document_type": "session_history",
     "tags": [
       "session_tracking",
       "work_log",
       "prax"
     ],
-    "limits": {
-      "max_sessions": 20,
-      "max_key_learnings": 25,
-      "session_summary_max_chars": 150,
-      "learning_value_max_chars": 200,
-      "note": "DO NOT trim, prune, or delete entries. Rollover to @memory handles overflow automatically. Just add new entries."
-    },
     "status": {
       "health": "healthy",
       "last_health_check": "2026-04-22",
       "current_lines": 0
     }
   },
-  "key_learnings": {}
+  "key_learnings": {},
+  "todos": []
 }
diff --git a/src/aipass/prax/apps/handlers/logging/introspection.py b/src/aipass/prax/apps/handlers/logging/introspection.py
index 2765f611..6abf8116 100755
--- a/src/aipass/prax/apps/handlers/logging/introspection.py
+++ b/src/aipass/prax/apps/handlers/logging/introspection.py
@@ -14,13 +14,13 @@ Used by logger_setup.py to route logs to correct files.
 """
 
 import logging
-
-logger = logging.getLogger(__name__)
 from pathlib import Path
 from typing import Optional
 
 from aipass.prax.apps.handlers.json import json_handler
 
+logger = logging.getLogger(__name__)
+
 _PRAX_INTERNAL_MARKERS = (
     "/prax/apps/modules/logger.py",
     "/prax/apps/handlers/",
@@ -85,14 +85,29 @@ def get_caller_info() -> tuple:
     get_calling_module_path() are called separately from different
     stack depths, potentially finding different external callers.
 
+    Env var overrides (checked in order):
+        AIPASS_LOG_NAME  — explicit module name override for any process
+        AIPASS_BOT_ID    — set by telegram-bot@.service, mapped to bot_{id}
+
     Returns:
         (module_name, module_path, branch_name) — branch_name may be None
     """
+    import os
+
     caller_path = _find_external_caller_path()
+    branch = detect_branch_from_path(caller_path) if caller_path else None
+
+    log_name = os.environ.get("AIPASS_LOG_NAME")
+    if log_name:
+        return (log_name, caller_path, branch)
+
+    bot_id = os.environ.get("AIPASS_BOT_ID")
+    if bot_id:
+        return (f"bot_{bot_id}", caller_path, branch)
+
     if not caller_path:
         return ("unknown_module", None, None)
     module_name = Path(caller_path).stem
-    branch = detect_branch_from_path(caller_path)
     return (module_name, caller_path, branch)
 
 
diff --git a/src/aipass/prax/apps/handlers/monitoring/telegram_relay.py b/src/aipass/prax/apps/handlers/monitoring/telegram_relay.py
new file mode 100644
index 00000000..6def5e8f
--- /dev/null
+++ b/src/aipass/prax/apps/handlers/monitoring/telegram_relay.py
@@ -0,0 +1,217 @@
+# =================== AIPass ====================
+# Name: telegram_relay.py
+# Description: Telegram relay for prax monitor feed
+# Version: 1.0.0
+# Created: 2026-06-24
+# Modified: 2026-06-24
+# =============================================
+
+"""
+Telegram relay for prax monitor — mirrors the live console feed to a Telegram chat.
+
+Buffers events in a thread-safe list, flushes every 5s via a daemon thread.
+Activation requires --relay flag or AIPASS_PRAX_MONITOR_RELAY=1, plus a valid
+bot config passed by the module layer (monitor.py loads from @api secrets).
+"""
+
+import json
+import os
+import threading
+from datetime import datetime
+from typing import Optional
+from urllib.error import URLError
+from urllib.request import Request
+from urllib.request import urlopen as _http_fetch
+
+from aipass.prax.apps.modules.logger import get_direct_logger
+from aipass.prax.apps.handlers.json import json_handler
+
+logger = get_direct_logger()
+
+BATCH_INTERVAL = 5.0
+TELEGRAM_MAX_LENGTH = 4000
+FLOOD_CAP = 150
+
+_lock = threading.Lock()
+_buffer: list[str] = []
+_thread: Optional[threading.Thread] = None
+_stop_event = threading.Event()
+_bot_token: Optional[str] = None
+_chat_id: Optional[int] = None
+_RELAY_ACTIVE = False
+
+
+def init_relay(enabled: bool, config: Optional[dict] = None) -> None:
+    """Start the relay if enabled and config is valid. Safe no-op otherwise.
+
+    Args:
+        enabled: Whether the relay flag is set.
+        config: Bot config dict with 'bot_token' and 'chat_id' keys.
+               Loaded by the module layer from @api secrets.
+    """
+    global _RELAY_ACTIVE, _bot_token, _chat_id, _thread
+
+    if not enabled:
+        return
+
+    json_handler.log_operation("relay_init", {"enabled": enabled, "has_config": config is not None})
+
+    if config is None:
+        logger.info("[telegram_relay] No config provided — relay inactive")
+        return
+
+    token = config.get("bot_token", "")
+    chat = config.get("chat_id")
+    if not token or not chat:
+        logger.info("[telegram_relay] Incomplete config (missing bot_token or chat_id) — relay inactive")
+        return
+
+    _bot_token = token
+    _chat_id = int(chat)
+    _RELAY_ACTIVE = True
+
+    _stop_event.clear()
+    _thread = threading.Thread(target=_flush_loop, name="telegram-relay", daemon=True)
+    _thread.start()
+    logger.info("[telegram_relay] Relay started (chat_id=%s)", _chat_id)
+
+
+def relay_event(event) -> None:
+    """Format a MonitoringEvent and buffer for Telegram delivery. No-op when inactive."""
+    if not _RELAY_ACTIVE:
+        return
+
+    line = _format_event(event)
+    if not line:
+        return
+
+    with _lock:
+        _buffer.append(line)
+
+
+def stop_relay() -> None:
+    """Final flush and thread shutdown. Safe no-op when inactive."""
+    global _RELAY_ACTIVE, _thread
+
+    if not _RELAY_ACTIVE:
+        return
+
+    _RELAY_ACTIVE = False
+    _stop_event.set()
+
+    _flush_buffer()
+
+    if _thread is not None:
+        _thread.join(timeout=BATCH_INTERVAL + 2)
+        _thread = None
+
+    json_handler.log_operation("relay_stopped", {})
+    logger.info("[telegram_relay] Relay stopped")
+
+
+def _format_event(event) -> Optional[str]:
+    """Format a MonitoringEvent as a plain-text line (no Rich markup)."""
+    ts = datetime.now().strftime("%H:%M:%S")
+
+    if event.event_type == "command":
+        parts = [f"▶ {event.message}"]
+        caller = getattr(event, "caller", None)
+        target = None
+        if hasattr(event, "action") and event.action and ":" in event.action:
+            action_parts = event.action.split(":", 1)
+            if len(action_parts) == 2 and action_parts[1]:
+                target = action_parts[1]
+        if caller and caller.upper() != "UNKNOWN":
+            attr = caller
+            if target:
+                attr = f"{caller} → {target}"
+            parts.insert(0, f"  {attr}")
+        return "\n".join(parts)
+
+    if event.event_type == "hook":
+        action = getattr(event, "action", "unknown")
+        if action == "fired":
+            return f"⚡ HOOK {event.message}"
+        if action == "skipped":
+            return f"· HOOK {event.message}"
+        return f"? HOOK {event.message}"
+
+    branch_label = event.branch.upper()
+    pid = getattr(event, "pid", None)
+    if pid:
+        branch_label = f"{branch_label}:{pid}"
+    return f"[{ts}] [{branch_label}] {event.message}"
+
+
+def _flush_buffer() -> None:
+    """Drain buffer and send to Telegram."""
+    with _lock:
+        if not _buffer:
+            return
+        lines = list(_buffer)
+        _buffer.clear()
+
+    if not _bot_token or not _chat_id:
+        return
+
+    if len(lines) > FLOOD_CAP:
+        suppressed = len(lines) - FLOOD_CAP
+        lines = lines[:FLOOD_CAP]
+        lines.append(f"…({suppressed} more suppressed)")
+
+    _send_batched(lines)
+
+
+def _flush_loop() -> None:
+    """Background thread: flush buffer every BATCH_INTERVAL seconds."""
+    while not _stop_event.is_set():
+        _stop_event.wait(BATCH_INTERVAL)
+        if _buffer:
+            _flush_buffer()
+
+
+def _send_batched(lines: list[str]) -> None:
+    """Split lines into ≤4000-char chunks and POST each to Telegram."""
+    if not lines:
+        return
+
+    batch: list[str] = []
+    batch_len = 0
+
+    for line in lines:
+        line_len = len(line) + (1 if batch else 0)
+        if batch_len + line_len > TELEGRAM_MAX_LENGTH and batch:
+            _send_message("\n".join(batch))
+            batch = []
+            batch_len = 0
+        batch.append(line)
+        batch_len += line_len
+
+    if batch:
+        _send_message("\n".join(batch))
+
+
+def _send_message(text: str) -> bool:
+    """POST a single message to the Telegram Bot API."""
+    url = f"https://api.telegram.org/bot{_bot_token}/sendMessage"
+    payload = json.dumps(
+        {
+            "chat_id": _chat_id,
+            "text": text,
+            "disable_notification": True,
+        }
+    ).encode("utf-8")
+    req = Request(url, data=payload, headers={"Content-Type": "application/json"})
+
+    try:
+        with _http_fetch(req, timeout=10) as resp:
+            result = json.loads(resp.read().decode("utf-8"))
+            return result.get("ok", False)
+    except (URLError, Exception) as e:
+        logger.warning("[telegram_relay] Send failed: %s", e)
+        return False
+
+
+def is_relay_enabled_by_env() -> bool:
+    """Check if the relay is enabled via environment variable."""
+    return os.environ.get("AIPASS_PRAX_MONITOR_RELAY", "").strip() in ("1", "true", "yes")
diff --git a/src/aipass/prax/apps/modules/monitor.py b/src/aipass/prax/apps/modules/monitor.py
index 4b04251d..373c7287 100755
--- a/src/aipass/prax/apps/modules/monitor.py
+++ b/src/aipass/prax/apps/modules/monitor.py
@@ -43,6 +43,12 @@ from aipass.prax.apps.handlers.monitoring import (
     ModuleTracker,  # module_tracker.py
 )
 from aipass.prax.apps.handlers.monitoring.event_queue import MonitoringEvent
+from aipass.prax.apps.handlers.monitoring.telegram_relay import (
+    init_relay,
+    relay_event,
+    stop_relay,
+    is_relay_enabled_by_env,
+)
 
 
 # =============================================================================
@@ -188,6 +194,10 @@ def print_help():
     console.print("    Monitor specific branches (comma-separated)")
     console.print("    Example: drone @prax monitor run seedgo,cli,flow")
     console.print()
+    console.print("  [cyan]drone @prax monitor run --relay[/cyan]")
+    console.print("    Enable Telegram relay (mirrors feed to prax_monitor bot)")
+    console.print("    Also enabled by env AIPASS_PRAX_MONITOR_RELAY=1")
+    console.print()
     console.print("  [cyan]drone @prax monitor --help[/cyan]")
     console.print("    Show this help")
     console.print()
@@ -249,6 +259,17 @@ def handle_command(command: str, args: List[str]) -> bool:
     return True
 
 
+def _load_relay_config() -> Optional[dict]:
+    """Load Telegram relay config from @api secrets."""
+    try:
+        from aipass.api.apps.modules.secrets import get_secret
+
+        return get_secret("telegram", "prax_monitor", as_json=True)
+    except Exception as e:
+        logger.info("[monitor] Could not load relay config: %s", e)
+        return None
+
+
 def _run_monitor(args: List[str]) -> bool:
     """Launch Mission Control live monitoring."""
     global _event_queue, _module_tracker
@@ -262,6 +283,14 @@ def _run_monitor(args: List[str]) -> bool:
     _module_tracker = ModuleTracker()
     _stop_event.clear()
 
+    # Initialize Telegram relay (--relay flag or env var)
+    _relay_enabled = "--relay" in args or is_relay_enabled_by_env()
+    if _relay_enabled:
+        args = [a for a in args if a != "--relay"]
+    init_relay(_relay_enabled, _load_relay_config() if _relay_enabled else None)
+    if _relay_enabled:
+        console.print("[green]monitor → Telegram relay ON (prax_monitor)[/green]")
+
     _is_tty = sys.stdin.isatty()
 
     # Display header
@@ -311,10 +340,11 @@ def _start_threads():
 
 
 def _stop_threads():
-    """Stop all monitoring threads"""
+    """Stop all monitoring threads and Telegram relay"""
     global _event_queue
 
     _stop_event.set()
+    stop_relay()
 
     if _event_queue:
         _event_queue.stop()
@@ -328,7 +358,7 @@ def _stop_threads():
 
 
 def _render_event(event) -> None:
-    """Render a single monitoring event to the console."""
+    """Render a single monitoring event to the console, and relay to Telegram."""
     branch_pid = _get_pid_for_branch(event.branch)
 
     if event.event_type == "command":
@@ -344,6 +374,8 @@ def _render_event(event) -> None:
     else:
         print_event(event.event_type, event.branch, event.message, event.level, pid=branch_pid)
 
+    relay_event(event)
+
 
 def _display_worker():
     """Display thread - pulls events from queue and displays them. No filtering."""
diff --git a/src/aipass/prax/prax-monitor.service b/src/aipass/prax/prax-monitor.service
new file mode 100644
index 00000000..a1fd6b4b
--- /dev/null
+++ b/src/aipass/prax/prax-monitor.service
@@ -0,0 +1,34 @@
+# Systemd user service for the prax monitor with Telegram relay.
+#
+# Install:
+#   cp prax-monitor.service ~/.config/systemd/user/
+#   systemctl --user daemon-reload
+#
+# Usage:
+#   systemctl --user start  prax-monitor
+#   systemctl --user enable prax-monitor   # auto-start on login
+#   systemctl --user status prax-monitor
+
+[Unit]
+Description=AIPass Prax Monitor — Telegram relay
+After=network-online.target
+Wants=network-online.target
+
+[Service]
+Type=simple
+# NOTE: the module __main__ takes a single positional (the subcommand); 'run' →
+# _run_monitor([]) = all branches. The relay is enabled by the env var below
+# (the __main__ argparse rejects extra tokens like 'all --relay').
+ExecStart=%h/Projects/AIPass/.venv/bin/python3 -m aipass.prax.apps.modules.monitor run
+WorkingDirectory=%h/Projects/AIPass
+Environment=AIPASS_PRAX_MONITOR_RELAY=1
+Restart=always
+RestartSec=5
+# IMPORTANT: log OUTSIDE system_logs/ — the monitor tails system_logs/*.log and
+# @trigger watches it too. Writing the monitor's own output there creates a
+# feedback loop (monitor output → re-tailed/recorded → reported → more output).
+StandardOutput=append:%h/.aipass/prax-monitor.service.log
+StandardError=append:%h/.aipass/prax-monitor.service.log
+
+[Install]
+WantedBy=default.target
diff --git a/src/aipass/prax/tests/test_monitor_module.py b/src/aipass/prax/tests/test_monitor_module.py
index 4beffded..31b7332f 100644
--- a/src/aipass/prax/tests/test_monitor_module.py
+++ b/src/aipass/prax/tests/test_monitor_module.py
@@ -40,6 +40,7 @@ _MONITORING_MOCKS = {
     "aipass.prax.apps.handlers.monitoring.interactive_filter": MagicMock(),
     "aipass.prax.apps.handlers.monitoring.monitoring_filters": MagicMock(),
     "aipass.prax.apps.handlers.monitoring.file_watcher_integration": MagicMock(),
+    "aipass.prax.apps.handlers.monitoring.telegram_relay": MagicMock(),
 }
 
 
diff --git a/src/aipass/prax/tests/test_telegram_relay.py b/src/aipass/prax/tests/test_telegram_relay.py
new file mode 100644
index 00000000..fdba8e93
--- /dev/null
+++ b/src/aipass/prax/tests/test_telegram_relay.py
@@ -0,0 +1,411 @@
+# =================== AIPass ====================
+# Name: test_telegram_relay.py
+# Description: Tests for the Telegram relay handler
+# Version: 1.0.0
+# Created: 2026-06-24
+# Modified: 2026-06-24
+# =============================================
+
+"""Tests for apps/handlers/monitoring/telegram_relay.py
+
+Covers:
+- Event formatting (log, command, hook types, PID labels)
+- init_relay: disabled path, missing config, incomplete config, successful start
+- Fail-silent-once: exactly one log line when config absent, zero sends
+- stop_relay: final flush and thread join, no-op when inactive
+- relay_event: buffering when active, no-op when inactive
+- Batching: 4000-char split across messages
+- Flood cap: truncation at 150 lines with suppression notice
+- _render_event calls relay_event in monitor.py
+- is_relay_enabled_by_env for env var detection
+"""
+
+import importlib
+import sys
+from dataclasses import dataclass, field
+from datetime import datetime
+from typing import Optional
+from unittest.mock import MagicMock, patch
+
+
+@dataclass
+class FakeEvent:
+    """Minimal MonitoringEvent stand-in for tests."""
+
+    priority: int = 3
+    timestamp: datetime = field(default_factory=datetime.now)
+    event_type: str = ""
+    branch: str = ""
+    action: str = ""
+    message: str = ""
+    level: str = "info"
+    caller: Optional[str] = None
+    pid: Optional[int] = None
+
+
+def _import_relay():
+    """Import (or reload) telegram_relay with mocked dependencies."""
+    fresh_mocks = {
+        "aipass.prax.apps.modules.logger": MagicMock(),
+        "aipass.prax.apps.handlers.json": MagicMock(),
+        "aipass.prax.apps.handlers.json.json_handler": MagicMock(),
+    }
+    with patch.dict(sys.modules, fresh_mocks):
+        if "aipass.prax.apps.handlers.monitoring.telegram_relay" in sys.modules:
+            mod = importlib.reload(sys.modules["aipass.prax.apps.handlers.monitoring.telegram_relay"])
+        else:
+            mod = importlib.import_module("aipass.prax.apps.handlers.monitoring.telegram_relay")
+
+    setattr(mod, "_RELAY_ACTIVE", False)
+    setattr(mod, "_bot_token", None)
+    setattr(mod, "_chat_id", None)
+    mod._buffer.clear()
+    mod._stop_event.clear()
+    setattr(mod, "_thread", None)
+    return mod
+
+
+# ---------------------------------------------------------------------------
+# Event formatting
+# ---------------------------------------------------------------------------
+
+
+class TestFormatEvent:
+    """Test _format_event produces correct plain-text lines."""
+
+    def test_log_event_basic(self):
+        """Log event includes uppercased branch and message."""
+        relay = _import_relay()
+        event = FakeEvent(event_type="log", branch="seedgo", message="Audit started")
+        result = relay._format_event(event)
+        assert "[SEEDGO]" in result
+        assert "Audit started" in result
+
+    def test_log_event_with_pid(self):
+        """Log event with PID shows BRANCH:PID label."""
+        relay = _import_relay()
+        event = FakeEvent(event_type="log", branch="devpulse", message="Working", pid=12345)
+        result = relay._format_event(event)
+        assert "[DEVPULSE:12345]" in result
+
+    def test_command_event(self):
+        """Command event shows arrow prefix."""
+        relay = _import_relay()
+        event = FakeEvent(event_type="command", branch="drone", message="seedgo audit", action="")
+        result = relay._format_event(event)
+        assert "▶ seedgo audit" in result
+
+    def test_command_event_with_caller_and_target(self):
+        """Command event with caller and target shows attribution line."""
+        relay = _import_relay()
+        event = FakeEvent(
+            event_type="command",
+            branch="drone",
+            message="seedgo audit",
+            action="run:prax",
+            caller="devpulse",
+        )
+        result = relay._format_event(event)
+        assert "devpulse → prax" in result
+        assert "▶ seedgo audit" in result
+
+    def test_command_event_unknown_caller_omitted(self):
+        """Command event with UNKNOWN caller omits caller line."""
+        relay = _import_relay()
+        event = FakeEvent(
+            event_type="command",
+            branch="drone",
+            message="test",
+            caller="UNKNOWN",
+        )
+        result = relay._format_event(event)
+        assert "UNKNOWN" not in result
+
+    def test_hook_event_fired(self):
+        """Fired hook event uses lightning bolt symbol."""
+        relay = _import_relay()
+        event = FakeEvent(event_type="hook", branch="hooks", message="cadence:fired", action="fired")
+        result = relay._format_event(event)
+        assert result == "⚡ HOOK cadence:fired"
+
+    def test_hook_event_skipped(self):
+        """Skipped hook event uses dot symbol."""
+        relay = _import_relay()
+        event = FakeEvent(event_type="hook", branch="hooks", message="cadence:skipped", action="skipped")
+        result = relay._format_event(event)
+        assert result == "· HOOK cadence:skipped"
+
+    def test_hook_event_unknown_action(self):
+        """Unknown hook action uses question mark symbol."""
+        relay = _import_relay()
+        event = FakeEvent(event_type="hook", branch="hooks", message="something", action="other")
+        result = relay._format_event(event)
+        assert result.startswith("? HOOK")
+
+    def test_file_event(self):
+        """File event formats like a log event with branch and message."""
+        relay = _import_relay()
+        event = FakeEvent(event_type="file", branch="prax", message="monitor.py modified")
+        result = relay._format_event(event)
+        assert "[PRAX]" in result
+        assert "monitor.py modified" in result
+
+
+# ---------------------------------------------------------------------------
+# init_relay
+# ---------------------------------------------------------------------------
+
+
+class TestInitRelay:
+    """Test init_relay activation and fail-silent behavior."""
+
+    def test_disabled_is_noop(self):
+        """Disabled flag skips all initialization."""
+        relay = _import_relay()
+        relay.init_relay(enabled=False)
+        assert relay._RELAY_ACTIVE is False
+        assert relay._thread is None
+
+    def test_no_config_stays_inactive(self):
+        """None config keeps relay inactive."""
+        relay = _import_relay()
+        relay.init_relay(enabled=True, config=None)
+        assert relay._RELAY_ACTIVE is False
+
+    def test_no_config_logs_exactly_once(self):
+        """Missing config produces exactly one info log, not per-cycle spam."""
+        relay = _import_relay()
+        relay.init_relay(enabled=True, config=None)
+        calls = [c for c in relay.logger.info.call_args_list if "inactive" in str(c)]
+        assert len(calls) == 1
+
+    def test_incomplete_config_missing_chat_id(self):
+        """Config without chat_id stays inactive."""
+        relay = _import_relay()
+        relay.init_relay(enabled=True, config={"bot_token": "tok123"})
+        assert relay._RELAY_ACTIVE is False
+
+    def test_incomplete_config_missing_token(self):
+        """Config without bot_token stays inactive."""
+        relay = _import_relay()
+        relay.init_relay(enabled=True, config={"chat_id": 123})
+        assert relay._RELAY_ACTIVE is False
+
+    def test_valid_config_activates(self):
+        """Valid config sets active flag and stores credentials."""
+        relay = _import_relay()
+        relay.init_relay(enabled=True, config={"bot_token": "tok123", "chat_id": 456})
+        assert relay._RELAY_ACTIVE is True
+        assert relay._bot_token == "tok123"
+        assert relay._chat_id == 456
+        assert relay._thread is not None
+        relay.stop_relay()
+
+    def test_valid_config_starts_daemon_thread(self):
+        """Valid config starts a named daemon thread."""
+        relay = _import_relay()
+        relay.init_relay(enabled=True, config={"bot_token": "t", "chat_id": 1})
+        assert relay._thread.daemon is True
+        assert relay._thread.name == "telegram-relay"
+        relay.stop_relay()
+
+
+# ---------------------------------------------------------------------------
+# relay_event
+# ---------------------------------------------------------------------------
+
+
+class TestRelayEvent:
+    """Test relay_event buffering."""
+
+    def test_noop_when_inactive(self):
+        """Inactive relay does not buffer events."""
+        relay = _import_relay()
+        event = FakeEvent(event_type="log", branch="test", message="hello")
+        relay.relay_event(event)
+        assert len(relay._buffer) == 0
+
+    def test_buffers_when_active(self):
+        """Active relay appends formatted line to buffer."""
+        relay = _import_relay()
+        setattr(relay, "_RELAY_ACTIVE", True)
+        event = FakeEvent(event_type="log", branch="test", message="hello")
+        relay.relay_event(event)
+        assert len(relay._buffer) == 1
+        assert "hello" in relay._buffer[0]
+
+
+# ---------------------------------------------------------------------------
+# stop_relay
+# ---------------------------------------------------------------------------
+
+
+class TestStopRelay:
+    """Test stop_relay cleanup."""
+
+    def test_noop_when_inactive(self):
+        """Stopping an inactive relay is a safe no-op."""
+        relay = _import_relay()
+        relay.stop_relay()
+        assert relay._RELAY_ACTIVE is False
+
+    def test_flushes_and_joins(self):
+        """Stopping an active relay clears state and joins thread."""
+        relay = _import_relay()
+        relay.init_relay(enabled=True, config={"bot_token": "t", "chat_id": 1})
+        assert relay._RELAY_ACTIVE is True
+        relay.stop_relay()
+        assert relay._RELAY_ACTIVE is False
+        assert relay._thread is None
+
+
+# ---------------------------------------------------------------------------
+# Batching
+# ---------------------------------------------------------------------------
+
+
+class TestBatching:
+    """Test _send_batched 4000-char splitting."""
+
+    def test_single_message_under_limit(self):
+        """Short content sends as one message."""
+        relay = _import_relay()
+        sent = []
+        setattr(relay, "_send_message", lambda text: sent.append(text) or True)
+        relay._send_batched(["short line"])
+        assert len(sent) == 1
+        assert sent[0] == "short line"
+
+    def test_splits_at_4000_chars(self):
+        """Lines exceeding 4000 chars are split across multiple messages."""
+        relay = _import_relay()
+        sent = []
+        setattr(relay, "_send_message", lambda text: sent.append(text) or True)
+        lines = [f"line-{i:04d}-" + "x" * 90 for i in range(50)]
+        relay._send_batched(lines)
+        assert len(sent) > 1
+        for msg in sent:
+            assert len(msg) <= relay.TELEGRAM_MAX_LENGTH + 200
+
+    def test_empty_lines_sends_nothing(self):
+        """Empty list sends no messages."""
+        relay = _import_relay()
+        sent = []
+        setattr(relay, "_send_message", lambda text: sent.append(text) or True)
+        relay._send_batched([])
+        assert len(sent) == 0
+
+
+# ---------------------------------------------------------------------------
+# Flood cap
+# ---------------------------------------------------------------------------
+
+
+class TestFloodCap:
+    """Test flood cap truncation."""
+
+    def test_under_cap_sends_all(self):
+        """Lines under FLOOD_CAP are all delivered."""
+        relay = _import_relay()
+        setattr(relay, "_bot_token", "t")
+        setattr(relay, "_chat_id", 1)
+        sent = []
+        setattr(relay, "_send_batched", lambda lines: sent.extend(lines))
+        relay._buffer.extend([f"line {i}" for i in range(100)])
+        setattr(relay, "_RELAY_ACTIVE", True)
+        relay._flush_buffer()
+        assert len(sent) == 100
+
+    def test_over_cap_truncates_with_notice(self):
+        """Lines over FLOOD_CAP are truncated with a suppression notice."""
+        relay = _import_relay()
+        setattr(relay, "_bot_token", "t")
+        setattr(relay, "_chat_id", 1)
+        sent_lines = []
+        setattr(relay, "_send_batched", lambda lines: sent_lines.extend(lines))
+        relay._buffer.extend([f"line {i}" for i in range(200)])
+        setattr(relay, "_RELAY_ACTIVE", True)
+        relay._flush_buffer()
+        assert len(sent_lines) == relay.FLOOD_CAP + 1
+        assert "50 more suppressed" in sent_lines[-1]
+
+
+# ---------------------------------------------------------------------------
+# _render_event calls relay_event
+# ---------------------------------------------------------------------------
+
+
+class TestRenderEventCallsRelay:
+    """Test that monitor._render_event calls relay_event."""
+
+    def test_render_event_calls_relay(self):
+        """_render_event in monitor.py calls relay_event after console render."""
+        fresh_mocks = {
+            "aipass.prax.apps.handlers.monitoring": MagicMock(),
+            "aipass.prax.apps.handlers.monitoring.event_queue": MagicMock(),
+            "aipass.prax.apps.handlers.monitoring.filesystem_handler": MagicMock(),
+            "aipass.prax.apps.handlers.monitoring.log_watcher": MagicMock(),
+            "aipass.prax.apps.handlers.monitoring.unified_stream": MagicMock(),
+            "aipass.prax.apps.handlers.monitoring.module_tracker": MagicMock(),
+            "aipass.prax.apps.handlers.monitoring.branch_detector": MagicMock(),
+            "aipass.prax.apps.handlers.monitoring.interactive_filter": MagicMock(),
+            "aipass.prax.apps.handlers.monitoring.monitoring_filters": MagicMock(),
+            "aipass.prax.apps.handlers.monitoring.file_watcher_integration": MagicMock(),
+            "aipass.prax.apps.handlers.monitoring.telegram_relay": MagicMock(),
+        }
+        with patch.dict(sys.modules, fresh_mocks):
+            if "aipass.prax.apps.modules.monitor" in sys.modules:
+                mod = importlib.reload(sys.modules["aipass.prax.apps.modules.monitor"])
+            else:
+                mod = importlib.import_module("aipass.prax.apps.modules.monitor")
+
+        event = MagicMock()
+        event.event_type = "log"
+        event.branch = "TEST"
+        event.message = "hello"
+        event.level = "info"
+        event.action = ""
+
+        with patch.object(mod, "_get_pid_for_branch", return_value=None):
+            mod._render_event(event)
+
+        mod.relay_event.assert_called_once_with(event)
+
+
+# ---------------------------------------------------------------------------
+# is_relay_enabled_by_env
+# ---------------------------------------------------------------------------
+
+
+class TestRelayEnabledByEnv:
+    """Test environment variable detection."""
+
+    def test_not_set(self):
+        """Unset env var returns False."""
+        relay = _import_relay()
+        with patch.dict("os.environ", {}, clear=True):
+            assert relay.is_relay_enabled_by_env() is False
+
+    def test_set_to_1(self):
+        """AIPASS_PRAX_MONITOR_RELAY=1 returns True."""
+        relay = _import_relay()
+        with patch.dict("os.environ", {"AIPASS_PRAX_MONITOR_RELAY": "1"}):
+            assert relay.is_relay_enabled_by_env() is True
+
+    def test_set_to_true(self):
+        """AIPASS_PRAX_MONITOR_RELAY=true returns True."""
+        relay = _import_relay()
+        with patch.dict("os.environ", {"AIPASS_PRAX_MONITOR_RELAY": "true"}):
+            assert relay.is_relay_enabled_by_env() is True
+
+    def test_set_to_yes(self):
+        """AIPASS_PRAX_MONITOR_RELAY=yes returns True."""
+        relay = _import_relay()
+        with patch.dict("os.environ", {"AIPASS_PRAX_MONITOR_RELAY": "yes"}):
+            assert relay.is_relay_enabled_by_env() is True
+
+    def test_set_to_0(self):
+        """AIPASS_PRAX_MONITOR_RELAY=0 returns False."""
+        relay = _import_relay()
+        with patch.dict("os.environ", {"AIPASS_PRAX_MONITOR_RELAY": "0"}):
+            assert relay.is_relay_enabled_by_env() is False
diff --git a/src/aipass/seedgo/.seedgo/README.md b/src/aipass/seedgo/.seedgo/README.md
index dd56a69b..db291616 100644
--- a/src/aipass/seedgo/.seedgo/README.md
+++ b/src/aipass/seedgo/.seedgo/README.md
@@ -3,3 +3,26 @@
 Seedgo audit bypass config for `SEEDGO`.
 
 When an audit flags a false positive that doesn't apply to your architecture, add a bypass entry in `bypass.json` with a reason explaining why it's justified.
+
+## Fields
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| `file` | yes | Relative path from branch root |
+| `standard` | yes | Standard name (cli, imports, naming, etc.) |
+| `lines` | no | Specific line numbers to bypass |
+| `functions` | no | Function names for name-scoped bypass (required for `unused_function`) |
+| `reason` | yes | Why this bypass exists |
+
+## Name-scoped bypass (unused_function)
+
+Use `functions` instead of `lines` for `unused_function` bypasses — function names are stable across edits, line numbers drift silently:
+
+```json
+{
+  "file": "apps/handlers/registry.py",
+  "standard": "unused_function",
+  "functions": ["get_skill", "get_skill_names"],
+  "reason": "Public API surface — called by external consumers"
+}
+```
diff --git a/src/aipass/seedgo/apps/handlers/aipass_standards/cli.md b/src/aipass/seedgo/apps/handlers/aipass_standards/cli.md
index c3a570f7..b2c1b07d 100644
--- a/src/aipass/seedgo/apps/handlers/aipass_standards/cli.md
+++ b/src/aipass/seedgo/apps/handlers/aipass_standards/cli.md
@@ -135,7 +135,9 @@ console.print("[cyan]This is the ONLY approved way to output text[/cyan]")
 
 ### Help Output: Manual Rich Formatting
 
-**DO NOT use `parser.print_help()`** - it outputs plain text.
+**DO NOT use `parser.print_help()` or `parser.format_help()`** - both produce plain argparse text.
+
+Wrapping `format_help()` in `console.print()` still renders plain text — it launders argparse output through the approved API without adding Rich formatting.
 
 **Argparse is for PARSING arguments only, NOT for help output.**
 
@@ -161,6 +163,9 @@ def print_help():
 # DON'T DO THIS - outputs plain text
 parser = argparse.ArgumentParser(...)
 parser.print_help()
+
+# DON'T DO THIS EITHER - format_help() returns plain text
+console.print(parser.format_help())
 ```
 
 ---
diff --git a/src/aipass/seedgo/apps/handlers/aipass_standards/cli_check.py b/src/aipass/seedgo/apps/handlers/aipass_standards/cli_check.py
index ff2ab6de..364f3579 100644
--- a/src/aipass/seedgo/apps/handlers/aipass_standards/cli_check.py
+++ b/src/aipass/seedgo/apps/handlers/aipass_standards/cli_check.py
@@ -333,6 +333,7 @@ def check_print_usage(
     # Find print() statements and raw stdout/stderr writes
     print_lines = []
     parser_print_help_lines = []
+    format_help_lines = []
     raw_write_lines = []
 
     # Track if we're inside an if __name__ == '__main__': block
@@ -376,6 +377,15 @@ def check_print_usage(
             else:
                 parser_print_help_lines.append(i)
 
+        # Check for .format_help() - returns plain argparse text
+        if ".format_help()" in stripped:
+            if "#" in line:
+                code_part = line.split("#")[0]
+                if ".format_help()" in code_part:
+                    format_help_lines.append(i)
+            else:
+                format_help_lines.append(i)
+
         # Check for raw sys.stdout.write() / sys.stderr.write() (bypasses Rich)
         if "sys.stdout.write(" in stripped or "sys.stderr.write(" in stripped:
             if "#" in line:
@@ -412,6 +422,16 @@ def check_print_usage(
             ),
         }
 
+    if format_help_lines:
+        return {
+            "name": "print() usage",
+            "passed": False,
+            "message": (
+                f"Found .format_help() in {filename} on lines "
+                f"{format_help_lines[:3]} (returns plain argparse text - write Rich help instead)"
+            ),
+        }
+
     if raw_write_lines:
         return {
             "name": "print() usage",
diff --git a/src/aipass/seedgo/apps/handlers/aipass_standards/cli_content.py b/src/aipass/seedgo/apps/handlers/aipass_standards/cli_content.py
index e356db2b..1ca7c59f 100644
--- a/src/aipass/seedgo/apps/handlers/aipass_standards/cli_content.py
+++ b/src/aipass/seedgo/apps/handlers/aipass_standards/cli_content.py
@@ -35,10 +35,11 @@ def get_cli_standards() -> str:
         "  • Only in test/temp code",
         "  • Remove before commit",
         "",
-        "[red]✗ Never use:[/red] parser.print_help()",
-        "  • Outputs plain text (violates standard)",
+        "[red]✗ Never use:[/red] parser.print_help() or parser.format_help()",
+        "  • Both produce plain argparse text (violates standard)",
+        "  • console.print(parser.format_help()) still renders plain text",
         "  • Argparse is for PARSING only, not help output",
-        "  • Write custom print_help() with console.print()",
+        "  • Write custom print_help() with console.print() and Rich markup",
         "",
         "─" * 70,
         "",
@@ -84,7 +85,8 @@ def get_cli_standards() -> str:
         "[bold cyan]RICH FORMATTING QUICK REFERENCE:[/bold cyan]",
         "",
         "[bold]Colors:[/bold]",
-        "  [red]red[/red], [green]green[/green], [yellow]yellow[/yellow], [blue]blue[/blue], [cyan]cyan[/cyan], [magenta]magenta[/magenta]",
+        "  [red]red[/red], [green]green[/green], [yellow]yellow[/yellow],"
+        " [blue]blue[/blue], [cyan]cyan[/cyan], [magenta]magenta[/magenta]",
         "",
         "[bold]Styles:[/bold]",
         "  [bold]bold[/bold], [italic]italic[/italic], [dim]dim[/dim], [underline]underline[/underline]",
diff --git a/src/aipass/seedgo/apps/handlers/aipass_standards/readme_check.py b/src/aipass/seedgo/apps/handlers/aipass_standards/readme_check.py
index bdf23912..f691dc28 100644
--- a/src/aipass/seedgo/apps/handlers/aipass_standards/readme_check.py
+++ b/src/aipass/seedgo/apps/handlers/aipass_standards/readme_check.py
@@ -30,6 +30,7 @@ from typing import Dict, List, Optional
 from aipass.prax import logger
 from aipass.seedgo.apps.handlers.json import json_handler
 from aipass.seedgo.apps.handlers.bypass.utils import is_bypassed
+from aipass.seedgo.apps.handlers.aipass_standards.skip_dirs import SOURCE_SKIP_DIRS, is_disabled_file
 
 # Audit scope: entry points only (apps/{name}.py)
 AUDIT_SCOPE = "entry_point"
@@ -395,6 +396,8 @@ def check_module_list(lines: List[str], branch_root: Path, file_path: str, bypas
     for py_file in sorted(modules_dir.glob("*.py")):
         if py_file.name == "__init__.py":
             continue
+        if is_disabled_file(py_file.name):
+            continue
         module_files.append(py_file.stem)
 
     if not module_files:
@@ -502,6 +505,10 @@ def _count_test_functions(tests_dir: Path) -> int:
     count = 0
     test_func_pattern = re.compile(r"^\s*def\s+test_", re.MULTILINE)
     for test_file in tests_dir.rglob("test_*.py"):
+        if any(part in SOURCE_SKIP_DIRS for part in test_file.relative_to(tests_dir).parts):
+            continue
+        if is_disabled_file(test_file.name):
+            continue
         try:
             source = test_file.read_text(encoding="utf-8")
             count += len(test_func_pattern.findall(source))
diff --git a/src/aipass/seedgo/apps/handlers/aipass_standards/template.md b/src/aipass/seedgo/apps/handlers/aipass_standards/template.md
new file mode 100644
index 00000000..b8ae31af
--- /dev/null
+++ b/src/aipass/seedgo/apps/handlers/aipass_standards/template.md
@@ -0,0 +1,43 @@
+# Template Standard
+
+Detects files still in un-configured template form after spawn scaffolding.
+
+## Severity
+
+**Advisory (WARNING)** — never fails the audit or blocks commits. Surfaces loudly so branch owners notice.
+
+## Target Files
+
+- `.aipass/aipass_local_prompt.md` — branch prompt
+- `README.md` — branch documentation
+- `.trinity/*.json` — identity files (passport, local, observations)
+
+## Detection Markers
+
+### Definitive (all file types)
+
+- `NEEDS CONFIGURATION`
+- `{{BRANCHNAME}}` / `{{BRANCH}}` — unfilled mustache placeholders from spawn
+- `INSTRUCTIONS FOR FILLING OUT THIS TEMPLATE`
+- `WHEN YOU'RE DONE`
+
+### Markdown-only (.md files)
+
+- Single-curly placeholders: `{role description}`, `{command1}`, etc.
+- Double-curly `{{...}}` are handled by the definitive check above
+
+## How to Fix
+
+Open the flagged file and replace template markers with real content. The spawn template shows which sections need filling.
+
+## Bypass
+
+Add to `.seedgo/bypass.json`:
+
+```json
+{"file": "<path-substring>", "standard": "template", "reason": "intentionally left as template"}
+```
+
+## Scope
+
+`AUDIT_SCOPE = branch_level` — runs once per branch via `check_branch()`.
diff --git a/src/aipass/seedgo/apps/handlers/aipass_standards/template_check.py b/src/aipass/seedgo/apps/handlers/aipass_standards/template_check.py
new file mode 100644
index 00000000..a2c495f2
--- /dev/null
+++ b/src/aipass/seedgo/apps/handlers/aipass_standards/template_check.py
@@ -0,0 +1,170 @@
+# =================== AIPass ====================
+# Name: template_check.py
+# Description: Template/Boilerplate Detection Checker Handler
+# Version: 1.0.0
+# Created: 2026-07-01
+# Modified: 2026-07-01
+# =============================================
+
+"""
+Template/Boilerplate Detection Checker Handler
+
+Detects files still left in un-configured template form and flags them
+as advisory warnings. Never blocks the audit — surfaces loudly so
+branches know they have unconfigured stub files.
+
+Checks:
+1. .aipass/aipass_local_prompt.md for template markers
+2. README.md for template markers
+3. .trinity/*.json for template markers (definitive only — no curly brace regex)
+
+AUDIT_SCOPE: branch_level — runs once per branch via check_branch().
+ADVISORY: always passes so it never blocks commits or audits.
+"""
+
+import re
+from pathlib import Path
+from typing import Dict
+
+from aipass.prax import logger
+from aipass.seedgo.apps.handlers.json import json_handler
+from aipass.seedgo.apps.handlers.bypass.utils import is_bypassed
+
+AUDIT_SCOPE = "branch_level"
+ADVISORY = True
+
+_DEFINITIVE_MARKERS = [
+    "NEEDS CONFIGURATION",
+    "{{BRANCHNAME}}",
+    "{{BRANCH}}",
+    "INSTRUCTIONS FOR FILLING OUT THIS TEMPLATE",
+    "WHEN YOU'RE DONE",
+]
+
+_SINGLE_CURLY_RE = re.compile(r"\{[^{}\n]+\}")
+_DOUBLE_CURLY_RE = re.compile(r"\{\{[^}]*\}\}")
+
+
+def _find_markers(content: str, is_markdown: bool) -> list[str]:
+    """Return list of matched template marker descriptions."""
+    found: list[str] = []
+    content_upper = content.upper()
+
+    for marker in _DEFINITIVE_MARKERS:
+        if marker.upper() in content_upper:
+            found.append(marker)
+
+    if is_markdown:
+        stripped = _DOUBLE_CURLY_RE.sub("", content)
+        curly_matches = _SINGLE_CURLY_RE.findall(stripped)
+        if curly_matches:
+            examples = curly_matches[:3]
+            suffix = f" (+{len(curly_matches) - 3} more)" if len(curly_matches) > 3 else ""
+            found.append(f"single-curly placeholders: {', '.join(examples)}{suffix}")
+
+    return found
+
+
+def _check_file(file_path: Path, bypass_rules: list | None) -> Dict:
+    """Check a single target file for template markers."""
+    rel = file_path.name
+    if not file_path.exists():
+        return {"name": rel, "passed": True, "message": f"{rel} not found (skipped)"}
+
+    if is_bypassed(str(file_path), "template", bypass_rules=bypass_rules):
+        return {"name": rel, "passed": True, "message": f"{rel} bypassed via .seedgo/bypass.json"}
+
+    try:
+        content = file_path.read_text(encoding="utf-8")
+    except OSError:
+        logger.info("Cannot read %s for template check", file_path)
+        return {"name": rel, "passed": True, "message": f"{rel} unreadable (skipped)"}
+
+    is_md = file_path.suffix == ".md"
+    markers = _find_markers(content, is_md)
+
+    if not markers:
+        return {"name": rel, "passed": True, "message": "no template markers"}
+
+    marker_list = ", ".join(markers)
+    return {
+        "name": rel,
+        "passed": False,
+        "message": (
+            f"⚠ still in template form — {file_path.name} contains"
+            f" un-configured template markers ({marker_list})."
+            f" Please configure it (see the spawn template for the sections"
+            f" to fill), or add a template bypass in .seedgo/bypass.json"
+            f" if intentional."
+        ),
+    }
+
+
+def check_branch(branch_path: str, bypass_rules: list | None = None) -> Dict:
+    """Check branch for un-configured template/boilerplate files.
+
+    Args:
+        branch_path: Path to branch root (e.g., src/aipass/cli)
+        bypass_rules: Standard bypass rules from .seedgo/bypass.json
+
+    Returns:
+        dict with passed=True (advisory), checks list, score, standard, advisory flag
+    """
+    bp = Path(branch_path)
+
+    if is_bypassed(branch_path, "template", bypass_rules=bypass_rules):
+        json_handler.log_operation(
+            "check_completed",
+            {"branch": branch_path, "score": 100, "standard": "template"},
+        )
+        return {
+            "passed": True,
+            "checks": [
+                {
+                    "name": "Template check",
+                    "passed": True,
+                    "message": "Standard bypassed via .seedgo/bypass.json",
+                }
+            ],
+            "score": 100,
+            "standard": "TEMPLATE",
+            "advisory": True,
+        }
+
+    checks: list[Dict] = []
+
+    targets: list[Path] = [
+        bp / ".aipass" / "aipass_local_prompt.md",
+        bp / "README.md",
+    ]
+    for trinity_file in sorted((bp / ".trinity").glob("*.json")) if (bp / ".trinity").is_dir() else []:
+        targets.append(trinity_file)
+
+    for target in targets:
+        checks.append(_check_file(target, bypass_rules))
+
+    if not checks:
+        checks.append({"name": "Template check", "passed": True, "message": "No target files found (skipped)"})
+
+    failed_count = sum(1 for c in checks if not c["passed"])
+    total = len(checks)
+    score = int(((total - failed_count) / total) * 100) if total > 0 else 100
+
+    json_handler.log_operation(
+        "check_completed",
+        {
+            "branch": branch_path,
+            "score": score,
+            "standard": "template",
+            "warnings": failed_count,
+            "advisory": True,
+        },
+    )
+
+    return {
+        "passed": True,
+        "checks": checks,
+        "score": score,
+        "standard": "TEMPLATE",
+        "advisory": True,
+    }
diff --git a/src/aipass/seedgo/apps/handlers/aipass_standards/template_content.py b/src/aipass/seedgo/apps/handlers/aipass_standards/template_content.py
new file mode 100644
index 00000000..062f35d9
--- /dev/null
+++ b/src/aipass/seedgo/apps/handlers/aipass_standards/template_content.py
@@ -0,0 +1,77 @@
+# =================== AIPass ====================
+# Name: template_content.py
+# Description: Template Standards Content Handler
+# Version: 1.0.0
+# Created: 2026-07-01
+# Modified: 2026-07-01
+# =============================================
+
+"""
+Template Standards Content Handler
+
+Provides formatted template standards content.
+Module orchestrates, handler implements.
+"""
+
+from aipass.seedgo.apps.handlers.json import json_handler
+
+
+def get_template_standards() -> str:
+    """Return formatted template standards content with Rich markup.
+
+    Returns:
+        str: Formatted standards text with Rich styling
+    """
+    lines = [
+        "[bold cyan]CORE PRINCIPLE:[/bold cyan]",
+        "  Branches should not run with un-configured template files.",
+        "  Spawn creates scaffolding from templates — but those templates",
+        "  must be filled in by the branch owner. Un-configured stubs are",
+        "  a silent failure: the branch runs fine but gets wrong prompts,",
+        "  generic READMEs, or placeholder identity.",
+        "",
+        "[bold cyan]WHAT IT CHECKS:[/bold cyan]",
+        "  Scans key branch files for template markers that indicate the",
+        "  file was never configured after spawn:",
+        "",
+        "  [yellow]Target files:[/yellow]",
+        "  - [dim].aipass/aipass_local_prompt.md[/dim] — branch prompt",
+        "  - [dim]README.md[/dim] — branch documentation",
+        "  - [dim].trinity/*.json[/dim] — identity files",
+        "",
+        "  [yellow]Definitive markers (all file types):[/yellow]",
+        "  - [red]NEEDS CONFIGURATION[/red]",
+        "  - [red]{{BRANCHNAME}}[/red] / [red]{{BRANCH}}[/red]",
+        "  - [red]INSTRUCTIONS FOR FILLING OUT THIS TEMPLATE[/red]",
+        "  - [red]WHEN YOU'RE DONE[/red]",
+        "",
+        "  [yellow]Markdown-only markers (.md files):[/yellow]",
+        "  - Single-curly placeholders: [dim]{role}[/dim], [dim]{command1}[/dim]",
+        "",
+        "[bold cyan]SEVERITY:[/bold cyan]",
+        "  [yellow]Advisory (WARNING)[/yellow] — never fails the audit.",
+        "",
+        "[bold cyan]HOW TO FIX:[/bold cyan]",
+        "  Open the flagged file and replace template markers with real",
+        "  content. The spawn template shows which sections need filling.",
+        "",
+        "  Intentional exception? Add a bypass in [dim].seedgo/bypass.json[/dim]:",
+        '  [dim]{"file":"<path>","standard":"template","reason":"..."}[/dim]',
+        "",
+        "[yellow]SCOPE:[/yellow]",
+        "  AUDIT_SCOPE = [bold]branch_level[/bold]",
+        "",
+        "[bold cyan]SCORING:[/bold cyan]",
+        "  One check per target file. Score dips per flagged file.",
+        "  Audit still [green]passes[/green] regardless (advisory).",
+        "",
+        "[bold cyan]BYPASS:[/bold cyan]",
+        "  Via [dim].seedgo/bypass.json[/dim] — standard + file-level",
+        "",
+        "[bold cyan]REFERENCE:[/bold cyan]",
+        "  [dim]See: seedgo standards pack (template)[/dim]",
+        "  [dim]Checker: template_check.py[/dim]",
+    ]
+
+    json_handler.log_operation("standard_content_queried", {"standard": "template"})
+    return "\n".join(lines)
diff --git a/src/aipass/seedgo/apps/handlers/aipass_standards/test_quality_check.py b/src/aipass/seedgo/apps/handlers/aipass_standards/test_quality_check.py
index 2735b4ba..c627cde0 100644
--- a/src/aipass/seedgo/apps/handlers/aipass_standards/test_quality_check.py
+++ b/src/aipass/seedgo/apps/handlers/aipass_standards/test_quality_check.py
@@ -195,7 +195,7 @@ def _find_test_files_broad(branch_path: Path) -> list[Path]:
         for py_file in sorted(tests_dir.rglob("*.py")):
             if py_file.name in ("__init__.py", "conftest.py"):
                 continue
-            if "__pycache__" in py_file.parts:
+            if any(_should_skip_dir(part) for part in py_file.relative_to(tests_dir).parts):
                 continue
             resolved = py_file.resolve()
             if resolved not in seen:
diff --git a/src/aipass/seedgo/apps/handlers/aipass_standards/unused_function_check.py b/src/aipass/seedgo/apps/handlers/aipass_standards/unused_function_check.py
index 1f12df36..b866c6e6 100644
--- a/src/aipass/seedgo/apps/handlers/aipass_standards/unused_function_check.py
+++ b/src/aipass/seedgo/apps/handlers/aipass_standards/unused_function_check.py
@@ -277,8 +277,7 @@ def check_branch(branch_path: str, bypass_rules: list | None = None) -> dict:
     unused_functions: list[dict] = []
 
     for func_name, lineno, py_file in all_functions:
-        # Check bypass at file+line level
-        if is_bypassed(str(py_file), "unused_function", lineno, bypass_rules):
+        if is_bypassed(str(py_file), "unused_function", lineno, bypass_rules, name=func_name):
             continue
 
         total_refs = _count_references_in_corpus(func_name, corpus)
diff --git a/src/aipass/seedgo/apps/handlers/audit/branch_audit.py b/src/aipass/seedgo/apps/handlers/audit/branch_audit.py
index 2d192953..562580ac 100644
--- a/src/aipass/seedgo/apps/handlers/audit/branch_audit.py
+++ b/src/aipass/seedgo/apps/handlers/audit/branch_audit.py
@@ -187,7 +187,9 @@ def audit_branch(branch: Dict[str, str], bypass_rules: list, pack_path: Path | N
                 logger.info("Post-check %s failed for branch %s", name, branch["name"])
 
     json_handler.log_operation("branch_audit_completed", {"branch": branch["name"], "checkers": len(checkers)})
-    avg = int(sum(scores.values()) / len(scores)) if scores else 0
+    advisory_standards = [name for name, mod in checkers.items() if getattr(mod, "ADVISORY", False) is True]
+    gating_scores = {k: v for k, v in scores.items() if k not in advisory_standards}
+    avg = int(sum(gating_scores.values()) / len(gating_scores)) if gating_scores else 0
 
     # Deprecated DOCUMENTS/ directory check
     deprecated = []
@@ -214,6 +216,7 @@ def audit_branch(branch: Dict[str, str], bypass_rules: list, pack_path: Path | N
         "branch": branch,
         "results": results,
         "scores": scores,
+        "advisory_standards": advisory_standards,
         "average": avg,
         "deprecated_patterns": deprecated,
         "files_checked": len(all_files),
diff --git a/src/aipass/seedgo/apps/handlers/bypass/bypass_handler.py b/src/aipass/seedgo/apps/handlers/bypass/bypass_handler.py
index 98d7bc82..4c62c7ea 100644
--- a/src/aipass/seedgo/apps/handlers/bypass/bypass_handler.py
+++ b/src/aipass/seedgo/apps/handlers/bypass/bypass_handler.py
@@ -37,14 +37,13 @@ BYPASS_TEMPLATE = {
             "file": "apps/modules/logger.py",
             "standard": "cli",
             "lines": [146, 177],
-            "pattern": "if __name__ == '__main__'",
             "reason": "Circular dependency - logger cannot import CLI",
         },
         "fields": {
             "file": "Relative path from branch root (required)",
             "standard": "Standard name: cli, imports, naming, etc. (required)",
             "lines": "Optional - specific line numbers to bypass",
-            "pattern": "Optional - pattern to match (e.g. 'if __name__')",
+            "functions": "Optional - list of function names for name-scoped bypass (required for unused_function)",
             "reason": "Required - why this bypass exists",
         },
     },
diff --git a/src/aipass/seedgo/apps/handlers/bypass/utils.py b/src/aipass/seedgo/apps/handlers/bypass/utils.py
index 8fe216ca..a1c7633f 100644
--- a/src/aipass/seedgo/apps/handlers/bypass/utils.py
+++ b/src/aipass/seedgo/apps/handlers/bypass/utils.py
@@ -18,6 +18,7 @@ def is_bypassed(
     standard: str,
     line: int | None = None,
     bypass_rules: list | None = None,
+    name: str | None = None,
 ) -> bool:
     """Check if a violation should be bypassed.
 
@@ -26,6 +27,7 @@ def is_bypassed(
         standard: Standard name (e.g., 'cli', 'imports')
         line: Optional specific line number of the violation
         bypass_rules: List of bypass rules from .seedgo/bypass.json
+        name: Optional function/symbol name for name-scoped bypasses
 
     Returns:
         True if this violation should be bypassed
@@ -40,15 +42,20 @@ def is_bypassed(
         rule_file = rule.get("file", "")
         if rule_file and rule_file not in file_path_posix:
             continue
-        rule_lines = rule.get("lines", [])
-        if rule_lines and line is not None and line not in rule_lines:
-            continue
+        functions = rule.get("functions")
+        if functions and name is not None:
+            if name not in functions:
+                continue
+        elif rule.get("lines") and line is not None:
+            if line not in rule["lines"]:
+                continue
         json_handler.log_operation(
             "bypass_matched",
             {
                 "file": file_path,
                 "standard": standard,
                 "line": line,
+                "name": name,
                 "rule_file": rule_file,
             },
         )
diff --git a/src/aipass/seedgo/tests/fixtures/provider_hooks_snapshot.json b/src/aipass/seedgo/tests/fixtures/provider_hooks_snapshot.json
index fb62f90f..f46db711 100644
--- a/src/aipass/seedgo/tests/fixtures/provider_hooks_snapshot.json
+++ b/src/aipass/seedgo/tests/fixtures/provider_hooks_snapshot.json
@@ -1,5 +1,13 @@
 {
   "UserPromptSubmit": [
+    {
+      "hooks": [
+        {
+          "type": "command",
+          "command": "$AIPASS_HOME/.venv/bin/python3 $AIPASS_HOME/src/aipass/hooks/apps/handlers/bridges/claude.py UserPromptSubmit:presence_gate"
+        }
+      ]
+    },
     {
       "hooks": [
         {
diff --git a/src/aipass/seedgo/tests/test_bypass.py b/src/aipass/seedgo/tests/test_bypass.py
index 1f39c7fa..464104fc 100644
--- a/src/aipass/seedgo/tests/test_bypass.py
+++ b/src/aipass/seedgo/tests/test_bypass.py
@@ -44,6 +44,7 @@ def _mock_infrastructure(monkeypatch):
     for mod_name in [
         "aipass.seedgo.apps.handlers.bypass.bypass_handler",
         "aipass.seedgo.apps.handlers.bypass.ignore_handler",
+        "aipass.seedgo.apps.handlers.bypass.utils",
     ]:
         monkeypatch.delitem(sys.modules, mod_name, raising=False)
 
@@ -210,3 +211,214 @@ def test_get_deprecated_patterns_returns_dict():
     for key, value in patterns.items():
         assert isinstance(key, str)
         assert isinstance(value, str)
+
+
+# ---------------------------------------------------------------------------
+# Tests -- utils.is_bypassed name-scoped bypass
+# ---------------------------------------------------------------------------
+
+
+def test_utils_name_match_suppresses_regardless_of_line():
+    """Name-scoped bypass matches by function name, ignoring line number."""
+    from aipass.seedgo.apps.handlers.bypass.utils import is_bypassed
+
+    rules = [
+        {
+            "file": "apps/ops.py",
+            "standard": "unused_function",
+            "functions": ["update_command"],
+            "reason": "public API",
+        }
+    ]
+    assert (
+        is_bypassed(
+            "/branch/apps/ops.py",
+            "unused_function",
+            line=999,
+            bypass_rules=rules,
+            name="update_command",
+        )
+        is True
+    )
+
+
+def test_utils_name_not_in_functions_list():
+    """Name-scoped bypass rejects function not in the functions list."""
+    from aipass.seedgo.apps.handlers.bypass.utils import is_bypassed
+
+    rules = [
+        {
+            "file": "apps/ops.py",
+            "standard": "unused_function",
+            "functions": ["update_command"],
+            "reason": "public API",
+        }
+    ]
+    assert (
+        is_bypassed(
+            "/branch/apps/ops.py",
+            "unused_function",
+            line=232,
+            bypass_rules=rules,
+            name="delete_command",
+        )
+        is False
+    )
+
+
+def test_utils_line_drift_no_longer_breaks_name_scoped():
+    """Line drift doesn't affect name-scoped bypass — name is stable."""
+    from aipass.seedgo.apps.handlers.bypass.utils import is_bypassed
+
+    rules = [
+        {
+            "file": "apps/ops.py",
+            "standard": "unused_function",
+            "functions": ["get_skill", "get_skill_names"],
+            "reason": "public API",
+        }
+    ]
+    assert (
+        is_bypassed(
+            "/branch/apps/ops.py",
+            "unused_function",
+            line=52,
+            bypass_rules=rules,
+            name="get_skill",
+        )
+        is True
+    )
+    assert (
+        is_bypassed(
+            "/branch/apps/ops.py",
+            "unused_function",
+            line=9999,
+            bypass_rules=rules,
+            name="get_skill",
+        )
+        is True
+    )
+
+
+def test_utils_functions_present_name_none_falls_back_to_lines():
+    """When functions is set but name=None (other checker), fall back to line matching."""
+    from aipass.seedgo.apps.handlers.bypass.utils import is_bypassed
+
+    rules = [
+        {
+            "file": "apps/ops.py",
+            "standard": "unused_function",
+            "functions": ["update_command"],
+            "lines": [10],
+            "reason": "test",
+        }
+    ]
+    assert (
+        is_bypassed(
+            "/branch/apps/ops.py",
+            "unused_function",
+            line=10,
+            bypass_rules=rules,
+            name=None,
+        )
+        is True
+    )
+
+
+def test_utils_existing_lines_only_rules_still_work():
+    """Existing line-only rules (no functions field) still match by line."""
+    from aipass.seedgo.apps.handlers.bypass.utils import is_bypassed
+
+    rules = [
+        {
+            "file": "apps/foo.py",
+            "standard": "cli",
+            "lines": [10, 20],
+            "reason": "circular",
+        }
+    ]
+    assert (
+        is_bypassed(
+            "/branch/apps/foo.py",
+            "cli",
+            line=10,
+            bypass_rules=rules,
+        )
+        is True
+    )
+    assert (
+        is_bypassed(
+            "/branch/apps/foo.py",
+            "cli",
+            line=99,
+            bypass_rules=rules,
+        )
+        is False
+    )
+
+
+def test_utils_file_only_bypass_still_matches():
+    """File-level bypass (no lines, no functions) still works."""
+    from aipass.seedgo.apps.handlers.bypass.utils import is_bypassed
+
+    rules = [
+        {
+            "file": "apps/foo.py",
+            "standard": "unused_function",
+            "reason": "whole file bypassed",
+        }
+    ]
+    assert (
+        is_bypassed(
+            "/branch/apps/foo.py",
+            "unused_function",
+            line=50,
+            bypass_rules=rules,
+            name="anything",
+        )
+        is True
+    )
+
+
+def test_utils_multiple_functions_in_one_rule():
+    """A single rule can list multiple function names."""
+    from aipass.seedgo.apps.handlers.bypass.utils import is_bypassed
+
+    rules = [
+        {
+            "file": "apps/registry.py",
+            "standard": "unused_function",
+            "functions": ["get_skill", "get_skill_names"],
+            "reason": "public API",
+        }
+    ]
+    assert (
+        is_bypassed(
+            "/branch/apps/registry.py",
+            "unused_function",
+            line=1,
+            bypass_rules=rules,
+            name="get_skill",
+        )
+        is True
+    )
+    assert (
+        is_bypassed(
+            "/branch/apps/registry.py",
+            "unused_function",
+            line=1,
+            bypass_rules=rules,
+            name="get_skill_names",
+        )
+        is True
+    )
+    assert (
+        is_bypassed(
+            "/branch/apps/registry.py",
+            "unused_function",
+            line=1,
+            bypass_rules=rules,
+            name="other_func",
+        )
+        is False
+    )
diff --git a/src/aipass/seedgo/tests/test_checkers_batch6.py b/src/aipass/seedgo/tests/test_checkers_batch6.py
index 11d35485..f603329f 100644
--- a/src/aipass/seedgo/tests/test_checkers_batch6.py
+++ b/src/aipass/seedgo/tests/test_checkers_batch6.py
@@ -50,17 +50,27 @@ def _mock_infrastructure(monkeypatch):
         json_mod,
     )
 
-    # -- bypass handler (used by architecture_check) ------------------------
+    # -- bypass handler (used by architecture_check + cli_check) -------------
     bypass_pkg = MagicMock()
     bypass_ignore = MagicMock()
     bypass_ignore.get_template_ignore_patterns = MagicMock(return_value=[])
     bypass_pkg.ignore_handler = bypass_ignore
+    from aipass.seedgo.apps.handlers.bypass.utils import is_bypassed as _real_is_bypassed
+
+    bypass_utils = MagicMock()
+    bypass_utils.is_bypassed = _real_is_bypassed
+    bypass_pkg.utils = bypass_utils
     monkeypatch.setitem(sys.modules, "aipass.seedgo.apps.handlers.bypass", bypass_pkg)
     monkeypatch.setitem(
         sys.modules,
         "aipass.seedgo.apps.handlers.bypass.ignore_handler",
         bypass_ignore,
     )
+    monkeypatch.setitem(
+        sys.modules,
+        "aipass.seedgo.apps.handlers.bypass.utils",
+        bypass_utils,
+    )
 
     # Force re-imports so checkers pick up fresh mocks
     for mod_name in [
@@ -545,6 +555,30 @@ class TestCheckPrintUsage:
         assert result["passed"] is False
         assert "parser.print_help()" in result["message"]
 
+    def test_format_help_fails(self):
+        """console.print(parser.format_help()) fails — plain argparse text."""
+        from aipass.seedgo.apps.handlers.aipass_standards.cli_check import (
+            check_print_usage,
+        )
+
+        content = "console.print(parser.format_help())\n"
+        lines = _lines(content)
+        result = check_print_usage(content, lines, "/module.py")
+        assert result is not None
+        assert result["passed"] is False
+        assert ".format_help()" in result["message"]
+
+    def test_format_help_in_comment_ignored(self):
+        """.format_help() inside a comment is not flagged."""
+        from aipass.seedgo.apps.handlers.aipass_standards.cli_check import (
+            check_print_usage,
+        )
+
+        content = "# parser.format_help() should not be used\n"
+        lines = _lines(content)
+        result = check_print_usage(content, lines, "/module.py")
+        assert result is None
+
     def test_sys_stdout_write_fails(self):
         """sys.stdout.write() usage fails."""
         from aipass.seedgo.apps.handlers.aipass_standards.cli_check import (
diff --git a/src/aipass/seedgo/tests/test_readme_content_checks.py b/src/aipass/seedgo/tests/test_readme_content_checks.py
index ec2f55f3..c43b5ff4 100644
--- a/src/aipass/seedgo/tests/test_readme_content_checks.py
+++ b/src/aipass/seedgo/tests/test_readme_content_checks.py
@@ -498,6 +498,41 @@ def test_is_runtime_artifact_known_dirs():
     assert _is_runtime_artifact(Path("/any/path/tests")) is False
 
 
+def test_module_list_skips_disabled_file(tmp_path):
+    """A (disabled) .py in apps/modules/ must not trigger a 'missing module' violation."""
+    from aipass.seedgo.apps.handlers.aipass_standards.readme_check import (
+        check_module_list,
+    )
+
+    modules_dir = tmp_path / "apps" / "modules"
+    modules_dir.mkdir(parents=True)
+    (modules_dir / "__init__.py").write_text("", encoding="utf-8")
+    (modules_dir / "real_module.py").write_text("# real\n", encoding="utf-8")
+    (modules_dir / "old_module(disabled).py").write_text("# disabled\n", encoding="utf-8")
+
+    readme_lines = _lines("# Branch\n\nreal_module is mentioned here.\n")
+    result = check_module_list(readme_lines, tmp_path, "fake.py")
+    assert result["passed"] is True
+    assert "old_module" not in result["message"]
+
+
+def test_count_test_functions_skips_disabled_file(tmp_path):
+    """_count_test_functions must exclude test_*(disabled).py files."""
+    from aipass.seedgo.apps.handlers.aipass_standards.readme_check import (
+        _count_test_functions,
+    )
+
+    tests_dir = tmp_path / "tests"
+    tests_dir.mkdir()
+    (tests_dir / "test_active.py").write_text("def test_one(): pass\ndef test_two(): pass\n", encoding="utf-8")
+    (tests_dir / "test_old(disabled).py").write_text(
+        "def test_ghost(): pass\ndef test_phantom(): pass\ndef test_zombie(): pass\n",
+        encoding="utf-8",
+    )
+
+    assert _count_test_functions(tests_dir) == 2
+
+
 def test_directory_tree_passes_absent_runtime_dir(tmp_path):
     """Parity regression: README tree lists runtime dir (logs), dir absent on
     disk, no git available — tree check passes via _is_runtime_artifact."""
diff --git a/src/aipass/seedgo/tests/test_template_check.py b/src/aipass/seedgo/tests/test_template_check.py
new file mode 100644
index 00000000..60fe5a27
--- /dev/null
+++ b/src/aipass/seedgo/tests/test_template_check.py
@@ -0,0 +1,309 @@
+"""Tests for template_check — template/boilerplate detection checker."""
+
+# =================== META ====================
+# Name: test_template_check.py
+# Description: Unit tests for template_check
+# Version: 1.0.0
+# Created: 2026-07-01
+# Modified: 2026-07-01
+# =============================================
+
+import json
+
+import pytest
+from unittest.mock import MagicMock
+
+
+# ---------------------------------------------------------------------------
+# Fixtures
+# ---------------------------------------------------------------------------
+
+
+@pytest.fixture(autouse=True)
+def _mock_infrastructure(monkeypatch):
+    """Mock heavy infrastructure imports for standards checkers."""
+    import sys
+
+    mock_logger = MagicMock()
+    mock_json_handler = MagicMock()
+    mock_json_handler.log_operation = MagicMock(return_value=True)
+
+    prax_mod = MagicMock()
+    prax_mod.logger = mock_logger
+    monkeypatch.setitem(sys.modules, "aipass.prax", prax_mod)
+
+    json_pkg = MagicMock()
+    json_pkg.json_handler = mock_json_handler
+    monkeypatch.setitem(sys.modules, "aipass.seedgo.apps.handlers.json", json_pkg)
+    json_mod = MagicMock()
+    json_mod.log_operation = mock_json_handler.log_operation
+    monkeypatch.setitem(
+        sys.modules,
+        "aipass.seedgo.apps.handlers.json.json_handler",
+        json_mod,
+    )
+
+    from aipass.seedgo.apps.handlers.bypass.utils import (
+        is_bypassed as real_is_bypassed,
+    )
+
+    bypass_pkg = MagicMock()
+    bypass_utils = MagicMock()
+    bypass_utils.is_bypassed = real_is_bypassed
+    bypass_pkg.utils = bypass_utils
+    bypass_ignore = MagicMock()
+    bypass_ignore.get_template_ignore_patterns = MagicMock(return_value=[])
+    bypass_pkg.ignore_handler = bypass_ignore
+    monkeypatch.setitem(sys.modules, "aipass.seedgo.apps.handlers.bypass", bypass_pkg)
+    monkeypatch.setitem(sys.modules, "aipass.seedgo.apps.handlers.bypass.utils", bypass_utils)
+    monkeypatch.setitem(
+        sys.modules,
+        "aipass.seedgo.apps.handlers.bypass.ignore_handler",
+        bypass_ignore,
+    )
+
+    for mod_name in [
+        "aipass.seedgo.apps.handlers.aipass_standards.template_check",
+    ]:
+        monkeypatch.delitem(sys.modules, mod_name, raising=False)
+
+
+# ===========================================================================
+# 1. _find_markers — core detection logic
+# ===========================================================================
+
+
+class TestFindMarkers:
+    """Tests for the _find_markers helper."""
+
+    def test_needs_configuration_detected(self):
+        from aipass.seedgo.apps.handlers.aipass_standards.template_check import (
+            _find_markers,
+        )
+
+        markers = _find_markers("This file NEEDS CONFIGURATION.", False)
+        assert any("NEEDS CONFIGURATION" in m for m in markers)
+
+    def test_mustache_branchname_detected(self):
+        from aipass.seedgo.apps.handlers.aipass_standards.template_check import (
+            _find_markers,
+        )
+
+        markers = _find_markers("Welcome to {{BRANCHNAME}}.", False)
+        assert any("{{BRANCHNAME}}" in m for m in markers)
+
+    def test_mustache_branch_detected(self):
+        from aipass.seedgo.apps.handlers.aipass_standards.template_check import (
+            _find_markers,
+        )
+
+        markers = _find_markers("Branch: {{BRANCH}}", False)
+        assert any("{{BRANCH}}" in m for m in markers)
+
+    def test_instructions_marker_detected(self):
+        from aipass.seedgo.apps.handlers.aipass_standards.template_check import (
+            _find_markers,
+        )
+
+        markers = _find_markers("INSTRUCTIONS FOR FILLING OUT THIS TEMPLATE", False)
+        assert len(markers) >= 1
+
+    def test_when_youre_done_detected(self):
+        from aipass.seedgo.apps.handlers.aipass_standards.template_check import (
+            _find_markers,
+        )
+
+        markers = _find_markers("WHEN YOU'RE DONE, delete this section", False)
+        assert any("WHEN YOU'RE DONE" in m for m in markers)
+
+    def test_single_curly_detected_in_markdown(self):
+        from aipass.seedgo.apps.handlers.aipass_standards.template_check import (
+            _find_markers,
+        )
+
+        markers = _find_markers(
+            "Role: {one-line role description}\nDo: {Primary responsibility}",
+            True,
+        )
+        assert any("single-curly" in m for m in markers)
+
+    def test_single_curly_not_detected_in_json(self):
+        from aipass.seedgo.apps.handlers.aipass_standards.template_check import (
+            _find_markers,
+        )
+
+        markers = _find_markers('{"key": "value", "nested": {"a": 1}}', False)
+        assert not any("single-curly" in m for m in markers)
+
+    def test_double_curly_not_double_counted_as_single(self):
+        from aipass.seedgo.apps.handlers.aipass_standards.template_check import (
+            _find_markers,
+        )
+
+        content = "Hello {{BRANCH}}, welcome."
+        markers = _find_markers(content, True)
+        assert not any("single-curly" in m for m in markers)
+
+    def test_clean_content_no_markers(self):
+        from aipass.seedgo.apps.handlers.aipass_standards.template_check import (
+            _find_markers,
+        )
+
+        markers = _find_markers(
+            "This is a well-configured branch prompt with real content.",
+            True,
+        )
+        assert markers == []
+
+    def test_case_insensitive_detection(self):
+        from aipass.seedgo.apps.handlers.aipass_standards.template_check import (
+            _find_markers,
+        )
+
+        markers = _find_markers("needs configuration", False)
+        assert any("NEEDS CONFIGURATION" in m for m in markers)
+
+
+# ===========================================================================
+# 2. check_branch — integration tests
+# ===========================================================================
+
+
+class TestCheckBranch:
+    """Tests for the check_branch function."""
+
+    def test_stub_prompt_flagged(self, tmp_path):
+        from aipass.seedgo.apps.handlers.aipass_standards.template_check import (
+            check_branch,
+        )
+
+        aipass_dir = tmp_path / ".aipass"
+        aipass_dir.mkdir()
+        (aipass_dir / "aipass_local_prompt.md").write_text(
+            "# {{BRANCHNAME}}\nNEEDS CONFIGURATION\n"
+            "INSTRUCTIONS FOR FILLING OUT THIS TEMPLATE\n"
+            "WHEN YOU'RE DONE, delete this block.\n"
+            "Role: {one-line role description}\n"
+        )
+        (tmp_path / "README.md").write_text("# My Branch\nConfigured.")
+        trinity = tmp_path / ".trinity"
+        trinity.mkdir()
+        (trinity / "passport.json").write_text('{"branch": "test"}')
+
+        result = check_branch(str(tmp_path))
+        assert result["passed"] is True
+        assert result["advisory"] is True
+        assert result["score"] < 100
+        prompt_check = next(c for c in result["checks"] if "aipass_local_prompt" in c["name"])
+        assert not prompt_check["passed"]
+        assert "template markers" in prompt_check["message"]
+
+    def test_configured_branch_clean(self, tmp_path):
+        from aipass.seedgo.apps.handlers.aipass_standards.template_check import (
+            check_branch,
+        )
+
+        aipass_dir = tmp_path / ".aipass"
+        aipass_dir.mkdir()
+        (aipass_dir / "aipass_local_prompt.md").write_text("# My Branch\nThis is my real prompt with real content.")
+        (tmp_path / "README.md").write_text("# My Branch\nReal documentation.")
+        trinity = tmp_path / ".trinity"
+        trinity.mkdir()
+        (trinity / "passport.json").write_text(json.dumps({"branch": "test", "role": "builder"}))
+
+        result = check_branch(str(tmp_path))
+        assert result["passed"] is True
+        assert result["score"] == 100
+        assert all(c["passed"] for c in result["checks"])
+
+    def test_bypass_suppresses_warning(self, tmp_path):
+        from aipass.seedgo.apps.handlers.aipass_standards.template_check import (
+            check_branch,
+        )
+
+        aipass_dir = tmp_path / ".aipass"
+        aipass_dir.mkdir()
+        (aipass_dir / "aipass_local_prompt.md").write_text("NEEDS CONFIGURATION\n{{BRANCH}}\n")
+        (tmp_path / "README.md").write_text("# Configured\nReal content.")
+
+        bypass_rules = [
+            {
+                "file": "aipass_local_prompt",
+                "standard": "template",
+                "reason": "intentionally left as template",
+            }
+        ]
+        result = check_branch(str(tmp_path), bypass_rules=bypass_rules)
+        prompt_check = next(c for c in result["checks"] if "aipass_local_prompt" in c["name"])
+        assert prompt_check["passed"]
+        assert "bypassed" in prompt_check["message"]
+
+    def test_trinity_json_no_false_positive(self, tmp_path):
+        from aipass.seedgo.apps.handlers.aipass_standards.template_check import (
+            check_branch,
+        )
+
+        aipass_dir = tmp_path / ".aipass"
+        aipass_dir.mkdir()
+        (aipass_dir / "aipass_local_prompt.md").write_text("Real prompt.")
+        (tmp_path / "README.md").write_text("# Branch\nReal docs.")
+        trinity = tmp_path / ".trinity"
+        trinity.mkdir()
+        (trinity / "passport.json").write_text(
+            json.dumps(
+                {
+                    "branch_info": {"branch_name": "test"},
+                    "identity": {"role": "builder", "purpose": "testing"},
+                    "nested": {"key": "value"},
+                }
+            )
+        )
+        (trinity / "local.json").write_text(
+            json.dumps(
+                {
+                    "sessions": [{"date": "2026-01-01", "summary": "work"}],
+                    "todos": [],
+                }
+            )
+        )
+
+        result = check_branch(str(tmp_path))
+        assert result["score"] == 100
+        trinity_checks = [c for c in result["checks"] if c["name"].endswith(".json")]
+        assert all(c["passed"] for c in trinity_checks)
+
+    def test_standard_level_bypass(self, tmp_path):
+        from aipass.seedgo.apps.handlers.aipass_standards.template_check import (
+            check_branch,
+        )
+
+        bypass_rules = [{"standard": "template", "reason": "skip all"}]
+        result = check_branch(str(tmp_path), bypass_rules=bypass_rules)
+        assert result["passed"] is True
+        assert result["score"] == 100
+
+    def test_missing_targets_skipped(self, tmp_path):
+        from aipass.seedgo.apps.handlers.aipass_standards.template_check import (
+            check_branch,
+        )
+
+        result = check_branch(str(tmp_path))
+        assert result["passed"] is True
+        assert result["advisory"] is True
+
+    def test_curly_placeholders_in_prompt(self, tmp_path):
+        from aipass.seedgo.apps.handlers.aipass_standards.template_check import (
+            check_branch,
+        )
+
+        aipass_dir = tmp_path / ".aipass"
+        aipass_dir.mkdir()
+        (aipass_dir / "aipass_local_prompt.md").write_text(
+            "Role: {one-line role description}\nDo: {Primary responsibility}\nCommands: {command1}\n"
+        )
+        (tmp_path / "README.md").write_text("# Branch\nConfigured.")
+
+        result = check_branch(str(tmp_path))
+        prompt_check = next(c for c in result["checks"] if "aipass_local_prompt" in c["name"])
+        assert not prompt_check["passed"]
+        assert "single-curly" in prompt_check["message"]
diff --git a/src/aipass/skills/.aipass/aipass_local_prompt.md b/src/aipass/skills/.aipass/aipass_local_prompt.md
index a00be480..02b476ec 100644
--- a/src/aipass/skills/.aipass/aipass_local_prompt.md
+++ b/src/aipass/skills/.aipass/aipass_local_prompt.md
@@ -1,5 +1,5 @@
 # SKILLS — Branch Context
-<!-- File: src/skills/.aipass/aipass_local_prompt.md — Injected on every prompt when in skills directory. -->
+<!-- File: src/aipass/skills/.aipass/aipass_local_prompt.md — Injected on every prompt when in skills directory. -->
 
 Capability framework for AI agents. Discoverable, validatable, executable skill units across three tiers: markdown-only, with handler, full 3-layer.
 
@@ -34,7 +34,7 @@ apps/
 │   ├── validator.py          # Requirement checking (pip, bins, config)
 │   └── template.py           # Template resolution and copying
 ├── plugins/               # Extension point (empty)
-catalog/                   # Built-in skills: drone_commands, github, system_status
+lib/                       # Built-in skills: branch_health, drone_commands, github, inbox_check, system_status, telegram
 templates/                 # Skill creation templates (markdown_only, with_handler, full)
 ```
 
@@ -42,7 +42,7 @@ templates/                 # Skill creation templates (markdown_only, with_handl
 
 1. `.aipass/skills/` — Project-local skills
 2. `~/.aipass/skills/` — Global user skills
-3. `src/skills/catalog/` — Built-in skills
+3. `src/aipass/skills/lib/` — Built-in skills
 
 ## Three Skill Tiers
 
diff --git a/src/aipass/skills/.aipass/skills/another_test/SKILL.md b/src/aipass/skills/.aipass/skills/another_test/SKILL.md
deleted file mode 100644
index bc7f5601..00000000
--- a/src/aipass/skills/.aipass/skills/another_test/SKILL.md
+++ /dev/null
@@ -1,27 +0,0 @@
----
-name: another_test
-description: TODO — describe what this skill does
-version: 1.0.0
-tags: []
-requires:
-  pip: []
-  bins: []
-  config: []
-has_handler: true
----
-
-# another_test
-
-## What This Does
-TODO
-
-## When to Use
-TODO
-
-## Steps
-1. TODO
-
-## Example
-```
-TODO
-```
diff --git a/src/aipass/skills/.aipass/skills/another_test/handler.py b/src/aipass/skills/.aipass/skills/another_test/handler.py
deleted file mode 100644
index aa687a64..00000000
--- a/src/aipass/skills/.aipass/skills/another_test/handler.py
+++ /dev/null
@@ -1,30 +0,0 @@
-"""
-another_test skill handler
-
-Called by: drone @skills run another_test <action> [args]
-"""
-
-
-def run(action, args=None, config=None):
-    """Execute a skill action.
-
-    Args:
-        action: What to do
-        args: Dict of action arguments
-        config: Dict of resolved config values
-
-    Returns:
-        {"success": bool, "output": str, "error": str|None}
-    """
-    args = args or {}
-    config = config or {}
-
-    if action == "example":
-        return {"success": True, "output": "It works!", "error": None}
-
-    return {"success": False, "output": "", "error": f"Unknown action: {action}"}
-
-
-def get_actions():
-    """List available actions for this skill."""
-    return ["example"]
diff --git a/src/aipass/skills/.aipass/skills/full_test/SKILL.md b/src/aipass/skills/.aipass/skills/full_test/SKILL.md
deleted file mode 100644
index 14ccde01..00000000
--- a/src/aipass/skills/.aipass/skills/full_test/SKILL.md
+++ /dev/null
@@ -1,27 +0,0 @@
----
-name: full_test
-description: TODO — describe what this skill does
-version: 1.0.0
-tags: []
-requires:
-  pip: []
-  bins: []
-  config: []
-has_handler: true
----
-
-# full_test
-
-## What This Does
-TODO
-
-## When to Use
-TODO
-
-## Steps
-1. TODO
-
-## Example
-```
-TODO
-```
diff --git a/src/aipass/skills/.aipass/skills/full_test/apps/__init__.py b/src/aipass/skills/.aipass/skills/full_test/apps/__init__.py
deleted file mode 100644
index 254aa8dd..00000000
--- a/src/aipass/skills/.aipass/skills/full_test/apps/__init__.py
+++ /dev/null
@@ -1,7 +0,0 @@
-# ===================AIPASS====================
-# META DATA HEADER
-# Name: __init__.py - full_test apps package
-# Date: 2026-03-07
-# Version: 1.0.0
-# Category: skills/catalog/full_test/apps
-# =============================================
diff --git a/src/aipass/skills/.aipass/skills/full_test/apps/handlers/__init__.py b/src/aipass/skills/.aipass/skills/full_test/apps/handlers/__init__.py
deleted file mode 100644
index d8469cca..00000000
--- a/src/aipass/skills/.aipass/skills/full_test/apps/handlers/__init__.py
+++ /dev/null
@@ -1,13 +0,0 @@
-# ===================AIPASS====================
-# META DATA HEADER
-# Name: __init__.py - full_test handlers package
-# Date: 2026-03-07
-# Version: 1.0.0
-# Category: skills/catalog/full_test/apps/handlers
-#
-# CHANGELOG (Max 5 entries):
-#   - v1.0.0 (2026-03-07): Initial scaffold
-#
-# CODE STANDARDS:
-#   - Handlers layer: returns dicts, NEVER prints
-# =============================================
diff --git a/src/aipass/skills/.aipass/skills/full_test/apps/modules/__init__.py b/src/aipass/skills/.aipass/skills/full_test/apps/modules/__init__.py
deleted file mode 100644
index f1d4d7f5..00000000
--- a/src/aipass/skills/.aipass/skills/full_test/apps/modules/__init__.py
+++ /dev/null
@@ -1,13 +0,0 @@
-# ===================AIPASS====================
-# META DATA HEADER
-# Name: __init__.py - full_test modules package
-# Date: 2026-03-07
-# Version: 1.0.0
-# Category: skills/catalog/full_test/apps/modules
-#
-# CHANGELOG (Max 5 entries):
-#   - v1.0.0 (2026-03-07): Initial scaffold
-#
-# CODE STANDARDS:
-#   - Modules layer: orchestration (can print)
-# =============================================
diff --git a/src/aipass/skills/.aipass/skills/full_test/handler.py b/src/aipass/skills/.aipass/skills/full_test/handler.py
deleted file mode 100644
index d213f2ba..00000000
--- a/src/aipass/skills/.aipass/skills/full_test/handler.py
+++ /dev/null
@@ -1,24 +0,0 @@
-"""
-full_test — Full 3-layer skill handler.
-
-Scaffolded by: drone @skills create full_test --full
-"""
-
-
-def run(action: str, args: list, config: dict) -> dict:
-    """
-    Execute the skill.
-
-    Args:
-        action: The action to perform
-        args: Command arguments
-        config: Skill configuration from SKILL.md
-
-    Returns:
-        dict with keys: success (bool), output (str), error (str|None)
-    """
-    return {
-        "success": True,
-        "output": f"full_test executed action: {action}",
-        "error": None,
-    }
diff --git a/src/aipass/skills/.aipass/skills/test_skill/SKILL.md b/src/aipass/skills/.aipass/skills/test_skill/SKILL.md
deleted file mode 100644
index a9e3aa22..00000000
--- a/src/aipass/skills/.aipass/skills/test_skill/SKILL.md
+++ /dev/null
@@ -1,27 +0,0 @@
----
-name: test_skill
-description: TODO — describe what this skill does
-version: 1.0.0
-tags: []
-requires:
-  pip: []
-  bins: []
-  config: []
-has_handler: false
----
-
-# test_skill
-
-## What This Does
-TODO
-
-## When to Use
-TODO
-
-## Steps
-1. TODO
-
-## Example
-```
-TODO
-```
diff --git a/src/aipass/skills/.gitignore b/src/aipass/skills/.gitignore
index 9cf1dfc4..a926f1c5 100644
--- a/src/aipass/skills/.gitignore
+++ b/src/aipass/skills/.gitignore
@@ -12,3 +12,4 @@ build/
 *.log
 *.tmp
 *.swp
+.local/
diff --git a/src/aipass/skills/.seedgo/bypass.json b/src/aipass/skills/.seedgo/bypass.json
index cbbfffc4..a27dc525 100644
--- a/src/aipass/skills/.seedgo/bypass.json
+++ b/src/aipass/skills/.seedgo/bypass.json
@@ -6,15 +6,181 @@
   },
   "bypass": [
     {
-      "file": ".aipass/skills/telegram/tests/test_response_router.py",
+      "file": "lib/telegram/tests/conftest.py",
+      "standard": "architecture",
+      "reason": "Test infrastructure — conftest.py lives in tests/ by pytest convention, not the 3-layer app structure. Test support files are exempt."
+    },
+    {
+      "file": "lib/telegram/tests/conftest.py",
+      "standard": "encapsulation",
+      "reason": "Test infrastructure — imports aipass.prax.apps.handlers.logging.direct to redirect log output during tests. Necessary to clear cached logger state; no module entry point exists for this internal reset."
+    },
+    {
+      "file": "lib/telegram/tests/conftest.py",
+      "standard": "imports",
+      "reason": "Test infrastructure — sys.path manipulation is intentional: adds src/ root for aipass.* imports and skill root for local apps.handlers.* imports. Required because tests run without a full pip install of the skill."
+    },
+    {
+      "file": "lib/telegram/tests/test_response_router.py",
       "standard": "architecture",
       "reason": "Test file — lives in tests/ by convention, not in the 3-layer app structure. Test files are exempt from layer architecture standard."
     },
     {
-      "file": ".aipass/skills/telegram/tests/test_response_router.py",
+      "file": "lib/telegram/tests/test_response_router.py",
       "standard": "encapsulation",
       "reason": "Test file — imports handler module directly for unit testing. Tests need direct access to monkeypatch module-level attributes and verify handler behavior."
     },
+    {
+      "file": "lib/telegram/tests/test_monitor.py",
+      "standard": "architecture",
+      "reason": "Test file — lives in tests/ by convention. Test files are exempt from layer architecture standard."
+    },
+    {
+      "file": "lib/telegram/tests/test_monitor.py",
+      "standard": "encapsulation",
+      "reason": "Test file — imports handler directly for unit testing. Tests need direct access to patch module-level state and verify handler internals."
+    },
+    {
+      "file": "lib/telegram/tests/test_monitor.py",
+      "standard": "documentation",
+      "reason": "Test file — public functions are pytest test methods; docstrings on individual test methods are optional when class docstring and test name are self-documenting."
+    },
+    {
+      "file": "lib/telegram/tests/test_multi_bot.py",
+      "standard": "architecture",
+      "reason": "Test file — lives in tests/ by convention. Test files are exempt from layer architecture standard."
+    },
+    {
+      "file": "lib/telegram/tests/test_multi_bot.py",
+      "standard": "encapsulation",
+      "reason": "Test file — imports handler directly for unit testing. Tests need direct access to patch module-level state."
+    },
+    {
+      "file": "lib/telegram/tests/test_multi_bot.py",
+      "standard": "documentation",
+      "reason": "Test file — pytest test methods are self-documenting via class/method names; docstrings on individual test cases are optional."
+    },
+    {
+      "file": "lib/telegram/tests/test_multi_bot.py",
+      "standard": "hardcoded_path",
+      "reason": "Test data — /home/aipass/* paths are mock return values passed to validate_branch() and create_bot() mocks, not real filesystem paths. They represent synthetic registry entries in test fixtures."
+    },
+    {
+      "file": "lib/telegram/tests/test_multi_bot.py",
+      "standard": "trigger",
+      "lines": [409],
+      "reason": "Test-only teardown — base_bot.pending_file.unlink() simulates file absence to verify heartbeat backward-compat behavior. No trigger event is appropriate for test fixture manipulation."
+    },
+    {
+      "file": "lib/telegram/tests/test_attach_only.py",
+      "standard": "architecture",
+      "reason": "Test file — lives in tests/ by convention. Test files are exempt from layer architecture standard."
+    },
+    {
+      "file": "lib/telegram/tests/test_attach_only.py",
+      "standard": "encapsulation",
+      "reason": "Test file — imports handler directly for unit testing."
+    },
+    {
+      "file": "lib/telegram/tests/test_attach_only.py",
+      "standard": "documentation",
+      "reason": "Test file — pytest test methods are self-documenting via class/method names."
+    },
+    {
+      "file": "lib/telegram/tests/test_presence_pointer.py",
+      "standard": "architecture",
+      "reason": "Test file — lives in tests/ by convention. Test files are exempt from layer architecture standard."
+    },
+    {
+      "file": "lib/telegram/tests/test_presence_pointer.py",
+      "standard": "encapsulation",
+      "reason": "Test file — imports handler directly for unit testing. Same pattern as test_multi_bot.py and test_attach_only.py."
+    },
+    {
+      "file": "lib/telegram/tests/test_streaming.py",
+      "standard": "architecture",
+      "reason": "Test file — lives in tests/ by convention. Test files are exempt from layer architecture standard."
+    },
+    {
+      "file": "lib/telegram/tests/test_streaming.py",
+      "standard": "encapsulation",
+      "reason": "Test file — imports handler directly for unit testing. Same pattern as all other TG test files."
+    },
+    {
+      "file": "lib/telegram/tests/test_streaming.py",
+      "standard": "documentation",
+      "reason": "Test file — pytest test methods are self-documenting via class/method names."
+    },
+    {
+      "file": "lib/telegram/tests/test_heartbeat_delivered.py",
+      "standard": "architecture",
+      "reason": "Test file — lives in tests/ by convention. Test files are exempt from layer architecture standard."
+    },
+    {
+      "file": "lib/telegram/tests/test_heartbeat_delivered.py",
+      "standard": "encapsulation",
+      "reason": "Test file — imports handler directly for unit testing."
+    },
+    {
+      "file": "lib/telegram/tests/test_heartbeat_delivered.py",
+      "standard": "documentation",
+      "reason": "Test file — pytest test methods are self-documenting via class/method names."
+    },
+    {
+      "file": "lib/telegram/tests/test_status_reset.py",
+      "standard": "architecture",
+      "reason": "Test file — lives in tests/ by convention. Test files are exempt from layer architecture standard."
+    },
+    {
+      "file": "lib/telegram/tests/test_status_reset.py",
+      "standard": "encapsulation",
+      "reason": "Test file — imports handler directly for unit testing."
+    },
+    {
+      "file": "lib/telegram/tests/test_status_reset.py",
+      "standard": "documentation",
+      "reason": "Test file — pytest test methods are self-documenting via class/method names."
+    },
+    {
+      "file": "lib/telegram/tests/test_mirror_session.py",
+      "standard": "architecture",
+      "reason": "Test file — lives in tests/ by convention. Test files are exempt from layer architecture standard."
+    },
+    {
+      "file": "lib/telegram/tests/test_mirror_session.py",
+      "standard": "encapsulation",
+      "reason": "Test file — imports handler directly for unit testing."
+    },
+    {
+      "file": "lib/telegram/tests/test_mirror_session.py",
+      "standard": "hardcoded_path",
+      "reason": "Test data — /home/test/api is a mock return value for validate_branch(), not a real filesystem path."
+    },
+    {
+      "file": "lib/telegram/tests/test_mirror_session.py",
+      "standard": "permission_flags",
+      "reason": "Test file — asserts that launch_mirror_session() correctly passes --dangerously-skip-permissions. Testing the TDPLAN-0009 feature, not bypassing permissions."
+    },
+    {
+      "file": "lib/telegram/apps/handlers/bot_factory.py",
+      "standard": "handlers",
+      "reason": "DPLAN-0220 incomplete port — bot_factory imports _api_set_secret from aipass.api.apps.modules.secrets for config persistence. Same pattern as config.py."
+    },
+    {
+      "file": "lib/telegram/apps/handlers/bot_factory.py",
+      "standard": "json_structure",
+      "reason": "DPLAN-0220 incomplete port — factory functions predate json_handler.log_operation convention. Adding log_operation to every function is a separate cleanup task."
+    },
+    {
+      "file": "lib/telegram/apps/handlers/bot_factory.py",
+      "standard": "meta",
+      "reason": "DPLAN-0220 incomplete port — file uses legacy header format from Dev-Pass port, not the META block format."
+    },
+    {
+      "file": "lib/telegram/apps/handlers/bot_factory.py",
+      "standard": "permission_flags",
+      "reason": "TDPLAN-0009 — launch_mirror_session() intentionally uses --dangerously-skip-permissions. Detached tmux mirror sessions have no operator to approve prompts; without it the session hangs forever. Patrick's explicit ask."
+    },
     {
       "file": "apps/handlers/loader_handler.py",
       "standard": "handlers",
@@ -39,9 +205,56 @@
     {
       "file": "apps/handlers/registry.py",
       "standard": "unused_function",
-      "lines": [52, 68],
-      "pattern": "def get_skill|def get_skill_names",
+      "functions": ["get_skill", "get_skill_names"],
       "reason": "Public API functions — used by test_registry.py and available for external callers; part of the registry module's contract"
+    },
+    {
+      "file": "lib/telegram/apps/handlers/base_bot.py",
+      "standard": "unused_function",
+      "functions": ["chunk_text", "on_response", "_read_transcript_tail", "_extract_assistant_text"],
+      "reason": "DPLAN-0220/DPLAN-0226 — chunk_text + on_response are ported-but-unwired (Dev-Pass). _read_transcript_tail + _extract_assistant_text are DPLAN-0226 OUT relay infrastructure: built and tested, wiring pending end-to-end integration."
+    },
+    {
+      "file": "lib/telegram/apps/handlers/bot_operations.py",
+      "standard": "unused_function",
+      "functions": ["get_all_bots"],
+      "reason": "DPLAN-0220 incomplete port — multi-bot listing helper, ported-but-unwired pending multi-bot wiring. See README → Ported-but-unwired."
+    },
+    {
+      "file": "lib/telegram/apps/handlers/bot_registry.py",
+      "standard": "unused_function",
+      "functions": ["get_bot_by_work_dir"],
+      "reason": "DPLAN-0220 incomplete port — used by the response router to match CWD→bot; awaits the response_router wiring (td-38 import-vs-delete). See README → Ported-but-unwired."
+    },
+    {
+      "file": "lib/telegram/apps/handlers/branch_plugin.py",
+      "standard": "unused_function",
+      "functions": ["on_response"],
+      "reason": "DPLAN-0220 incomplete port — branch-plugin response hook, ported-but-unwired; pending Wave-2 on_response design call (td-38). See README → Ported-but-unwired."
+    },
+    {
+      "file": "lib/telegram/apps/handlers/config.py",
+      "standard": "unused_function",
+      "functions": ["get_allowed_user_ids", "validate_config"],
+      "reason": "DPLAN-0220 incomplete port — config accessors/validator ported-but-unwired, pending wiring. See README → Ported-but-unwired."
+    },
+    {
+      "file": "lib/telegram/apps/handlers/file_handler.py",
+      "standard": "unused_function",
+      "functions": ["download_telegram_file", "cleanup_file"],
+      "reason": "DPLAN-0220 incomplete port — file up/download feature ported-but-unwired, pending wiring. See README → Ported-but-unwired."
+    },
+    {
+      "file": "lib/telegram/apps/handlers/response_router.py",
+      "standard": "unused_function",
+      "functions": ["find_pending_bot", "clean_expired_pending"],
+      "reason": "DPLAN-0220 incomplete port — response-router helpers, pending the response_router import-vs-delete design call (td-38). See README → Ported-but-unwired."
+    },
+    {
+      "file": "lib/telegram/apps/handlers/tmux_manager.py",
+      "standard": "unused_function",
+      "functions": ["_send_rename", "has_tmux", "kill_session", "list_sessions", "get_session_pane"],
+      "reason": "DPLAN-0220 incomplete port — interactive tmux session management, ported-but-unwired pending wiring (td-38 tmux). See README → Ported-but-unwired."
     }
   ],
   "notes": {
diff --git a/src/aipass/skills/README.md b/src/aipass/skills/README.md
index 94f0afe6..97ed0ca4 100644
--- a/src/aipass/skills/README.md
+++ b/src/aipass/skills/README.md
@@ -104,7 +104,7 @@ Skills are discovered in this order (first match wins for same name):
 
 1. **Project**: `.aipass/skills/` in the current working directory
 2. **Global**: `~/.aipass/skills/` in the user's home directory
-3. **Built-in**: `src/skills/catalog/` in the AIPass codebase
+3. **Built-in**: `src/aipass/skills/lib/` in the AIPass codebase
 
 ## Commands / Usage
 
@@ -124,7 +124,7 @@ drone @skills --help                       # Show help
 ## Directory Structure
 
 ```
-src/skills/
+src/aipass/skills/
   apps/
     skills.py              # Entry point (handle_command)
     modules/
@@ -140,7 +140,7 @@ src/skills/
       validator.py         # Check requirements
       template.py          # Skill templates
     plugins/               # Plugin extensions
-  catalog/                 # Built-in skills (branch_health, drone_commands, github, inbox_check, system_status)
+  lib/                     # Built-in skills (branch_health, drone_commands, github, inbox_check, system_status, telegram)
   templates/               # Skill creation templates
   skills_json/             # JSON tracking directory
   dropbox/                 # External storage sync
diff --git a/src/aipass/skills/apps/handlers/discovery_handler.py b/src/aipass/skills/apps/handlers/discovery_handler.py
index 86644465..8f49474e 100644
--- a/src/aipass/skills/apps/handlers/discovery_handler.py
+++ b/src/aipass/skills/apps/handlers/discovery_handler.py
@@ -39,7 +39,7 @@ def get_search_paths():
     Search order (first match wins for same name):
         1. Current project: .aipass/skills/
         2. Global user: ~/.aipass/skills/
-        3. Built-in: src/skills/catalog/
+        3. Built-in: src/aipass/skills/lib/
 
     Returns:
         list[tuple[Path, str]]: List of (path, source_label) tuples.
@@ -54,8 +54,8 @@ def get_search_paths():
     global_path = Path.home() / ".aipass" / "skills"
     paths.append((global_path, "global"))
 
-    # 3. Built-in catalog
-    builtin_path = Path(__file__).resolve().parent.parent.parent / "catalog"
+    # 3. Built-in lib
+    builtin_path = Path(__file__).resolve().parent.parent.parent / "lib"
     paths.append((builtin_path, "builtin"))
 
     return paths
diff --git a/src/aipass/skills/apps/handlers/template.py b/src/aipass/skills/apps/handlers/template.py
index 9ded5643..989c2e25 100644
--- a/src/aipass/skills/apps/handlers/template.py
+++ b/src/aipass/skills/apps/handlers/template.py
@@ -13,7 +13,7 @@ from aipass.prax import logger
 from aipass.skills.apps.handlers.json import json_handler
 
 
-# Template directory lives at src/skills/templates/
+# Template directory lives at src/aipass/skills/templates/
 TEMPLATES_DIR = Path(__file__).resolve().parent.parent.parent / "templates"
 
 VALID_TYPES = ("markdown_only", "with_handler", "full")
diff --git a/src/aipass/skills/apps/skills.py b/src/aipass/skills/apps/skills.py
index a774988f..d8e75b78 100644
--- a/src/aipass/skills/apps/skills.py
+++ b/src/aipass/skills/apps/skills.py
@@ -123,7 +123,7 @@ def print_help():
     console.print("Search paths (first match wins):")
     console.print("  1. .aipass/skills/           Project-local skills")
     console.print("  2. ~/.aipass/skills/         Global user skills")
-    console.print("  3. src/skills/catalog/       Built-in skills")
+    console.print("  3. src/aipass/skills/lib/     Built-in skills")
 
 
 def _cmd_list():
diff --git a/src/aipass/skills/catalog/.gitkeep b/src/aipass/skills/lib/.gitkeep
similarity index 100%
rename from src/aipass/skills/catalog/.gitkeep
rename to src/aipass/skills/lib/.gitkeep
diff --git a/src/aipass/skills/.aipass/skills/telegram/tests/__init__.py b/src/aipass/skills/lib/__init__.py
similarity index 100%
rename from src/aipass/skills/.aipass/skills/telegram/tests/__init__.py
rename to src/aipass/skills/lib/__init__.py
diff --git a/src/aipass/skills/catalog/branch_health/SKILL.md b/src/aipass/skills/lib/branch_health/SKILL.md
similarity index 100%
rename from src/aipass/skills/catalog/branch_health/SKILL.md
rename to src/aipass/skills/lib/branch_health/SKILL.md
diff --git a/src/aipass/skills/catalog/branch_health/handler.py b/src/aipass/skills/lib/branch_health/handler.py
similarity index 98%
rename from src/aipass/skills/catalog/branch_health/handler.py
rename to src/aipass/skills/lib/branch_health/handler.py
index c9d74b8d..cb6665fd 100644
--- a/src/aipass/skills/catalog/branch_health/handler.py
+++ b/src/aipass/skills/lib/branch_health/handler.py
@@ -3,7 +3,7 @@
 # Name: handler.py - Branch Health skill handler
 # Date: 2026-03-29
 # Version: 1.0.0
-# Category: skills/catalog/branch_health
+# Category: skills/lib/branch_health
 # =============================================
 
 """
@@ -58,7 +58,7 @@ def get_actions():
 
 def _src_root():
     """Return the src/ directory by navigating up from this handler."""
-    # handler.py -> branch_health/ -> catalog/ -> skills/ -> aipass/ -> src/
+    # handler.py -> branch_health/ -> lib/ -> skills/ -> aipass/ -> src/
     return Path(__file__).resolve().parents[4]
 
 
diff --git a/src/aipass/skills/catalog/drone_commands/SKILL.md b/src/aipass/skills/lib/drone_commands/SKILL.md
similarity index 100%
rename from src/aipass/skills/catalog/drone_commands/SKILL.md
rename to src/aipass/skills/lib/drone_commands/SKILL.md
diff --git a/src/aipass/skills/catalog/drone_commands/apps/__init__.py b/src/aipass/skills/lib/drone_commands/apps/__init__.py
similarity index 87%
rename from src/aipass/skills/catalog/drone_commands/apps/__init__.py
rename to src/aipass/skills/lib/drone_commands/apps/__init__.py
index 1db46e55..faa1eed7 100644
--- a/src/aipass/skills/catalog/drone_commands/apps/__init__.py
+++ b/src/aipass/skills/lib/drone_commands/apps/__init__.py
@@ -3,7 +3,7 @@
 # Name: __init__.py - drone_commands apps package
 # Date: 2026-03-07
 # Version: 1.0.0
-# Category: skills/catalog/drone_commands/apps
+# Category: skills/lib/drone_commands/apps
 #
 # CHANGELOG (Max 5 entries):
 #   - v1.0.0 (2026-03-07): Initial implementation
diff --git a/src/aipass/skills/catalog/drone_commands/apps/handlers/__init__.py b/src/aipass/skills/lib/drone_commands/apps/handlers/__init__.py
similarity index 86%
rename from src/aipass/skills/catalog/drone_commands/apps/handlers/__init__.py
rename to src/aipass/skills/lib/drone_commands/apps/handlers/__init__.py
index a38b5733..b9161bf0 100644
--- a/src/aipass/skills/catalog/drone_commands/apps/handlers/__init__.py
+++ b/src/aipass/skills/lib/drone_commands/apps/handlers/__init__.py
@@ -3,7 +3,7 @@
 # Name: __init__.py - drone_commands handlers package
 # Date: 2026-03-07
 # Version: 1.0.0
-# Category: skills/catalog/drone_commands/apps/handlers
+# Category: skills/lib/drone_commands/apps/handlers
 #
 # CHANGELOG (Max 5 entries):
 #   - v1.0.0 (2026-03-07): Initial implementation
diff --git a/src/aipass/skills/catalog/drone_commands/apps/handlers/executor.py b/src/aipass/skills/lib/drone_commands/apps/handlers/executor.py
similarity index 98%
rename from src/aipass/skills/catalog/drone_commands/apps/handlers/executor.py
rename to src/aipass/skills/lib/drone_commands/apps/handlers/executor.py
index a25910ff..d2b12738 100644
--- a/src/aipass/skills/catalog/drone_commands/apps/handlers/executor.py
+++ b/src/aipass/skills/lib/drone_commands/apps/handlers/executor.py
@@ -3,7 +3,7 @@
 # Name: executor.py - Runs drone commands via subprocess
 # Date: 2026-03-07
 # Version: 1.0.0
-# Category: skills/catalog/drone_commands/apps/handlers
+# Category: skills/lib/drone_commands/apps/handlers
 #
 # CHANGELOG (Max 5 entries):
 #   - v1.0.0 (2026-03-07): Initial implementation
diff --git a/src/aipass/skills/catalog/drone_commands/apps/handlers/parser.py b/src/aipass/skills/lib/drone_commands/apps/handlers/parser.py
similarity index 98%
rename from src/aipass/skills/catalog/drone_commands/apps/handlers/parser.py
rename to src/aipass/skills/lib/drone_commands/apps/handlers/parser.py
index 74737a98..b79748aa 100644
--- a/src/aipass/skills/catalog/drone_commands/apps/handlers/parser.py
+++ b/src/aipass/skills/lib/drone_commands/apps/handlers/parser.py
@@ -3,7 +3,7 @@
 # Name: parser.py - Parses drone command output
 # Date: 2026-03-07
 # Version: 1.0.0
-# Category: skills/catalog/drone_commands/apps/handlers
+# Category: skills/lib/drone_commands/apps/handlers
 #
 # CHANGELOG (Max 5 entries):
 #   - v1.0.0 (2026-03-07): Initial implementation
diff --git a/src/aipass/skills/catalog/drone_commands/apps/modules/__init__.py b/src/aipass/skills/lib/drone_commands/apps/modules/__init__.py
similarity index 86%
rename from src/aipass/skills/catalog/drone_commands/apps/modules/__init__.py
rename to src/aipass/skills/lib/drone_commands/apps/modules/__init__.py
index 310625a8..cb856a82 100644
--- a/src/aipass/skills/catalog/drone_commands/apps/modules/__init__.py
+++ b/src/aipass/skills/lib/drone_commands/apps/modules/__init__.py
@@ -3,7 +3,7 @@
 # Name: __init__.py - drone_commands modules package
 # Date: 2026-03-07
 # Version: 1.0.0
-# Category: skills/catalog/drone_commands/apps/modules
+# Category: skills/lib/drone_commands/apps/modules
 #
 # CHANGELOG (Max 5 entries):
 #   - v1.0.0 (2026-03-07): Initial implementation
diff --git a/src/aipass/skills/catalog/drone_commands/apps/modules/command_runner.py b/src/aipass/skills/lib/drone_commands/apps/modules/command_runner.py
similarity index 98%
rename from src/aipass/skills/catalog/drone_commands/apps/modules/command_runner.py
rename to src/aipass/skills/lib/drone_commands/apps/modules/command_runner.py
index ba34f1dd..a52ab77e 100644
--- a/src/aipass/skills/catalog/drone_commands/apps/modules/command_runner.py
+++ b/src/aipass/skills/lib/drone_commands/apps/modules/command_runner.py
@@ -3,7 +3,7 @@
 # Name: command_runner.py - Orchestrates drone command execution
 # Date: 2026-03-07
 # Version: 1.0.0
-# Category: skills/catalog/drone_commands/apps/modules
+# Category: skills/lib/drone_commands/apps/modules
 #
 # CHANGELOG (Max 5 entries):
 #   - v1.0.0 (2026-03-07): Initial implementation
diff --git a/src/aipass/skills/catalog/drone_commands/handler.py b/src/aipass/skills/lib/drone_commands/handler.py
similarity index 98%
rename from src/aipass/skills/catalog/drone_commands/handler.py
rename to src/aipass/skills/lib/drone_commands/handler.py
index 88f679e4..dd303535 100644
--- a/src/aipass/skills/catalog/drone_commands/handler.py
+++ b/src/aipass/skills/lib/drone_commands/handler.py
@@ -3,7 +3,7 @@
 # Name: handler.py - Drone Commands skill handler
 # Date: 2026-03-07
 # Version: 1.0.0
-# Category: skills/catalog/drone_commands
+# Category: skills/lib/drone_commands
 #
 # CHANGELOG (Max 5 entries):
 #   - v1.0.0 (2026-03-07): Initial implementation
diff --git a/src/aipass/skills/catalog/github/SKILL.md b/src/aipass/skills/lib/github/SKILL.md
similarity index 100%
rename from src/aipass/skills/catalog/github/SKILL.md
rename to src/aipass/skills/lib/github/SKILL.md
diff --git a/src/aipass/skills/catalog/inbox_check/SKILL.md b/src/aipass/skills/lib/inbox_check/SKILL.md
similarity index 100%
rename from src/aipass/skills/catalog/inbox_check/SKILL.md
rename to src/aipass/skills/lib/inbox_check/SKILL.md
diff --git a/src/aipass/skills/catalog/inbox_check/handler.py b/src/aipass/skills/lib/inbox_check/handler.py
similarity index 98%
rename from src/aipass/skills/catalog/inbox_check/handler.py
rename to src/aipass/skills/lib/inbox_check/handler.py
index c5d23ff3..ed2a3935 100644
--- a/src/aipass/skills/catalog/inbox_check/handler.py
+++ b/src/aipass/skills/lib/inbox_check/handler.py
@@ -3,7 +3,7 @@
 # Name: handler.py - Inbox Check skill handler
 # Date: 2026-03-29
 # Version: 1.0.0
-# Category: skills/catalog/inbox_check
+# Category: skills/lib/inbox_check
 # =============================================
 
 """
@@ -57,7 +57,7 @@ def get_actions():
 
 def _src_root():
     """Return the src/ directory by navigating up from this handler."""
-    # handler.py -> inbox_check/ -> catalog/ -> skills/ -> aipass/ -> src/
+    # handler.py -> inbox_check/ -> lib/ -> skills/ -> aipass/ -> src/
     return Path(__file__).resolve().parents[4]
 
 
diff --git a/src/aipass/skills/catalog/system_status/SKILL.md b/src/aipass/skills/lib/system_status/SKILL.md
similarity index 100%
rename from src/aipass/skills/catalog/system_status/SKILL.md
rename to src/aipass/skills/lib/system_status/SKILL.md
diff --git a/src/aipass/skills/catalog/system_status/handler.py b/src/aipass/skills/lib/system_status/handler.py
similarity index 99%
rename from src/aipass/skills/catalog/system_status/handler.py
rename to src/aipass/skills/lib/system_status/handler.py
index 072ab15e..e2e5cc54 100644
--- a/src/aipass/skills/catalog/system_status/handler.py
+++ b/src/aipass/skills/lib/system_status/handler.py
@@ -3,7 +3,7 @@
 # Name: handler.py - System Status skill handler
 # Date: 2026-03-07
 # Version: 1.0.0
-# Category: skills/catalog/system_status
+# Category: skills/lib/system_status
 # =============================================
 
 """
diff --git a/src/aipass/skills/.aipass/skills/telegram/SKILL.md b/src/aipass/skills/lib/telegram/SKILL.md
similarity index 58%
rename from src/aipass/skills/.aipass/skills/telegram/SKILL.md
rename to src/aipass/skills/lib/telegram/SKILL.md
index 96c625e9..4f17aa50 100644
--- a/src/aipass/skills/.aipass/skills/telegram/SKILL.md
+++ b/src/aipass/skills/lib/telegram/SKILL.md
@@ -4,7 +4,7 @@ description: Multi-bot Telegram bridge — routes messages between Telegram and
 version: 1.0.0
 tags: [communication, bridge, telegram, bot]
 requires:
-  pip: []
+  pip: [telethon]
   bins: [tmux, claude]
   config: []
   aipass: [api, prax, hooks, cli]
@@ -46,3 +46,22 @@ drone @skills run telegram notify "message"
 
 Bot tokens and config accessed via the in-process `aipass.api.apps.modules.secrets.get_secret` API.
 State files (offset, lock, registry) stay with the skill in `.local/`.
+
+## Ported-but-unwired (DPLAN-0220)
+
+This bridge is a partial port of the ~9k-line "Dev-Pass" telegram system. Several
+functions are **ported but not yet wired** — they have no caller today and will be
+connected as DPLAN-0220 completes. They are *not* dead code (do not delete them; see
+S249), so seedgo's `unused_function` check is bypassed for them in
+`.seedgo/bypass.json`. As each one is wired up, remove its bypass entry.
+
+| File | Function(s) | Awaiting |
+|---|---|---|
+| `base_bot.py` | `chunk_text`, `on_response` | long-message split + response hook (on_response = Wave-2 design call) |
+| `branch_plugin.py` | `on_response` | per-branch response hook (Wave-2 design call) |
+| `response_router.py` | `find_pending_bot`, `clean_expired_pending` | response_router import-vs-delete decision |
+| `bot_registry.py` | `get_bot_by_work_dir` | CWD→bot match for the response router |
+| `bot_operations.py` | `get_all_bots` | multi-bot listing |
+| `config.py` | `get_allowed_user_ids`, `validate_config` | config accessor/validator wiring |
+| `file_handler.py` | `download_telegram_file`, `cleanup_file` | file up/download feature |
+| `tmux_manager.py` | `_send_rename`, `has_tmux`, `kill_session`, `list_sessions`, `get_session_pane` | interactive tmux session management |
diff --git a/src/aipass/spawn/templates/builder/apps/modules/__init__.py b/src/aipass/skills/lib/telegram/__init__.py
similarity index 100%
rename from src/aipass/spawn/templates/builder/apps/modules/__init__.py
rename to src/aipass/skills/lib/telegram/__init__.py
diff --git a/src/aipass/skills/.aipass/skills/telegram/apps/__init__.py b/src/aipass/skills/lib/telegram/apps/__init__.py
similarity index 82%
rename from src/aipass/skills/.aipass/skills/telegram/apps/__init__.py
rename to src/aipass/skills/lib/telegram/apps/__init__.py
index 54987023..259abe5d 100644
--- a/src/aipass/skills/.aipass/skills/telegram/apps/__init__.py
+++ b/src/aipass/skills/lib/telegram/apps/__init__.py
@@ -3,5 +3,5 @@
 # Name: __init__.py - telegram apps package
 # Date: 2026-03-07
 # Version: 1.0.0
-# Category: skills/catalog/telegram/apps
+# Category: skills/lib/telegram/apps
 # =============================================
diff --git a/src/aipass/skills/.aipass/skills/telegram/apps/handlers/__init__.py b/src/aipass/skills/lib/telegram/apps/handlers/__init__.py
similarity index 100%
rename from src/aipass/skills/.aipass/skills/telegram/apps/handlers/__init__.py
rename to src/aipass/skills/lib/telegram/apps/handlers/__init__.py
diff --git a/src/aipass/skills/.aipass/skills/telegram/apps/handlers/base_bot.py b/src/aipass/skills/lib/telegram/apps/handlers/base_bot.py
similarity index 61%
rename from src/aipass/skills/.aipass/skills/telegram/apps/handlers/base_bot.py
rename to src/aipass/skills/lib/telegram/apps/handlers/base_bot.py
index cf475aec..746c969b 100644
--- a/src/aipass/skills/.aipass/skills/telegram/apps/handlers/base_bot.py
+++ b/src/aipass/skills/lib/telegram/apps/handlers/base_bot.py
@@ -47,6 +47,7 @@ import argparse
 import atexit
 import json
 import os
+import re
 import signal
 import subprocess
 import sys
@@ -56,7 +57,7 @@ import uuid
 from datetime import datetime
 from pathlib import Path
 from typing import Optional
-from urllib.error import URLError
+from urllib.error import HTTPError, URLError
 from urllib.request import Request, urlopen
 
 # Logging
@@ -84,9 +85,14 @@ from .file_handler import (
 )
 from .bot_factory import (
     create_bot,
+    launch_mirror_session,  # noqa: F401
+    set_bot_commands,
+    start_service,  # noqa: F401
     validate_branch,
     validate_token,
 )
+from .telegram_standards import build_botfather_commands
+
 from .bot_registry import (
     list_bots as registry_list_bots,
     get_bot_by_branch,
@@ -118,6 +124,7 @@ except ImportError:
 # MODULE-LEVEL CONSTANTS
 # =============================================
 
+CC_SESSIONS_DIR = Path.home() / ".claude" / "sessions"
 PENDING_DIR = Path.home() / ".aipass" / "telegram_pending"
 PENDING_TTL = 3600  # 1 hour
 TELEGRAM_CHAR_LIMIT = 4096
@@ -126,7 +133,9 @@ RATE_LIMIT_WINDOW = 60
 POLL_TIMEOUT = 30
 SEND_KEYS_DELAY = 0.5
 HEARTBEAT_INTERVAL = 30  # seconds
+STREAM_INTERVAL = 2  # seconds between streaming edits
 CLAUDE_BIN = str(Path.home() / ".local" / "bin" / "claude")
+MIRROR_SESSION_TYPE = "interactive-mirror"
 TEMP_DIR = Path("/tmp/telegram_uploads")
 MAX_FILE_SIZE = 10 * 1024 * 1024  # 10MB
 
@@ -155,6 +164,8 @@ class BaseBot:
         custom_commands: Optional[dict] = None,
         branch_name: Optional[str] = None,
         shared_session: Optional[str] = None,
+        attach_only: bool = False,
+        stream: bool = False,
     ) -> None:
         """
         Initialize BaseBot.
@@ -190,11 +201,19 @@ class BaseBot:
         # Shared-session mode: inject into an existing tmux session instead of creating own
         self._shared_session_name = shared_session
         self._using_shared_session = False
+        self._attach_only = attach_only
+        self._stream = stream
+        self._mirror_mapping_written = False
+        self._last_transcript_path: str | None = None
+        self._config_chat_id: int | None = None
+        self._active_session_id: str | None = None
+        self._active_transcript_path: Path | None = None
 
         self.state = {
             "running": True,
             "message_count": 0,
             "start_time": time.time(),
+            "conversation_start": time.time(),
             "last_message_time": 0.0,
         }
 
@@ -218,6 +237,9 @@ class BaseBot:
         self._log_streamer: Optional[LogStreamer] = None
         self._active_chat_id: Optional[int] = None
 
+        # Monitor streamer (system-wide, persisted across restarts)
+        self._monitor_streamer: Optional[LogStreamer] = None
+
         # Lock file
         self._lock_file = Path.home() / ".aipass" / "telegram_bots" / f".{bot_id}.lock"
 
@@ -247,12 +269,17 @@ class BaseBot:
         self._health["started_at"] = datetime.now().isoformat()
         json_handler.log_operation("bot_started", {"bot_id": self.bot_id})
 
-        # Check for existing lock
-        if self._check_lock():
-            logger.error("Another instance of bot-%s is already running", self.bot_id)
-            return 1
+        # Set Telegram command menu (idempotent, runs once per startup)
+        self._set_command_menu()
 
-        # Create lock file
+        # Boot-start monitor if a subscription was persisted
+        self._boot_monitor()
+
+        # Check for existing lock (prevents duplicate pollers for the same bot_id).
+        # Return 0 (not 1) so systemd Restart=on-failure does not restart-loop.
+        if self._check_lock():
+            logger.error("Another instance of bot-%s is already running — exiting cleanly", self.bot_id)
+            return 0
         self._create_lock()
 
         # Signal handlers
@@ -478,6 +505,7 @@ class BaseBot:
         # Start log streamer on first valid message (if branch has a name)
         if self._active_chat_id is None and chat_id:
             self._active_chat_id = chat_id
+            self._write_mirror_mapping()
             if self.branch_name is not None and self._log_streamer is None:
                 self._log_streamer = LogStreamer(self.bot_token, chat_id, self.branch_name)
                 self._log_streamer.start()
@@ -541,6 +569,11 @@ class BaseBot:
         """
         cmd_name, cmd_args = parsed
 
+        # /monitor command — system-wide log subscription
+        if cmd_name == "monitor":
+            self._handle_monitor_command(chat_id, cmd_args)
+            return True
+
         # /create command — multi-step bot creation
         if cmd_name == "create":
             self._handle_create_command(chat_id, cmd_args)
@@ -555,11 +588,16 @@ class BaseBot:
                 self.send_message(chat_id, "Nothing to cancel.")
             return True
 
-        # Compute uptime for /status
-        elapsed = time.time() - self.state["start_time"]
-        hours, remainder = divmod(int(elapsed), 3600)
-        minutes, seconds = divmod(remainder, 60)
-        uptime_str = f"{hours}h {minutes}m {seconds}s"
+        # Compute conversation uptime (resets on /new) and daemon uptime (since boot)
+        conv_elapsed = time.time() - self.state.get("conversation_start", self.state["start_time"])
+        conv_h, conv_rem = divmod(int(conv_elapsed), 3600)
+        conv_m, conv_s = divmod(conv_rem, 60)
+        uptime_str = f"{conv_h}h {conv_m}m {conv_s}s"
+
+        daemon_elapsed = time.time() - self.state["start_time"]
+        d_h, d_rem = divmod(int(daemon_elapsed), 3600)
+        d_m, d_s = divmod(d_rem, 60)
+        daemon_uptime_str = f"{d_h}h {d_m}m {d_s}s"
 
         # Merge custom commands from constructor and hook
         merged_commands = {**self.custom_commands, **self.get_custom_commands()}
@@ -572,6 +610,7 @@ class BaseBot:
                 uptime=uptime_str,
                 message_count=self.state.get("message_count"),
                 chat_id=chat_id,
+                daemon_uptime=daemon_uptime_str,
             )
             registry_text = self._build_registry_status()
             if registry_text:
@@ -596,8 +635,10 @@ class BaseBot:
                 action, response_text = result
                 if action == "new":
                     self._kill_tmux_session()
+                    self.state["message_count"] = 0
+                    self.state["conversation_start"] = time.time()
                     self.send_message(chat_id, response_text)
-                    logger.info("Handled /new command - session killed")
+                    logger.info("Handled /new command - session killed, counters reset")
             else:
                 self.send_message(chat_id, result)
                 logger.info("Handled /%s command", cmd_name)
@@ -634,8 +675,13 @@ class BaseBot:
 
         # Ensure tmux session
         if not self.ensure_tmux_session():
-            logger.error("Cannot process message - tmux session unavailable")
-            self.send_message(chat_id, "Failed to start Claude session. Check logs.")
+            logger.error("Cannot process message - no live session to mirror")
+            branch = self.branch_name or self.work_dir.name
+            self.send_message(
+                chat_id,
+                f"⚠️ No live Claude session found for branch '{branch}'.\n"
+                "Start a Claude session in the branch directory first.",
+            )
             return
 
         # Send processing indicator
@@ -725,8 +771,13 @@ class BaseBot:
 
         # Ensure tmux session
         if not self.ensure_tmux_session():
-            logger.error("Cannot process file - tmux session unavailable")
-            self.send_message(chat_id, "Failed to start Claude session. Check logs.")
+            logger.error("Cannot process file - no live session to mirror")
+            branch = self.branch_name or self.work_dir.name
+            self.send_message(
+                chat_id,
+                f"⚠️ No live Claude session found for branch '{branch}'.\n"
+                "Start a Claude session in the branch directory first.",
+            )
             if file_type == "text":
                 file_path.unlink(missing_ok=True)
             return
@@ -885,8 +936,10 @@ class BaseBot:
             self.send_message(
                 chat_id,
                 f"Branch @{branch_name} found at {branch_path}.\n\n"
-                "Now paste the BotFather token for the new bot.\n"
-                "(Get one from @BotFather -> /newbot)\n\n"
+                f"⚠️ BotFather automation unavailable: {telethon_reason}\n"
+                "Falling back to manual token flow.\n\n"
+                "Paste the BotFather token for the new bot.\n"
+                "(Get one from @BotFather → /newbot)\n\n"
                 "/cancel to abort.",
             )
             logger.info(
@@ -1207,16 +1260,40 @@ class BaseBot:
         """
         Ensure a tmux session is available for message injection.
 
-        In shared-session mode: attaches to an existing tmux session (e.g.,
-        the user's running Claude Code session). Falls back to own session if
-        the shared session is not found.
+        Resolution order:
+        1. Central presence pointer (.ai_central/PRESENCE.central.json)
+        2. Explicit shared_session from config
+        3. Already-running own tmux session (transitional)
 
-        In normal mode: creates telegram-{bot_id} session with Claude Code.
+        The bot NEVER spawns its own Claude brain — it is a thin relay that
+        follows the live session via the presence pointer (FPLAN-0289 P2).
 
         Returns:
             True if session is ready
         """
-        # Shared-session mode: attach to existing session if available
+        # Strategy 1: CC-native session discovery (DPLAN-0226)
+        cc_session = self._discover_cc_session()
+        if cc_session:
+            tmux_target = self._find_tmux_pane_by_cwd()
+            if tmux_target:
+                self.session_name = tmux_target
+                self._using_shared_session = True
+                self._active_session_id = cc_session.get("sessionId")
+                self._active_transcript_path = self._resolve_cc_transcript_path(cc_session)
+                logger.info(
+                    "CC-native discovery: session '%s' (PID %d) → tmux '%s'",
+                    cc_session.get("name", "?"),
+                    cc_session.get("pid", 0),
+                    tmux_target,
+                )
+                self._write_mirror_mapping()
+                return True
+            logger.warning(
+                "CC session found (PID %d) but no matching tmux pane",
+                cc_session.get("pid", 0),
+            )
+
+        # Strategy 2: explicit shared-session from config
         if self._shared_session_name:
             try:
                 result = subprocess.run(
@@ -1230,94 +1307,29 @@ class BaseBot:
                         "Shared session '%s' found — injecting into existing session",
                         self._shared_session_name,
                     )
+                    self._write_mirror_mapping()
                     return True
                 else:
-                    self._using_shared_session = False
-                    self.session_name = f"telegram-{self.bot_id}"
                     logger.warning(
-                        "Shared session '%s' not found — falling back to own session",
+                        "Shared session '%s' not found",
                         self._shared_session_name,
                     )
             except FileNotFoundError:
                 logger.warning("tmux not found while checking shared session '%s'", self._shared_session_name)
-                self._using_shared_session = False
-                self.session_name = f"telegram-{self.bot_id}"
 
+        # Strategy 3: already-running own tmux session (transitional — pre-existing sessions only)
         if self._tmux_session_exists():
             return True
 
-        # Validate work_dir exists — tmux silently falls back to HOME on bad paths
-        if not self.work_dir.is_dir():
-            logger.error("work_dir does not exist: %s — refusing to create tmux session", self.work_dir)
-            return False
-
-        logger.info("Creating tmux session '%s' at %s", self.session_name, self.work_dir)
-
-        try:
-            # env -u CLAUDECODE prevents "cannot run inside another Claude" error
-            env = os.environ.copy()
-            env.pop("CLAUDECODE", None)
-
-            subprocess.run(
-                [
-                    "tmux",
-                    "new-session",
-                    "-d",
-                    "-s",
-                    self.session_name,
-                    "-c",
-                    str(self.work_dir),
-                ],
-                check=True,
-                capture_output=True,
-                env=env,
-            )
-
-            # Set AIPASS_BOT_ID environment variable in the tmux session
-            subprocess.run(
-                [
-                    "tmux",
-                    "send-keys",
-                    "-t",
-                    self.session_name,
-                    f"export AIPASS_BOT_ID={self.bot_id}",
-                    "Enter",
-                ],
-                capture_output=True,
-            )
-            time.sleep(0.3)
-
-            # Launch Claude with session type so drone/hooks can identify this as a telegram session
-            claude_cmd = f"AIPASS_SESSION_TYPE=telegram {CLAUDE_BIN} --permission-mode bypassPermissions"
-            subprocess.run(
-                [
-                    "tmux",
-                    "send-keys",
-                    "-t",
-                    self.session_name,
-                    claude_cmd,
-                    "Enter",
-                ],
-                capture_output=True,
-            )
-
-            logger.info("tmux session created, waiting 5s for Claude to initialize...")
-            time.sleep(5)
-
-            # Hook: post-creation
-            self.on_session_create(self.session_name, self.work_dir)
-
-            return True
-
-        except subprocess.CalledProcessError as e:
-            logger.error(
-                "Failed to create tmux session: %s",
-                e.stderr.decode() if e.stderr else str(e),
-            )
-            return False
-        except FileNotFoundError:
-            logger.error("tmux not found - is it installed?")
-            return False
+        # PRESENCE GUARD: bot never spawns its own Claude brain (FPLAN-0289 P2).
+        # Legacy AIPASS_SESSION_TYPE=telegram own-session spawn RETIRED.
+        # The bot is a thin relay — it follows the presence pointer or an
+        # explicit shared_session. Start a Claude session in the branch first.
+        logger.error(
+            "No live session to mirror — presence pointer empty, no shared session. "
+            "Start a Claude session in the branch directory first."
+        )
+        return False
 
     def inject_message(self, text: str) -> bool:
         """
@@ -1427,7 +1439,11 @@ class BaseBot:
             "processing_message_id": processing_message_id,
             "timestamp": time.time(),
             "transcript_line_after": transcript_line_after,
+            "transcript_path": str(self._active_transcript_path) if self._active_transcript_path else None,
+            "session_id": self._active_session_id,
         }
+        if self._stream:
+            pending_data["streaming"] = True
 
         try:
             self.pending_file.write_text(
@@ -1452,39 +1468,403 @@ class BaseBot:
         except OSError as e:
             logger.warning("Failed to clean stale pending file: %s", e)
 
-    def _get_transcript_line_count(self) -> int:
-        """
-        Count lines in the Claude JSONL transcript for Layer 3 position tracking.
+    def _resolve_active_transcript(self) -> tuple[str | None, int]:
+        """Identify the ACTIVE Claude JSONL transcript and return its path and line count.
 
-        Returns:
-            Line count of the JSONL transcript, or 0 if unavailable
+        Prefers the CC-native transcript path when available (set by CC session
+        discovery in ensure_tmux_session). Falls back to PID-based fd scanning
+        and mtime heuristic.
         """
-        slug = str(self.work_dir).replace("/", "-")
-        # Look for transcript files matching the session pattern
+        # Strategy 0: CC-native transcript path (set by _discover_cc_session)
+        if self._active_transcript_path and self._active_transcript_path.exists():
+            return str(self._active_transcript_path), self._count_file_lines(self._active_transcript_path)
+
+        slug = str(self.work_dir).replace("\\", "-").replace("/", "-")
         projects_dir = Path.home() / ".claude" / "projects" / slug
         if not projects_dir.exists():
-            return 0
+            return None, 0
 
-        # Find the most recent JSONL transcript
-        jsonl_files = sorted(projects_dir.glob("*.jsonl"), key=lambda p: p.stat().st_mtime, reverse=True)
+        jsonl_files = list(projects_dir.glob("*.jsonl"))
         if not jsonl_files:
-            return 0
+            return None, 0
 
+        # Strategy 1: find the JSONL open by a child of the tmux pane
+        pane_pid = self._get_tmux_pane_pid()
+        if pane_pid:
+            target_names = {f.name for f in jsonl_files}
+            found = self._find_open_jsonl(pane_pid, projects_dir, target_names)
+            if found:
+                return str(found), self._count_file_lines(found)
+
+        # Strategy 2: most recently modified JSONL, but only if touched < 5 min ago
+        now = time.time()
+        recent = sorted(
+            ((f, f.stat().st_mtime) for f in jsonl_files),
+            key=lambda x: x[1],
+            reverse=True,
+        )
+        if recent and (now - recent[0][1]) < 300:
+            return str(recent[0][0]), self._count_file_lines(recent[0][0])
+
+        return None, 0
+
+    def _find_open_jsonl(self, pane_pid: int, projects_dir: Path, target_names: set[str]) -> Path | None:
+        """Scan /proc fd links for descendant PIDs to find an open JSONL in *projects_dir*."""
+        child_pids = self._get_descendant_pids(pane_pid)
+        for pid in child_pids:
+            match = self._scan_pid_fds(pid, projects_dir, target_names)
+            if match:
+                return match
+        return None
+
+    @staticmethod
+    def _scan_pid_fds(pid: int, projects_dir: Path, target_names: set[str]) -> Path | None:
+        """Check /proc/<pid>/fd/ for an open JSONL matching *target_names*."""
+        fd_dir = Path(f"/proc/{pid}/fd")
         try:
-            text = jsonl_files[0].read_text(encoding="utf-8").strip()
+            entries = list(fd_dir.iterdir())
+        except OSError as e:
+            logger.info("Cannot list fds for pid %d: %s", pid, e)
+            return None
+        for fd in entries:
+            try:
+                target = fd.resolve()
+            except OSError as e:
+                logger.info("Cannot resolve fd %s: %s", fd.name, e)
+                continue
+            if target.parent == projects_dir and target.name in target_names:
+                return target
+        return None
+
+    def _get_tmux_pane_pid(self) -> int | None:
+        """Get the shell PID of the first pane in the current tmux session."""
+        try:
+            result = subprocess.run(
+                ["tmux", "list-panes", "-t", self.session_name, "-F", "#{pane_pid}"],
+                capture_output=True,
+                text=True,
+                timeout=5,
+            )
+            if result.returncode == 0 and result.stdout.strip():
+                return int(result.stdout.strip().split("\n")[0])
+        except (subprocess.TimeoutExpired, OSError, ValueError) as e:
+            logger.info("Could not get tmux pane PID: %s", e)
+        return None
+
+    @staticmethod
+    def _get_descendant_pids(parent_pid: int) -> list[int]:
+        """Walk /proc to collect all descendant PIDs of *parent_pid*."""
+        children: dict[int, list[int]] = {}
+        try:
+            for entry in Path("/proc").iterdir():
+                if not entry.name.isdigit():
+                    continue
+                try:
+                    stat_text = (entry / "stat").read_text(encoding="utf-8")
+                    ppid = int(stat_text.split(") ")[1].split()[1])
+                    children.setdefault(ppid, []).append(int(entry.name))
+                except (OSError, IndexError, ValueError) as e:
+                    logger.info("Skipping /proc/%s/stat: %s", entry.name, e)
+                    continue
+        except OSError as e:
+            logger.info("Cannot scan /proc for descendant PIDs: %s", e)
+            return []
+        result: list[int] = []
+        queue = children.get(parent_pid, [])[:]
+        while queue:
+            pid = queue.pop()
+            result.append(pid)
+            queue.extend(children.get(pid, []))
+        return result
+
+    @staticmethod
+    def _count_file_lines(path: Path) -> int:
+        """Count newline-delimited lines in *path*."""
+        try:
+            text = path.read_text(encoding="utf-8").strip()
             return len(text.split("\n")) if text else 0
         except OSError as e:
             logger.warning("Could not read transcript for line count: %s", e)
             return 0
 
+    def _get_transcript_line_count(self) -> int:
+        """Count lines in the active JSONL transcript (compat shim)."""
+        _, count = self._resolve_active_transcript()
+        return count
+
+    # =============================================
+    # CC-NATIVE SESSION DISCOVERY (DPLAN-0226)
+    # =============================================
+
+    def _discover_cc_session(self) -> dict | None:
+        """Discover the active CC session for this bot's branch.
+
+        Enumerates ~/.claude/sessions/<pid>.json, filters by cwd matching
+        this bot's work_dir, confirms PID alive. Returns the latest session
+        (by startedAt) or None. CC keeps these current across /resume and
+        deletes on exit, so re-binding is automatic.
+        """
+        if not CC_SESSIONS_DIR.is_dir():
+            return None
+        target_cwd = str(self.work_dir.resolve())
+        best = None
+        for f in CC_SESSIONS_DIR.iterdir():
+            if not f.name.endswith(".json") or not f.stem.isdigit():
+                continue
+            try:
+                data = json.loads(f.read_text(encoding="utf-8"))
+            except (json.JSONDecodeError, OSError) as exc:
+                logger.info("Failed to read CC session file %s: %s", f, exc)
+                continue
+            session_cwd = data.get("cwd", "")
+            if not session_cwd:
+                continue
+            if str(Path(session_cwd).resolve()) != target_cwd:
+                continue
+            pid = data.get("pid")
+            if not pid or not self._is_pid_alive(pid):
+                continue
+            if best is None or data.get("startedAt", 0) > best.get("startedAt", 0):
+                best = data
+        return best
+
+    @staticmethod
+    def _is_pid_alive(pid: int) -> bool:
+        """Check if a process with the given PID exists."""
+        if pid <= 1:
+            return False
+        try:
+            os.kill(pid, 0)
+            return True
+        except ProcessLookupError:
+            logger.info("PID %d not found (dead)", pid)
+            return False
+        except PermissionError:
+            logger.info("PID %d exists but permission denied — treating as alive", pid)
+            return True
+        except OSError as exc:
+            logger.info("PID %d liveness check failed: %s — treating as dead", pid, exc)
+            return False
+
+    def _find_tmux_pane_by_cwd(self) -> str | None:
+        """Find a tmux session with a pane whose CWD matches this bot's work_dir."""
+        try:
+            result = subprocess.run(
+                ["tmux", "list-panes", "-a", "-F", "#{session_name}:#{pane_current_path}"],
+                capture_output=True,
+                text=True,
+                timeout=5,
+            )
+            if result.returncode != 0:
+                return None
+            target = str(self.work_dir.resolve())
+            for line in result.stdout.strip().split("\n"):
+                if ":" not in line:
+                    continue
+                session_name, pane_path = line.split(":", 1)
+                if str(Path(pane_path).resolve()) == target:
+                    return session_name
+        except (subprocess.TimeoutExpired, FileNotFoundError, OSError) as exc:
+            logger.info("tmux pane scan failed: %s", exc)
+        return None
+
+    @staticmethod
+    def _sanitize_path_for_cc(path_str: str) -> str:
+        """Sanitize a path for CC projects dir (every non-alphanumeric char becomes '-')."""
+        return re.sub(r"[^a-zA-Z0-9]", "-", path_str)
+
+    def _resolve_cc_transcript_path(self, session: dict) -> Path | None:
+        """Resolve the transcript JSONL path from a CC session entry."""
+        session_id = session.get("sessionId")
+        cwd = session.get("cwd", "")
+        if not session_id or not cwd:
+            return None
+        slug = self._sanitize_path_for_cc(cwd)
+        transcript = Path.home() / ".claude" / "projects" / slug / f"{session_id}.jsonl"
+        if transcript.exists():
+            return transcript
+        return None
+
+    @staticmethod
+    def _extract_assistant_text(entry: dict) -> str | None:
+        """Extract text content from a transcript entry if it's an assistant message."""
+        msg = entry.get("message", {})
+        if msg.get("role") != "assistant":
+            return None
+        content = msg.get("content", [])
+        if isinstance(content, str):
+            return content
+        if isinstance(content, list):
+            for block in content:
+                if isinstance(block, dict) and block.get("type") == "text":
+                    return block.get("text", "")
+        return None
+
+    def _read_transcript_tail(self, n_lines: int = 50) -> str | None:
+        """Read the latest assistant text response from the active transcript.
+
+        Scans the last n_lines of the transcript JSONL for the most recent
+        assistant message with text content.
+        """
+        path = self._active_transcript_path
+        if not path or not path.exists():
+            return None
+        try:
+            text = path.read_text(encoding="utf-8").strip()
+            if not text:
+                return None
+            lines = text.split("\n")
+            tail = lines[-n_lines:] if len(lines) > n_lines else lines
+            for line in reversed(tail):
+                try:
+                    entry = json.loads(line)
+                except json.JSONDecodeError:
+                    logger.info("Malformed JSONL line in transcript tail")
+                    continue
+                result = self._extract_assistant_text(entry)
+                if result is not None:
+                    return result
+        except OSError as exc:
+            logger.info("Failed to read transcript tail: %s", exc)
+        return None
+
+    # =============================================
+    # DORMANT: PRESENCE POINTER (DPLAN-0226)
+    # Discovery replaced by CC-native ~/.claude/sessions.
+    # Guard half (presence_gate) stays LIVE in @hooks.
+    # Kept per Patrick's directive — do not delete.
+    # =============================================
+
+    # def _find_presence_file(self) -> Path | None:
+    #     """Locate .ai_central/PRESENCE.central.json by walking up from work_dir."""
+    #     current = self.work_dir.resolve()
+    #     for _ in range(20):
+    #         candidate = current / ".ai_central" / "PRESENCE.central.json"
+    #         if candidate.exists():
+    #             return candidate
+    #         if current.parent == current:
+    #             break
+    #         current = current.parent
+    #     return None
+    #
+    # def _read_presence_pointer(self) -> dict | None:
+    #     """Read the central presence pointer for this bot's branch."""
+    #     presence_file = self._find_presence_file()
+    #     if presence_file is None:
+    #         return None
+    #     try:
+    #         data = json.loads(presence_file.read_text(encoding="utf-8"))
+    #     except (json.JSONDecodeError, OSError):
+    #         return None
+    #     branch = self.branch_name or self.work_dir.name
+    #     entry = data.get(branch)
+    #     if not entry:
+    #         return None
+    #     pid = entry.get("pid")
+    #     if pid is None:
+    #         return None
+    #     try:
+    #         os.kill(pid, 0)
+    #     except ProcessLookupError:
+    #         return None
+    #     except PermissionError:
+    #         pass
+    #     except OSError:
+    #         return None
+    #     return entry
+    #
+    # def _find_tmux_for_presence(self, entry: dict) -> str | None:
+    #     """Find the tmux session for a presence entry."""
+    #     handle = entry.get("attach_handle", "")
+    #     if handle:
+    #         try:
+    #             result = subprocess.run(
+    #                 ["tmux", "has-session", "-t", handle],
+    #                 capture_output=True,
+    #                 timeout=5,
+    #             )
+    #             if result.returncode == 0:
+    #                 return handle
+    #         except (FileNotFoundError, subprocess.TimeoutExpired, OSError):
+    #             pass
+    #     work_dir = entry.get("work_dir", "")
+    #     if not work_dir:
+    #         return None
+    #     try:
+    #         result = subprocess.run(
+    #             ["tmux", "list-panes", "-a", "-F",
+    #              "#{session_name}:#{pane_current_path}"],
+    #             capture_output=True, text=True, timeout=5,
+    #         )
+    #         if result.returncode != 0:
+    #             return None
+    #         target = str(Path(work_dir).resolve())
+    #         for line in result.stdout.strip().split("\n"):
+    #             if ":" not in line:
+    #                 continue
+    #             session_name, pane_path = line.split(":", 1)
+    #             if str(Path(pane_path).resolve()) == target:
+    #                 return session_name
+    #     except (subprocess.TimeoutExpired, FileNotFoundError, OSError):
+    #         pass
+    #     return None
+
+    def _write_mirror_mapping(self) -> None:
+        """Write persistent mirror mapping file per THE CONTRACT (TDPLAN-0009).
+
+        Written at first successful attach AND rewritten whenever the active
+        transcript changes (session restart).  @hooks reads this every turn
+        to find the chat_id and cursor for mirror delivery.
+        """
+        if not self._attach_only:
+            return
+
+        chat_id = self._active_chat_id or getattr(self, "_config_chat_id", None)
+        if chat_id is None:
+            return
+
+        transcript_path, line_count = self._resolve_active_transcript()
+
+        if self._mirror_mapping_written:
+            if transcript_path == self._last_transcript_path:
+                return
+            logger.info(
+                "Transcript changed (%s → %s) — rewriting mirror mapping",
+                self._last_transcript_path,
+                transcript_path,
+            )
+
+        mapping_dir = Path.home() / ".aipass" / "telegram_bots"
+        mapping_dir.mkdir(parents=True, exist_ok=True)
+        mapping_file = mapping_dir / f"bot-{self.bot_id}.json"
+
+        mapping = {
+            "chat_id": chat_id,
+            "bot_token": self.bot_token,
+            "session_name": self.session_name,
+            "work_dir": str(self.work_dir),
+            "mirror": True,
+            "transcript_line_after": line_count,
+        }
+
+        try:
+            mapping_file.write_text(json.dumps(mapping, indent=2), encoding="utf-8")
+            self._mirror_mapping_written = True
+            self._last_transcript_path = transcript_path
+            logger.info("Mirror mapping written: %s (cursor=%d)", mapping_file, line_count)
+        except OSError as e:
+            logger.error("Failed to write mirror mapping: %s", e)
+
     # =============================================
     # HEARTBEAT THREAD
     # =============================================
 
     def _start_heartbeat(self, chat_id: int, processing_msg_id: int) -> None:
         """
-        Start a background thread that updates the "Processing..." message
-        with elapsed time.
+        Start a background thread that updates the "Processing..." message.
+
+        In batch mode (default): edits with elapsed time every 30s.
+        In stream mode: tails transcript and edits with live content every 2s.
 
         Args:
             chat_id: Chat ID where the processing message was sent
@@ -1495,13 +1875,20 @@ class BaseBot:
 
         def _heartbeat_loop():
             start = time.time()
+
+            # Streaming mode (FPLAN-0297): live transcript tail
+            if self._stream and self._active_transcript_path:
+                self._streaming_loop(chat_id, processing_msg_id, start)
+                return
+
+            # Batch mode (default): elapsed-time updates
             while not self._heartbeat_stop.is_set():
                 self._heartbeat_stop.wait(HEARTBEAT_INTERVAL)
                 if self._heartbeat_stop.is_set():
                     break
 
-                # Only update if pending file still exists and tmux alive
-                if not self.pending_file.exists():
+                # Stop if response has been delivered or tmux died
+                if self._is_pending_delivered():
                     break
                 if not self._tmux_session_exists():
                     break
@@ -1520,6 +1907,17 @@ class BaseBot:
             self._heartbeat_thread.join(timeout=5)
         self._heartbeat_thread = None
 
+    def _is_pending_delivered(self) -> bool:
+        """Check if the pending file has been marked as delivered by @hooks."""
+        if not self.pending_file.exists():
+            return True
+        try:
+            data = json.loads(self.pending_file.read_text(encoding="utf-8"))
+            return bool(data.get("delivered"))
+        except (json.JSONDecodeError, OSError) as e:
+            logger.warning("Failed to read pending file %s: %s", self.pending_file, e)
+            return False
+
     @staticmethod
     def _format_elapsed(seconds: float) -> str:
         """
@@ -1537,6 +1935,183 @@ class BaseBot:
         minutes, secs = divmod(total, 60)
         return f"{minutes}m {secs}s"
 
+    # =============================================
+    # STREAMING EDIT-IN-PLACE (FPLAN-0297)
+    # =============================================
+
+    def _streaming_loop(self, chat_id: int, msg_id: int, start_time: float) -> None:
+        """Stream transcript content into the processing message via edit-in-place."""
+        path = self._active_transcript_path
+        try:
+            byte_offset = path.stat().st_size if path else 0
+        except OSError as exc:
+            logger.info("Cannot stat transcript for streaming: %s", exc)
+            byte_offset = 0
+
+        buffer = ""
+        last_sent = ""
+        current_msg_id = msg_id
+        retry_after_until = 0.0
+
+        while not self._heartbeat_stop.is_set():
+            self._heartbeat_stop.wait(STREAM_INTERVAL)
+            if self._heartbeat_stop.is_set():
+                break
+            if self._is_pending_delivered():
+                break
+            if not self._tmux_session_exists():
+                break
+
+            new_entries, byte_offset = self._tail_transcript_bytes(path, byte_offset)
+            new_text = self._format_stream_entries(new_entries)
+            if new_text:
+                buffer += new_text
+
+            if self._is_pending_delivered():
+                break
+
+            if not buffer:
+                elapsed = time.time() - start_time
+                placeholder = f"Processing... ({self._format_elapsed(elapsed)})"
+                now = time.time()
+                if placeholder != last_sent and now >= retry_after_until:
+                    ok, retry = self._stream_edit(chat_id, current_msg_id, placeholder)
+                    retry_after_until = now + retry if retry > 0 else retry_after_until
+                    last_sent = placeholder if ok else last_sent
+                continue
+
+            if buffer == last_sent:
+                continue
+
+            now = time.time()
+            if now < retry_after_until:
+                continue
+
+            if len(buffer) > TELEGRAM_CHAR_LIMIT:
+                break_at = buffer.rfind("\n", 0, TELEGRAM_CHAR_LIMIT)
+                if break_at < TELEGRAM_CHAR_LIMIT // 2:
+                    break_at = TELEGRAM_CHAR_LIMIT
+                final_chunk = buffer[:break_at].rstrip()
+                self._stream_edit(chat_id, current_msg_id, final_chunk)
+                buffer = buffer[break_at:].lstrip()
+                initial = buffer[:TELEGRAM_CHAR_LIMIT] or "..."
+                result = self.send_message(chat_id, initial)
+                if result:
+                    current_msg_id = result.get("message_id", current_msg_id)
+                last_sent = initial
+                continue
+
+            ok, retry = self._stream_edit(chat_id, current_msg_id, buffer)
+            if retry > 0:
+                retry_after_until = now + retry
+            if ok:
+                last_sent = buffer
+
+    def _tail_transcript_bytes(self, path: Path | None, byte_offset: int) -> tuple[list[dict], int]:
+        """Incrementally tail a JSONL transcript from byte_offset."""
+        if not path:
+            return [], byte_offset
+        try:
+            with open(path, "rb") as f:
+                f.seek(0, 2)
+                file_size = f.tell()
+                if file_size <= byte_offset:
+                    return [], byte_offset
+                f.seek(byte_offset)
+                new_bytes = f.read()
+        except OSError as exc:
+            logger.info("Cannot read transcript for streaming tail: %s", exc)
+            return [], byte_offset
+
+        last_newline = new_bytes.rfind(b"\n")
+        if last_newline == -1:
+            return [], byte_offset
+
+        complete = new_bytes[: last_newline + 1]
+        entries = []
+        for line_bytes in complete.split(b"\n"):
+            line_str = line_bytes.decode("utf-8", errors="replace").strip()
+            if not line_str:
+                continue
+            try:
+                entries.append(json.loads(line_str))
+            except json.JSONDecodeError:
+                logger.info("Malformed JSONL line in streaming tail")
+
+        return entries, byte_offset + len(complete)
+
+    @staticmethod
+    def _format_content_block(block: dict) -> str | None:
+        """Map a single transcript content block to plain-text display."""
+        if not isinstance(block, dict):
+            return None
+        btype = block.get("type", "")
+        if btype == "text":
+            text = block.get("text", "")
+            return text if text.strip() else None
+        if btype == "thinking":
+            return "Thinking..."
+        if btype == "tool_use":
+            return f"Running {block.get('name', 'tool')}..."
+        return None
+
+    @staticmethod
+    def _format_stream_entries(entries: list[dict]) -> str:
+        """Block-map transcript entries to plain-text streaming content."""
+        parts: list[str] = []
+        for entry in entries:
+            if entry.get("isSidechain"):
+                continue
+            msg = entry.get("message", {})
+            if msg.get("role") != "assistant":
+                continue
+            content = msg.get("content", [])
+            if isinstance(content, str):
+                if content.strip():
+                    parts.append(content)
+                continue
+            if not isinstance(content, list):
+                continue
+            for block in content:
+                mapped = BaseBot._format_content_block(block)
+                if mapped is not None:
+                    parts.append(mapped)
+        if not parts:
+            return ""
+        return "\n".join(parts) + "\n"
+
+    def _stream_edit(self, chat_id: int, message_id: int, text: str) -> tuple[bool, float]:
+        """Edit a message with 429/not-modified handling for streaming.
+
+        Returns (success, retry_after_seconds). retry_after > 0 means rate-limited.
+        """
+        url = f"https://api.telegram.org/bot{self.bot_token}/editMessageText"
+        payload = {"chat_id": chat_id, "message_id": message_id, "text": text}
+
+        try:
+            data = json.dumps(payload).encode("utf-8")
+            req = Request(url, data=data, headers={"Content-Type": "application/json"})
+            with urlopen(req, timeout=15) as resp:
+                result = json.loads(resp.read().decode("utf-8"))
+            return result.get("ok", False), 0.0
+        except HTTPError as e:
+            try:
+                body = json.loads(e.read().decode("utf-8"))
+            except Exception as parse_err:
+                logger.info("Cannot parse stream edit error body: %s", parse_err)
+                body = {}
+            if e.code == 429:
+                retry = body.get("parameters", {}).get("retry_after", 30)
+                logger.info("Stream edit 429 — backing off %ds", retry)
+                return False, float(retry)
+            if e.code == 400 and "not modified" in body.get("description", ""):
+                return True, 0.0
+            logger.warning("Stream edit HTTP %d: %s", e.code, body.get("description", ""))
+            return False, 0.0
+        except Exception as e:
+            logger.warning("Stream edit error: %s", e)
+            return False, 0.0
+
     # =============================================
     # OVERRIDABLE HOOKS
     # =============================================
@@ -1569,18 +2144,160 @@ class BaseBot:
         """
         return text
 
-    def on_session_create(self, session_name: str, work_dir: Path) -> None:
-        """
-        Hook: called after a new tmux session is created.
+    def _set_command_menu(self) -> None:
+        """Set the Telegram command menu via setMyCommands on startup."""
+        merged_commands = {**self.custom_commands, **self.get_custom_commands()}
+        commands = build_botfather_commands(custom_commands=merged_commands or None)
+        if self.bot_token:
+            ok = set_bot_commands(self.bot_token, commands)
+            if ok:
+                logger.info("Command menu set (%d commands)", len(commands))
+            else:
+                logger.warning("Failed to set command menu")
 
-        Override in subclasses to perform post-creation setup
-        (e.g., injecting "hi" to trigger startup protocol).
+    # =============================================
+    # /MONITOR — SYSTEM-WIDE LOG SUBSCRIPTION
+    # =============================================
 
-        Args:
-            session_name: The tmux session name that was created
-            work_dir: The working directory of the session
-        """
-        return
+    def _handle_monitor_command(self, chat_id: int, args: str) -> None:
+        """Route /monitor subcommands: on, all, off, status."""
+        subcmd = args.strip().lower().split()[0] if args.strip() else ""
+
+        if subcmd == "on":
+            self._monitor_subscribe(chat_id, mode="default")
+        elif subcmd == "all":
+            self._monitor_subscribe(chat_id, mode="all")
+        elif subcmd == "off":
+            self._monitor_unsubscribe(chat_id)
+        elif subcmd == "status":
+            self._monitor_status(chat_id)
+        else:
+            self.send_message(
+                chat_id,
+                "/monitor on \u2014 errors & warnings\n"
+                "/monitor all \u2014 everything (firehose)\n"
+                "/monitor off \u2014 unsubscribe\n"
+                "/monitor status \u2014 current state",
+            )
+
+    def _monitor_subscribe(self, chat_id: int, mode: str) -> None:
+        """Subscribe this chat to the system-wide log monitor."""
+        # Stop any existing monitor streamer
+        if self._monitor_streamer is not None:
+            self._monitor_streamer.stop()
+            self._monitor_streamer = None
+
+        # Persist subscription
+        if not self._save_monitor_subscription(chat_id, mode):
+            self.send_message(chat_id, "Failed to save monitor subscription.")
+            return
+
+        # Start streamer
+        self._monitor_streamer = LogStreamer(
+            self.bot_token,
+            chat_id,
+            branch_name="monitor",
+            system_wide=True,
+            level_filter=mode,
+        )
+        self._monitor_streamer.start()
+
+        mode_label = "errors & warnings" if mode == "default" else "all levels (firehose)"
+        self.send_message(
+            chat_id,
+            f"Monitor subscribed: {mode_label}\n\n/monitor off to unsubscribe\n/monitor all for firehose mode",
+        )
+        logger.info("Monitor subscribed: chat_id=%s, mode=%s", chat_id, mode)
+
+    def _monitor_unsubscribe(self, chat_id: int) -> None:
+        """Unsubscribe from the system-wide log monitor."""
+        if self._monitor_streamer is not None:
+            self._monitor_streamer.stop()
+            self._monitor_streamer = None
+
+        self._clear_monitor_subscription()
+        self.send_message(chat_id, "Monitor unsubscribed. No more log alerts.")
+        logger.info("Monitor unsubscribed: chat_id=%s", chat_id)
+
+    def _monitor_status(self, chat_id: int) -> None:
+        """Show current monitor subscription status."""
+        sub = self._load_monitor_subscription()
+        if not sub or not sub.get("chat_id"):
+            self.send_message(chat_id, "Monitor: not subscribed.\n\n/monitor on to start.")
+            return
+
+        sub_chat = sub["chat_id"]
+        mode = sub.get("mode", "default")
+        mode_label = "errors & warnings" if mode == "default" else "all levels (firehose)"
+        is_this_chat = "(this chat)" if sub_chat == chat_id else f"(chat {sub_chat})"
+        running = self._monitor_streamer is not None and self._monitor_streamer._running
+        state = "streaming" if running else "paused"
+
+        self.send_message(
+            chat_id,
+            f"Monitor: {state}\nMode: {mode_label}\nTarget: {is_this_chat}",
+        )
+
+    def _boot_monitor(self) -> None:
+        """Start the monitor streamer from persisted subscription on boot."""
+        sub = self._load_monitor_subscription()
+        if not sub or not sub.get("chat_id"):
+            return
+
+        chat_id = sub["chat_id"]
+        mode = sub.get("mode", "default")
+
+        self._monitor_streamer = LogStreamer(
+            self.bot_token,
+            chat_id,
+            branch_name="monitor",
+            system_wide=True,
+            level_filter=mode,
+        )
+        self._monitor_streamer.start()
+        logger.info("Boot-started monitor streamer (chat_id=%s, mode=%s)", chat_id, mode)
+
+    def _monitor_subscription_file(self) -> Path:
+        """Return path to the local monitor subscription file."""
+        return Path.home() / ".aipass" / "telegram_bots" / f".{self.bot_id}_monitor.json"
+
+    def _load_monitor_subscription(self) -> dict | None:
+        """Load monitor subscription from local state file."""
+        sub_file = self._monitor_subscription_file()
+        if not sub_file.exists():
+            return None
+        try:
+            data = json.loads(sub_file.read_text(encoding="utf-8"))
+            if isinstance(data, dict) and data.get("chat_id"):
+                return data
+            return None
+        except (json.JSONDecodeError, OSError) as e:
+            logger.warning("Failed to load monitor subscription: %s", e)
+            return None
+
+    def _save_monitor_subscription(self, chat_id: int, mode: str) -> bool:
+        """Persist monitor subscription to local state file."""
+        sub_file = self._monitor_subscription_file()
+        try:
+            sub_file.parent.mkdir(parents=True, exist_ok=True)
+            sub_file.write_text(
+                json.dumps({"chat_id": chat_id, "mode": mode}, indent=2),
+                encoding="utf-8",
+            )
+            return True
+        except OSError as e:
+            logger.error("Failed to save monitor subscription: %s", e)
+            return False
+
+    def _clear_monitor_subscription(self) -> bool:
+        """Clear persisted monitor subscription."""
+        sub_file = self._monitor_subscription_file()
+        try:
+            sub_file.unlink(missing_ok=True)
+            return True
+        except OSError as e:
+            logger.error("Failed to clear monitor subscription: %s", e)
+            return False
 
     def get_custom_commands(self) -> dict:
         """
@@ -1593,13 +2310,17 @@ class BaseBot:
             Dict of commands in telegram_standards format
         """
         return {
+            "monitor": {
+                "description": "Subscribe to system-wide log alerts — /monitor on, off, all, status",
+                "menu_text": "Log monitor",
+            },
             "create": {
-                "description": "Create a new branch bot: /create chat <branch>",
-                "menu_text": "Create branch bot",
+                "description": "Create a Telegram bot for a branch — e.g. /create chat devpulse",
+                "menu_text": "New branch bot",
             },
             "cancel": {
-                "description": "Cancel active /create flow",
-                "menu_text": "Cancel",
+                "description": "Cancel an in-progress /create",
+                "menu_text": "Cancel create",
             },
         }
 
@@ -1696,6 +2417,9 @@ class BaseBot:
 
     def _cleanup(self) -> None:
         """Clean up resources on exit."""
+        if self._monitor_streamer is not None:
+            self._monitor_streamer.stop()
+            self._monitor_streamer = None
         if self._log_streamer is not None:
             self._log_streamer.stop()
             self._log_streamer = None
@@ -1733,6 +2457,11 @@ class BaseBot:
 # CLI ENTRY POINT
 # =============================================
 
+_BOT_CLASSES = {
+    "scheduler": ".scheduler_bot:SchedulerBot",
+}
+
+
 if __name__ == "__main__":
     parser = argparse.ArgumentParser(description="AIPass Telegram Bot")
     parser.add_argument("--bot-id", required=True, help="Bot identifier")
@@ -1745,7 +2474,15 @@ if __name__ == "__main__":
         print(f"No config found for bot_id={args.bot_id}")
         sys.exit(1)
 
-    bot = BaseBot(
+    bot_cls = BaseBot
+    if args.bot_id in _BOT_CLASSES:
+        mod_name, cls_name = _BOT_CLASSES[args.bot_id].rsplit(":", 1)
+        import importlib
+
+        mod = importlib.import_module(mod_name, package=__package__)
+        bot_cls = getattr(mod, cls_name)
+
+    bot = bot_cls(
         bot_id=args.bot_id,
         bot_token=config["bot_token"],
         work_dir=Path(config.get("work_dir", str(Path.home()))),
@@ -1753,5 +2490,11 @@ if __name__ == "__main__":
         allowed_user_ids=config.get("allowed_user_ids", []),
         branch_name=config.get("branch_name"),
         shared_session=config.get("shared_session"),
+        attach_only=config.get("attach_only", False),
+        stream=config.get("stream", False),
     )
+
+    if config.get("chat_id"):
+        bot._config_chat_id = config["chat_id"]
+
     sys.exit(bot.run())
diff --git a/src/aipass/skills/.aipass/skills/telegram/apps/handlers/bot_factory.py b/src/aipass/skills/lib/telegram/apps/handlers/bot_factory.py
similarity index 71%
rename from src/aipass/skills/.aipass/skills/telegram/apps/handlers/bot_factory.py
rename to src/aipass/skills/lib/telegram/apps/handlers/bot_factory.py
index 4001b14a..cddfaa98 100644
--- a/src/aipass/skills/.aipass/skills/telegram/apps/handlers/bot_factory.py
+++ b/src/aipass/skills/lib/telegram/apps/handlers/bot_factory.py
@@ -3,7 +3,7 @@
 # Name: bot_factory.py - Bot creation and deletion factory
 # Date: 2026-06-15
 # Version: 1.0.0
-# Category: skills/catalog/telegram/apps/handlers
+# Category: skills/lib/telegram/apps/handlers
 #
 # CHANGELOG (Max 5 entries):
 #   - v1.0.0 (2026-06-15): Ported from Dev-Pass — rewired registry, logger, config, base_bot path
@@ -31,7 +31,9 @@ All HTTP calls use urllib (stdlib). No external dependencies.
 
 # Standard library
 import json
+import shutil
 import subprocess
+import sys
 from datetime import datetime, timezone
 from pathlib import Path
 from typing import Optional
@@ -45,6 +47,10 @@ from aipass.prax import logger
 from aipass.skills.apps.handlers.json import json_handler  # noqa: F401
 
 # Internal imports
+from aipass.api.apps.modules.secrets import set_secret as _api_set_secret
+
+from .telegram_standards import build_botfather_commands
+
 from .bot_registry import (
     deregister_bot,
     ensure_registry,
@@ -60,14 +66,9 @@ from .bot_registry import (
 TELEGRAM_API = "https://api.telegram.org/bot{token}"
 SYSTEMD_DIR = Path.home() / ".config" / "systemd" / "user"
 _BOT_CONFIG_DIR = Path.home() / ".aipass" / "telegram_bots"
+CLAUDE_BIN = str(Path.home() / ".local" / "bin" / "claude")
 
-# Default commands set on every new bot via BotFather
-DEFAULT_BOT_COMMANDS = [
-    {"command": "start", "description": "Start the bot"},
-    {"command": "help", "description": "Show available commands"},
-    {"command": "status", "description": "Show session status"},
-    {"command": "new", "description": "Start a fresh session"},
-]
+# Command menu built from telegram_standards (single source of truth)
 
 # =============================================
 # TELEGRAM API HELPERS
@@ -200,11 +201,34 @@ def set_bot_commands(bot_token: str, commands: list[dict]) -> bool:
 # =============================================
 
 
+def _install_service_unit() -> bool:
+    """Copy telegram-bot@.service into ~/.config/systemd/user/ and reload."""
+    UNIT_SRC = Path(__file__).resolve().parents[2] / "telegram-bot@.service"
+    UNIT_DST_DIR = Path.home() / ".config" / "systemd" / "user"
+    UNIT_DST = UNIT_DST_DIR / "telegram-bot@.service"
+
+    try:
+        UNIT_DST_DIR.mkdir(parents=True, exist_ok=True)
+        shutil.copy2(UNIT_SRC, UNIT_DST)
+        subprocess.run(
+            ["systemctl", "--user", "daemon-reload"],
+            capture_output=True,
+            text=True,
+            timeout=10,
+        )
+        logger.info("Installed service unit: %s", UNIT_DST)
+        return True
+    except OSError as e:
+        logger.warning("Failed to install service unit: %s", e)
+        return False
+
+
 def enable_service(bot_id: str) -> bool:
     """
     Enable the systemd user service for a bot (does not start it).
 
-    Runs: systemctl --user enable telegram-bot@{bot_id}
+    Installs the unit file if missing, then runs:
+    systemctl --user enable telegram-bot@{bot_id}
 
     Args:
         bot_id: Bot identifier used in the service template.
@@ -212,6 +236,7 @@ def enable_service(bot_id: str) -> bool:
     Returns:
         True if the service was enabled successfully, False otherwise.
     """
+    _install_service_unit()
     SERVICE_NAME = f"telegram-bot@{bot_id}"
     try:
         result = subprocess.run(
@@ -283,12 +308,11 @@ def start_bot_process(bot_id: str) -> bool:
     Returns:
         True if the process was launched successfully, False otherwise.
     """
-    BASE_BOT_PATH = Path(__file__).parent / "base_bot.py"
-    PYTHON = str(Path.home() / ".venv" / "bin" / "python3")
+    MODULE_PATH = "aipass.skills.lib.telegram.apps.handlers.base_bot"
 
     try:
         proc = subprocess.Popen(
-            [PYTHON, str(BASE_BOT_PATH), "--bot-id", bot_id],
+            [sys.executable, "-m", MODULE_PATH, "--bot-id", bot_id],
             start_new_session=True,
             stdout=subprocess.DEVNULL,
             stderr=subprocess.DEVNULL,
@@ -301,6 +325,84 @@ def start_bot_process(bot_id: str) -> bool:
         return False
 
 
+def launch_mirror_session(
+    bot_id: str,
+    work_dir: str,
+    session_name: str,
+) -> bool:
+    """Launch the canonical tmux mirror session with --dangerously-skip-permissions.
+
+    Creates a detached tmux session running Claude Code in autonomous mirror mode.
+    The session uses --dangerously-skip-permissions because a detached tmux session
+    has no operator to approve permission prompts — without it, the session hangs.
+
+    Args:
+        bot_id: Bot identifier (set as AIPASS_BOT_ID env var in the session).
+        work_dir: Working directory for the Claude session.
+        session_name: tmux session name (e.g. "telegram-api").
+
+    Returns:
+        True if the session was launched successfully.
+    """
+    import os
+
+    try:
+        result = subprocess.run(
+            ["tmux", "has-session", "-t", session_name],
+            capture_output=True,
+        )
+        if result.returncode == 0:
+            logger.info("Mirror session '%s' already running — skipping launch", session_name)
+            return True
+    except FileNotFoundError:
+        logger.error("tmux not found — cannot launch mirror session")
+        return False
+
+    env = os.environ.copy()
+    env.pop("CLAUDECODE", None)
+
+    try:
+        subprocess.run(
+            ["tmux", "new-session", "-d", "-s", session_name, "-c", work_dir],
+            check=True,
+            capture_output=True,
+            env=env,
+        )
+    except subprocess.CalledProcessError as e:
+        logger.error("Failed to create tmux session '%s': %s", session_name, e)
+        return False
+
+    subprocess.run(
+        [
+            "tmux",
+            "send-keys",
+            "-t",
+            session_name,
+            f"export AIPASS_BOT_ID={bot_id}",
+            "Enter",
+        ],
+        capture_output=True,
+    )
+
+    import time
+
+    time.sleep(0.3)
+
+    claude_cmd = f"AIPASS_SESSION_TYPE=interactive-mirror {CLAUDE_BIN} --dangerously-skip-permissions"
+    subprocess.run(
+        ["tmux", "send-keys", "-t", session_name, claude_cmd, "Enter"],
+        capture_output=True,
+    )
+
+    logger.info(
+        "Mirror session '%s' launched (bot_id=%s, work_dir=%s, skip-perms=true)",
+        session_name,
+        bot_id,
+        work_dir,
+    )
+    return True
+
+
 def stop_service(bot_id: str) -> bool:
     """
     Stop the systemd user service for a bot.
@@ -336,6 +438,41 @@ def stop_service(bot_id: str) -> bool:
         return False
 
 
+def start_service(bot_id: str) -> bool:
+    """
+    Start the systemd user service for a bot.
+
+    Runs: systemctl --user start telegram-bot@{bot_id}
+
+    Args:
+        bot_id: Bot identifier used in the service template.
+
+    Returns:
+        True if the service was started successfully, False otherwise.
+    """
+    SERVICE_NAME = f"telegram-bot@{bot_id}"
+    try:
+        result = subprocess.run(
+            ["systemctl", "--user", "start", SERVICE_NAME],
+            capture_output=True,
+            text=True,
+            timeout=10,
+        )
+        if result.returncode == 0:
+            logger.info("Started systemd service: %s", SERVICE_NAME)
+            return True
+
+        logger.warning("Failed to start service %s: %s", SERVICE_NAME, result.stderr.strip())
+        return False
+
+    except subprocess.TimeoutExpired:
+        logger.warning("Timeout starting service: %s", SERVICE_NAME)
+        return False
+    except OSError as e:
+        logger.warning("Error starting service %s: %s", SERVICE_NAME, e)
+        return False
+
+
 # =============================================
 # BOT LIFECYCLE
 # =============================================
@@ -348,6 +485,9 @@ def create_bot(
     work_dir: Optional[str] = None,
     bot_name: Optional[str] = None,
     allowed_user_ids: Optional[list[int]] = None,
+    shared_session: Optional[str] = None,
+    attach_only: bool = False,
+    chat_id: Optional[int] = None,
 ) -> Optional[dict]:
     """
     Create a new bot: validate, write config, register, setup systemd.
@@ -360,7 +500,8 @@ def create_bot(
     5. Register in bot registry
     6. Set BotFather commands via setMyCommands API
     7. Enable systemd service
-    8. Auto-start the bot process
+    7.5. Mirror mode: launch canonical tmux session with skip-perms
+    8. Auto-start the bot (systemd for mirror, Popen for standard)
 
     Args:
         bot_id: Unique identifier for this bot (e.g., "dev_central", "base").
@@ -369,6 +510,9 @@ def create_bot(
         work_dir: Working directory for Claude sessions. Defaults to home dir if None.
         bot_name: Human-readable bot name. Auto-generated if None.
         allowed_user_ids: List of Telegram user IDs allowed to use this bot.
+        shared_session: tmux session name for mirror mode (attach to existing session).
+        attach_only: When True, bot only attaches — never spawns its own session.
+        chat_id: Pre-configured Telegram chat ID for mirror mapping.
 
     Returns:
         Bot info dict on success, None on any failure.
@@ -416,11 +560,7 @@ def create_bot(
             )
             return None
 
-    # Step 4: Write per-bot config to local shadow file.
-    # This is intentional: create_bot writes here first, then the config is
-    # imported into @api (drone @api set-secret) as a separate step. At runtime,
-    # load_bot_config reads exclusively from @api — the local file is the
-    # create-then-import staging artifact, not a runtime config source.
+    # Step 4: Build config and persist to @api secrets store + local shadow.
     ensure_registry()
     _BOT_CONFIG_DIR.mkdir(parents=True, exist_ok=True)
 
@@ -435,17 +575,28 @@ def create_bot(
         "work_dir": RESOLVED_WORK_DIR,
         "allowed_user_ids": allowed_user_ids or [],
         "created_at": datetime.now(timezone.utc).isoformat(),
+        "shared_session": shared_session,
+        "attach_only": attach_only,
+        "chat_id": chat_id,
     }
 
+    # Step 4a: Write to @api secrets store (load_bot_config reads from here)
+    try:
+        _api_set_secret("telegram", bot_id, config_data, as_json=True)
+        logger.info("Persisted bot config to @api secrets: telegram/%s", bot_id)
+    except OSError as e:
+        logger.error("create_bot failed: could not persist config to @api for '%s': %s", bot_id, e)
+        return None
+
+    # Step 4b: Write local shadow file (staging artifact, not runtime source)
     try:
         CONFIG_PATH.write_text(
             json.dumps(config_data, indent=2),
             encoding="utf-8",
         )
-        logger.info("Wrote bot config: %s", CONFIG_PATH)
+        logger.info("Wrote bot config shadow: %s", CONFIG_PATH)
     except OSError as e:
-        logger.warning("Failed to write bot config: %s", e)
-        return None
+        logger.warning("Failed to write shadow config (non-fatal): %s", e)
 
     # Step 5: Register in bot registry
     registered = register_bot(
@@ -454,6 +605,7 @@ def create_bot(
         branch_name=branch_name,
         work_dir=RESOLVED_WORK_DIR,
         config_path=str(CONFIG_PATH),
+        bot_token_ref=f"@api:telegram/{bot_id}",
     )
     if not registered:
         CONFIG_PATH.unlink(missing_ok=True)
@@ -461,21 +613,35 @@ def create_bot(
         return None
 
     # Step 6: Set BotFather commands
-    set_bot_commands(bot_token, DEFAULT_BOT_COMMANDS)
+    set_bot_commands(bot_token, build_botfather_commands())
 
     # Step 7: Enable systemd service
     enable_service(bot_id)
 
-    # Step 8: Auto-start the bot process
-    started = start_bot_process(bot_id)
+    # Step 7.5: Mirror mode — launch canonical tmux session
+    mirror_launched = False
+    if shared_session and attach_only:
+        mirror_launched = launch_mirror_session(session_name=shared_session, bot_id=bot_id, work_dir=RESOLVED_WORK_DIR)
+        if not mirror_launched:
+            logger.warning(
+                "Mirror session launch failed for '%s' — bot may need manual session start",
+                bot_id,
+            )
+
+    # Step 8: Auto-start the bot poller
+    if shared_session and attach_only:
+        started = start_service(bot_id)
+    else:
+        started = start_bot_process(bot_id)
 
     logger.info(
-        "Bot created: %s (@%s, branch=%s, work_dir=%s, started=%s)",
+        "Bot created: %s (@%s, branch=%s, work_dir=%s, started=%s, mirror=%s)",
         bot_id,
         BOT_USERNAME,
         branch_name,
         RESOLVED_WORK_DIR,
         started,
+        mirror_launched,
     )
 
     return {
@@ -487,6 +653,9 @@ def create_bot(
         "config_path": str(CONFIG_PATH),
         "service_name": f"telegram-bot@{bot_id}",
         "auto_started": started,
+        "shared_session": shared_session,
+        "attach_only": attach_only,
+        "mirror_launched": mirror_launched,
     }
 
 
diff --git a/src/aipass/skills/.aipass/skills/telegram/apps/handlers/bot_operations.py b/src/aipass/skills/lib/telegram/apps/handlers/bot_operations.py
similarity index 87%
rename from src/aipass/skills/.aipass/skills/telegram/apps/handlers/bot_operations.py
rename to src/aipass/skills/lib/telegram/apps/handlers/bot_operations.py
index e35c544a..8edbf349 100644
--- a/src/aipass/skills/.aipass/skills/telegram/apps/handlers/bot_operations.py
+++ b/src/aipass/skills/lib/telegram/apps/handlers/bot_operations.py
@@ -1,17 +1,9 @@
 # =================== AIPass ====================
-# Name: bot_operations.py - Bot operation handlers for multi-bot module
-# Date: 2026-02-24
-# Version: 1.0.0
-# Category: api/handlers/telegram
-#
-# CHANGELOG (Max 5 entries):
-#   - v1.0.0 (2026-02-24): Initial - start, stop, status, list operations for multi-bot system
-#
-# CODE STANDARDS:
-#   - Pure functions with proper error handling (graceful - never raise)
-#   - No Prax imports (handler tier 3)
-#   - Stdlib only (subprocess for systemd)
-#   - Returns values for caller to log/display - no handler-level logging
+# Name: bot_operations.py
+# Description: Bot lifecycle operation handlers — start, stop, status, list
+# Version: 1.0.1
+# Created: 2026-02-24
+# Modified: 2026-06-29
 # =============================================
 
 """
@@ -32,6 +24,12 @@ All functions return values - the module layer handles logging and display.
 import subprocess
 from pathlib import Path
 
+# Logging
+from aipass.prax import logger
+
+# JSON handler (seedgo standard)
+from aipass.skills.apps.handlers.json import json_handler  # noqa: F401
+
 # Internal handler imports
 from .base_bot import BaseBot
 from .branch_plugin import BranchPlugin
@@ -57,6 +55,7 @@ def start_bot(bot_id: str) -> int | None:
     Returns:
         Bot exit code, or None if config loading failed.
     """
+    json_handler.log_operation("start_bot", {"bot_id": bot_id})
     config = load_bot_config(bot_id)
     if not config:
         return None
@@ -69,6 +68,9 @@ def start_bot(bot_id: str) -> int | None:
     bot_name = config.get("bot_name", f"AIPass {bot_id} Bot")
     allowed_user_ids = config.get("allowed_user_ids", [])
     branch_name = config.get("branch_name")
+    shared_session = config.get("shared_session")
+    attach_only = config.get("attach_only", False)
+    chat_id = config.get("chat_id")
 
     if branch_name:
         bot = BranchPlugin(
@@ -78,6 +80,8 @@ def start_bot(bot_id: str) -> int | None:
             work_dir=work_dir,
             bot_name=bot_name,
             allowed_user_ids=allowed_user_ids,
+            shared_session=shared_session,
+            attach_only=attach_only,
         )
     else:
         bot = BaseBot(
@@ -86,8 +90,13 @@ def start_bot(bot_id: str) -> int | None:
             work_dir=work_dir,
             bot_name=bot_name,
             allowed_user_ids=allowed_user_ids,
+            shared_session=shared_session,
+            attach_only=attach_only,
         )
 
+    if chat_id is not None:
+        bot._config_chat_id = chat_id
+
     return bot.run()
 
 
@@ -117,8 +126,10 @@ def stop_bot(bot_id: str) -> tuple[bool, str]:
         return False, f"Failed to stop {service_name}: {result.stderr.strip()}"
 
     except subprocess.TimeoutExpired:
+        logger.warning("Timeout stopping %s", service_name)
         return False, f"Timeout stopping {service_name}"
     except OSError as e:
+        logger.warning("Error stopping %s: %s", service_name, e)
         return False, f"Error stopping {service_name}: {e}"
 
 
diff --git a/src/aipass/skills/.aipass/skills/telegram/apps/handlers/bot_registry.py b/src/aipass/skills/lib/telegram/apps/handlers/bot_registry.py
similarity index 83%
rename from src/aipass/skills/.aipass/skills/telegram/apps/handlers/bot_registry.py
rename to src/aipass/skills/lib/telegram/apps/handlers/bot_registry.py
index 21cd4590..992cb16c 100644
--- a/src/aipass/skills/.aipass/skills/telegram/apps/handlers/bot_registry.py
+++ b/src/aipass/skills/lib/telegram/apps/handlers/bot_registry.py
@@ -1,5 +1,19 @@
+# =================== AIPass ====================
+# Name: bot_registry.py
+# Description: Telegram bot registry — JSON store with advisory file locking
+# Version: 1.0.0
+# Created: 2026-06-24
+# Modified: 2026-06-25
+# =============================================
+
+"""Telegram bot registry.
+
+Persists registered bots to a JSON file with advisory file locking so concurrent
+read-modify-write operations don't corrupt the store. Provides CRUD plus lookup
+helpers (by id, branch, work_dir).
+"""
+
 # Standard library
-import fcntl
 import json
 from datetime import datetime, timezone
 from pathlib import Path
@@ -8,6 +22,30 @@ from typing import Optional
 # Logging
 from aipass.prax import logger
 
+# fcntl is POSIX-only (Linux/macOS); unavailable on Windows. Guard the import and
+# skip advisory locking when absent. Matches the codebase convention (hooks/cadence,
+# daemon) — see seedgo windows_compat standard.
+try:
+    import fcntl
+except ImportError:
+    fcntl = None  # type: ignore[assignment]
+    logger.info("[TELEGRAM] bot_registry: fcntl unavailable (Windows) — skipping advisory locks")
+
+
+def _lock(f, *, exclusive: bool) -> None:
+    """Acquire an advisory lock on an open file; no-op without fcntl (Windows)."""
+    if fcntl is None:
+        return
+    fcntl.flock(f.fileno(), fcntl.LOCK_EX if exclusive else fcntl.LOCK_SH)
+
+
+def _unlock(f) -> None:
+    """Release an advisory lock; no-op when fcntl is unavailable (Windows)."""
+    if fcntl is None:
+        return
+    fcntl.flock(f.fileno(), fcntl.LOCK_UN)
+
+
 # =============================================
 # CONSTANTS
 # =============================================
@@ -53,11 +91,11 @@ def ensure_registry() -> None:
         if not REGISTRY_FILE.exists():
             data = _empty_registry()
             with open(REGISTRY_FILE, "w", encoding="utf-8") as f:
-                fcntl.flock(f.fileno(), fcntl.LOCK_EX)
+                _lock(f, exclusive=True)
                 try:
                     json.dump(data, f, indent=2)
                 finally:
-                    fcntl.flock(f.fileno(), fcntl.LOCK_UN)
+                    _unlock(f)
             logger.info("Created new bot registry at %s", REGISTRY_FILE)
     except OSError as e:
         logger.warning("Failed to ensure registry: %s", e)
@@ -80,11 +118,11 @@ def load_registry() -> dict:
 
     try:
         with open(REGISTRY_FILE, "r", encoding="utf-8") as f:
-            fcntl.flock(f.fileno(), fcntl.LOCK_SH)
+            _lock(f, exclusive=False)
             try:
                 data = json.load(f)
             finally:
-                fcntl.flock(f.fileno(), fcntl.LOCK_UN)
+                _unlock(f)
 
         if not isinstance(data, dict) or "bots" not in data:
             logger.warning("Registry file has unexpected structure, returning empty")
@@ -116,11 +154,11 @@ def save_registry(data: dict) -> bool:
         data["metadata"]["last_updated"] = _now_iso()
 
         with open(REGISTRY_FILE, "w", encoding="utf-8") as f:
-            fcntl.flock(f.fileno(), fcntl.LOCK_EX)
+            _lock(f, exclusive=True)
             try:
                 json.dump(data, f, indent=2)
             finally:
-                fcntl.flock(f.fileno(), fcntl.LOCK_UN)
+                _unlock(f)
 
         return True
 
@@ -325,7 +363,8 @@ def get_bot_by_work_dir(work_dir) -> Optional[dict]:
             try:
                 if str(Path(bot_dir).resolve()) == target:
                     return bot
-            except (ValueError, OSError):
+            except (ValueError, OSError) as e:
+                logger.warning("Skipping unresolvable bot work_dir %r: %s", bot_dir, e)
                 continue
 
     return None
diff --git a/src/aipass/skills/.aipass/skills/telegram/apps/handlers/botfather_client.py b/src/aipass/skills/lib/telegram/apps/handlers/botfather_client.py
similarity index 100%
rename from src/aipass/skills/.aipass/skills/telegram/apps/handlers/botfather_client.py
rename to src/aipass/skills/lib/telegram/apps/handlers/botfather_client.py
diff --git a/src/aipass/skills/.aipass/skills/telegram/apps/handlers/branch_plugin.py b/src/aipass/skills/lib/telegram/apps/handlers/branch_plugin.py
similarity index 77%
rename from src/aipass/skills/.aipass/skills/telegram/apps/handlers/branch_plugin.py
rename to src/aipass/skills/lib/telegram/apps/handlers/branch_plugin.py
index de84bdfe..40e65901 100644
--- a/src/aipass/skills/.aipass/skills/telegram/apps/handlers/branch_plugin.py
+++ b/src/aipass/skills/lib/telegram/apps/handlers/branch_plugin.py
@@ -1,14 +1,20 @@
+# =================== AIPass ====================
+# Name: branch_plugin.py
+# Description: Per-branch Telegram bot — hook overrides for message prefixing and response tagging
+# Version: 2.0.0
+# Created: 2026-02-24
+# Modified: 2026-06-29
+# =============================================
+
 # Standard library
 import argparse
 import sys
-import time
 from pathlib import Path
 
 # Sibling import
 from .base_bot import BaseBot
 
-# Logging
-from aipass.prax import logger
+from aipass.skills.apps.handlers.json import json_handler  # noqa: F401
 
 
 # =============================================
@@ -20,8 +26,8 @@ class BranchPlugin(BaseBot):
     """
     Per-branch Telegram bot that extends BaseBot with branch-specific behavior.
 
-    Overrides BaseBot hooks to prefix messages, tag responses, and trigger
-    the AIPass startup protocol when a new tmux session is created.
+    Overrides BaseBot hooks to prefix messages with sender attribution
+    and tag responses with the branch name.
     """
 
     def __init__(self, branch_name: str, **kwargs) -> None:
@@ -34,6 +40,7 @@ class BranchPlugin(BaseBot):
         """
         self.branch_name = branch_name
         super().__init__(**kwargs)
+        json_handler.log_operation("branch_plugin_init", {"branch_name": branch_name})
 
     # =============================================
     # HOOK OVERRIDES
@@ -64,24 +71,6 @@ class BranchPlugin(BaseBot):
         """
         return f"@{self.branch_name}\n{text}"
 
-    def on_session_create(self, session_name: str, work_dir: Path) -> None:
-        """
-        Inject "hi" after tmux session creation to trigger startup protocol.
-
-        Waits 2 seconds for Claude to fully initialize, then injects "hi"
-        which triggers the AIPass startup sequence (reading memories, etc.).
-
-        Args:
-            session_name: The tmux session name that was created
-            work_dir: The working directory of the session
-        """
-        logger.info(
-            "Branch session created for @%s, injecting startup greeting",
-            self.branch_name,
-        )
-        time.sleep(2)
-        self.inject_message("hi")
-
 
 # =============================================
 # CLI ENTRY POINT
diff --git a/src/aipass/skills/.aipass/skills/telegram/apps/handlers/config.py b/src/aipass/skills/lib/telegram/apps/handlers/config.py
similarity index 93%
rename from src/aipass/skills/.aipass/skills/telegram/apps/handlers/config.py
rename to src/aipass/skills/lib/telegram/apps/handlers/config.py
index af21e76d..22bd6135 100644
--- a/src/aipass/skills/.aipass/skills/telegram/apps/handlers/config.py
+++ b/src/aipass/skills/lib/telegram/apps/handlers/config.py
@@ -1,5 +1,5 @@
 # Standard library
-from pathlib import Path
+from pathlib import PurePosixPath, PureWindowsPath
 from typing import Optional, List
 
 # Logging
@@ -208,8 +208,11 @@ def validate_bot_config(config: object) -> tuple[bool, str]:
         return False, "bot_token must be a string in format 'id:hash'"
 
     if "work_dir" in config and config["work_dir"] is not None:
-        work_dir = Path(config["work_dir"])
-        if not work_dir.is_absolute():
+        # work_dir is a deployment-target (Linux) path. Test absoluteness under
+        # POSIX *and* Windows semantics so validation is platform-independent —
+        # a bare host Path().is_absolute() would reject "/home/..." on Windows.
+        work_dir = str(config["work_dir"])
+        if not (PurePosixPath(work_dir).is_absolute() or PureWindowsPath(work_dir).is_absolute()):
             return False, "work_dir must be an absolute path"
 
     if "allowed_user_ids" in config:
diff --git a/src/aipass/skills/.aipass/skills/telegram/apps/handlers/file_handler.py b/src/aipass/skills/lib/telegram/apps/handlers/file_handler.py
similarity index 100%
rename from src/aipass/skills/.aipass/skills/telegram/apps/handlers/file_handler.py
rename to src/aipass/skills/lib/telegram/apps/handlers/file_handler.py
diff --git a/src/aipass/skills/.aipass/skills/telegram/apps/handlers/log_streamer.py b/src/aipass/skills/lib/telegram/apps/handlers/log_streamer.py
similarity index 85%
rename from src/aipass/skills/.aipass/skills/telegram/apps/handlers/log_streamer.py
rename to src/aipass/skills/lib/telegram/apps/handlers/log_streamer.py
index 08dbd87f..c5fd5779 100644
--- a/src/aipass/skills/.aipass/skills/telegram/apps/handlers/log_streamer.py
+++ b/src/aipass/skills/lib/telegram/apps/handlers/log_streamer.py
@@ -37,23 +37,55 @@ from aipass.skills.apps.handlers.json import json_handler
 # CONSTANTS
 # =============================================
 
-SYSTEM_LOGS_DIR = Path.home() / "system_logs"
 BATCH_INTERVAL = 5.0
 TELEGRAM_MAX_LENGTH = 4000
 
 
+def _get_system_logs_dir():
+    """Resolve system_logs dir, honoring AIPASS_TEST_LOG_DIR."""
+    import os
+
+    test_dir = os.environ.get("AIPASS_TEST_LOG_DIR")
+    if test_dir:
+        p = Path(test_dir) / "system"
+        p.mkdir(parents=True, exist_ok=True)
+        return p
+    here = Path(__file__).resolve()
+    for parent in here.parents:
+        if (parent / "pyproject.toml").exists():
+            d = parent / "system_logs"
+            d.mkdir(parents=True, exist_ok=True)
+            return d
+    return Path.home() / "system_logs"
+
+
+SYSTEM_LOGS_DIR = _get_system_logs_dir()
+
+
 # =============================================
 # LOG STREAMER
 # =============================================
 
 
+_LEVEL_MARKERS = ("| WARNING |", "| ERROR |", "| CRITICAL |")
+
+
 class LogStreamer:
     """Stream system log lines for a branch to Telegram via batched sends."""
 
-    def __init__(self, bot_token: str, chat_id: int, branch_name: str) -> None:
+    def __init__(
+        self,
+        bot_token: str,
+        chat_id: int,
+        branch_name: str,
+        system_wide: bool = False,
+        level_filter: str = "all",
+    ) -> None:
         self.bot_token = bot_token
         self.chat_id = chat_id
         self.branch_name = branch_name
+        self._system_wide = system_wide
+        self._level_filter = level_filter
 
         self._running = False
         self._stop_event = threading.Event()
@@ -68,11 +100,19 @@ class LogStreamer:
     # -----------------------------------------
 
     def _get_log_files(self) -> List[Path]:
-        """Find all log files matching this branch's pattern."""
+        """Find log files: all *.log when system_wide, else branch-specific."""
         if not SYSTEM_LOGS_DIR.exists():
             return []
+        if self._system_wide:
+            return sorted(SYSTEM_LOGS_DIR.glob("*.log"))
         return sorted(SYSTEM_LOGS_DIR.glob(f"{self.branch_name}_*.log"))
 
+    def _filter_lines(self, lines: List[str]) -> List[str]:
+        """Apply level filter: default keeps WARNING/ERROR/CRITICAL, all passes everything."""
+        if self._level_filter == "all":
+            return lines
+        return [ln for ln in lines if any(m in ln for m in _LEVEL_MARKERS)]
+
     def _init_positions(self) -> None:
         """Set initial positions to end of file so we only tail new lines."""
         for log_file in self._get_log_files():
@@ -201,6 +241,7 @@ class LogStreamer:
         while self._running:
             try:
                 new_lines = self._read_new_lines()
+                new_lines = self._filter_lines(new_lines)
                 if new_lines:
                     logger.info("Found %d new log lines, sending to Telegram", len(new_lines))
                     self._send_batched(new_lines)
diff --git a/src/aipass/skills/.aipass/skills/telegram/apps/handlers/notifier.py b/src/aipass/skills/lib/telegram/apps/handlers/notifier.py
similarity index 100%
rename from src/aipass/skills/.aipass/skills/telegram/apps/handlers/notifier.py
rename to src/aipass/skills/lib/telegram/apps/handlers/notifier.py
diff --git a/src/aipass/skills/.aipass/skills/telegram/apps/handlers/response_router.py b/src/aipass/skills/lib/telegram/apps/handlers/response_router.py
similarity index 100%
rename from src/aipass/skills/.aipass/skills/telegram/apps/handlers/response_router.py
rename to src/aipass/skills/lib/telegram/apps/handlers/response_router.py
diff --git a/src/aipass/skills/lib/telegram/apps/handlers/scheduler_bot.py b/src/aipass/skills/lib/telegram/apps/handlers/scheduler_bot.py
new file mode 100644
index 00000000..2bad4a45
--- /dev/null
+++ b/src/aipass/skills/lib/telegram/apps/handlers/scheduler_bot.py
@@ -0,0 +1,204 @@
+# =================== AIPass ====================
+# Name: scheduler_bot.py
+# Description: Dedicated Telegram bot for the daemon's job queue — announce/query only
+# Version: 1.0.0
+# Created: 2026-06-25
+# Modified: 2026-06-25
+# =============================================
+
+"""
+SchedulerBot — a BaseBot subclass for the AIPass Scheduler.
+
+Pure announce/query bot: serves /queue, posts an hourly digest, receives
+lifecycle pings from @daemon. Free-text messages do NOT spin up tmux/Claude.
+"""
+
+import json
+import subprocess
+import threading
+from typing import Optional
+
+from aipass.prax import logger
+from aipass.skills.apps.handlers.json import json_handler
+
+from .base_bot import BaseBot
+
+
+DIGEST_INTERVAL = 3600.0
+QUEUE_CMD = ["drone", "@daemon", "queue", "--json"]
+
+
+class SchedulerBot(BaseBot):
+    """Dedicated scheduler bot — no tmux/Claude, just /queue and hourly digest."""
+
+    def __init__(self, **kwargs) -> None:
+        super().__init__(**kwargs)
+        self._digest_thread: Optional[threading.Thread] = None
+        self._digest_stop = threading.Event()
+        self._scheduler_chat_id: Optional[int] = None
+
+    def handle_message(self, chat_id: int, text: str, message: dict) -> None:
+        """Reject free-text — this bot only serves commands (no tmux/Claude spawn)."""
+        self.send_message(
+            chat_id,
+            "I'm the scheduler bot — I only handle commands.\nTry /queue or /help",
+        )
+
+    def handle_file(self, chat_id: int, message: dict) -> None:
+        """Reject files — this bot only serves commands."""
+        self.send_message(chat_id, "I don't process files. Try /queue or /help")
+
+    def _dispatch_command(self, chat_id: int, parsed: tuple) -> bool:
+        cmd_name, cmd_args = parsed
+        if cmd_name == "queue":
+            self._handle_queue_command(chat_id)
+            return True
+        return super()._dispatch_command(chat_id, parsed)
+
+    def get_custom_commands(self) -> dict:
+        """Add /queue to the slash-menu alongside the inherited commands."""
+        cmds = super().get_custom_commands()
+        cmds["queue"] = {
+            "description": "Show all scheduled daemon jobs — next fire, status, type",
+            "menu_text": "Job queue",
+        }
+        return cmds
+
+    def _handle_queue_command(self, chat_id: int) -> None:
+        """Fetch queue from daemon and send formatted message."""
+        json_handler.log_operation("queue_requested", {"chat_id": chat_id})
+        queue_data = self._fetch_queue()
+        if queue_data is None:
+            self.send_message(chat_id, "Failed to fetch queue from daemon.")
+            return
+
+        text = self._format_queue(queue_data)
+        for chunk in self.chunk_text(text):
+            self.send_message(chat_id, chunk)
+
+    def _fetch_queue(self) -> Optional[dict]:
+        """Run drone @daemon queue --json and parse the result."""
+        try:
+            result = subprocess.run(
+                QUEUE_CMD,
+                capture_output=True,
+                text=True,
+                timeout=15,
+            )
+            if result.returncode != 0:
+                logger.warning("queue --json failed (rc=%d): %s", result.returncode, result.stderr)
+                return None
+            decoder = json.JSONDecoder(strict=False)
+            return decoder.decode(result.stdout)
+        except (subprocess.TimeoutExpired, json.JSONDecodeError, OSError) as e:
+            logger.warning("Failed to fetch queue: %s", e)
+            return None
+
+    @staticmethod
+    def _format_queue(data: dict) -> str:
+        """Format queue JSON into a readable Telegram message."""
+        jobs = data.get("jobs", [])
+        count = data.get("count", len(jobs))
+        generated = data.get("generated_at", "unknown")
+
+        if not jobs:
+            return f"No scheduled jobs.\n\nGenerated: {generated}"
+
+        lines = [f"Scheduled Jobs ({count})\n"]
+        for job in jobs:
+            owner = job.get("owner", "?")
+            job_id = job.get("id", "?")
+            enabled = job.get("enabled", False)
+            jtype = job.get("type", "?")
+            schedule = job.get("schedule_human", "?")
+            next_run = job.get("next_run") or "—"
+            last_status = job.get("last_status") or "never run"
+            last_error = job.get("last_error")
+            prompt = job.get("prompt_preview", "")
+
+            status_icon = {
+                "success": "✅",
+                "failed": "❌",
+                "dispatched": "\U0001f535",
+            }.get(last_status, "⚪")
+            enabled_tag = "" if enabled else " [disabled]"
+
+            lines.append(f"{status_icon} {owner}/{job_id}{enabled_tag}")
+            lines.append(f"  Type: {jtype} ({schedule})")
+            lines.append(f"  Next: {next_run}")
+            lines.append(f"  Last: {last_status}")
+            if last_error:
+                lines.append(f"  Error: {last_error}")
+            if prompt:
+                lines.append(f"  Prompt: {prompt[:80]}...")
+            lines.append("")
+
+        lines.append(f"Generated: {generated}")
+        return "\n".join(lines)
+
+    # =============================================
+    # HOURLY DIGEST
+    # =============================================
+
+    def start_digest(self, chat_id: int) -> None:
+        """Start the hourly digest thread."""
+        if self._digest_thread is not None and self._digest_thread.is_alive():
+            return
+        self._scheduler_chat_id = chat_id
+        self._digest_stop.clear()
+        self._digest_thread = threading.Thread(
+            target=self._digest_loop,
+            name="scheduler-digest",
+            daemon=True,
+        )
+        self._digest_thread.start()
+        logger.info("Digest thread started (chat_id=%s)", chat_id)
+
+    def stop_digest(self) -> None:
+        """Stop the hourly digest thread."""
+        self._digest_stop.set()
+        if self._digest_thread is not None:
+            self._digest_thread.join(timeout=5)
+            self._digest_thread = None
+        logger.info("Digest thread stopped")
+
+    def _digest_loop(self) -> None:
+        """Post a queue digest every hour."""
+        while not self._digest_stop.is_set():
+            self._digest_stop.wait(DIGEST_INTERVAL)
+            if self._digest_stop.is_set():
+                break
+            self._post_digest()
+
+    def _post_digest(self) -> None:
+        """Fetch queue and post digest to the scheduler chat."""
+        if self._scheduler_chat_id is None:
+            return
+        queue_data = self._fetch_queue()
+        if queue_data is None:
+            logger.warning("Digest skipped: failed to fetch queue")
+            return
+
+        text = f"Hourly Queue Digest\n{'=' * 20}\n\n{self._format_queue(queue_data)}"
+        for chunk in self.chunk_text(text):
+            self.send_message(self._scheduler_chat_id, chunk)
+        logger.info("Hourly digest posted")
+
+    # =============================================
+    # LIFECYCLE
+    # =============================================
+
+    def run(self) -> int:
+        """Run the bot: start the hourly digest, then delegate to the parent poll loop.
+
+        BaseBot.run() owns the full lifecycle (verify, command menu, lock, signal
+        handlers, offset tracking, poll loop, cleanup). We only wrap it to start the
+        digest thread before the blocking loop and stop it on exit.
+        """
+        chat_id = getattr(self, "_config_chat_id", None)
+        if chat_id:
+            self.start_digest(int(chat_id))
+        try:
+            return super().run()
+        finally:
+            self.stop_digest()
diff --git a/src/aipass/skills/.aipass/skills/telegram/apps/handlers/telegram_standards.py b/src/aipass/skills/lib/telegram/apps/handlers/telegram_standards.py
similarity index 83%
rename from src/aipass/skills/.aipass/skills/telegram/apps/handlers/telegram_standards.py
rename to src/aipass/skills/lib/telegram/apps/handlers/telegram_standards.py
index 76727af1..a470f27c 100644
--- a/src/aipass/skills/.aipass/skills/telegram/apps/handlers/telegram_standards.py
+++ b/src/aipass/skills/lib/telegram/apps/handlers/telegram_standards.py
@@ -1,6 +1,29 @@
+# =================== AIPass ====================
+# Name: telegram_standards.py
+# Description: Standard command registry, response builders, and helpers for Telegram bots
+# Version: 1.0.0
+# Created: 2026-02-24
+# Modified: 2026-06-29
+# =============================================
+
+"""
+Telegram Standards — shared command registry and response builders.
+
+Provides the canonical STANDARD_COMMANDS dict, text builder functions for
+/start, /help, /status, and /new responses, the BotFather setMyCommands
+payload builder, and the parse_command / handle_standard_command dispatcher
+used by BaseBot and all subclasses.
+
+All functions are pure (no side effects) except _tmux_session_exists which
+calls subprocess to check tmux state.
+"""
+
 import subprocess
 from typing import Optional
 
+from aipass.skills.apps.handlers.json import json_handler  # noqa: F401
+from aipass.prax import logger
+
 
 # =============================================
 # STANDARD COMMAND REGISTRY
@@ -8,19 +31,19 @@ from typing import Optional
 
 STANDARD_COMMANDS: dict[str, dict[str, str]] = {
     "start": {
-        "description": "Welcome message and command list",
-        "menu_text": "Start / welcome message",
+        "description": "Welcome — what this bot is and how to use it",
+        "menu_text": "What this bot does",
     },
     "help": {
-        "description": "Show available commands",
-        "menu_text": "Show help",
+        "description": "Show every command and what it does",
+        "menu_text": "List commands",
     },
     "new": {
-        "description": "Kill current session and start fresh (clean Claude context)",
+        "description": "Start a fresh conversation (clears Claude's current context)",
         "menu_text": "Fresh session",
     },
     "status": {
-        "description": "Show session info (branch, uptime, session state)",
+        "description": "Show the branch, uptime, and whether a session is active",
         "menu_text": "Session status",
     },
 }
@@ -34,7 +57,7 @@ PROCESSING_MSG = "Processing..."
 
 ERROR_TEMPLATE = "Something went wrong: {error}"
 
-HELP_FOOTER = "\nSend any message to chat with Claude."
+HELP_FOOTER = "\nJust send any message to talk to me — or use a command above."
 
 # Internal templates (used by builder functions)
 _WELCOME_HEADER = "Hello! I'm {bot_name}."
@@ -91,7 +114,7 @@ def build_help_text(
         standard_commands = STANDARD_COMMANDS
 
     parts: list[str] = [
-        "Commands:",
+        "Available commands:",
         _format_command_list(standard_commands, custom_commands),
         HELP_FOOTER,
     ]
@@ -123,7 +146,7 @@ def build_welcome_text(
         _WELCOME_HEADER.format(bot_name=bot_name),
         _WELCOME_BRANCH.format(branch_name=branch_name),
         "",
-        "Commands:",
+        "Available commands:",
         _format_command_list(standard_commands, custom_commands),
         HELP_FOOTER,
     ]
@@ -136,6 +159,7 @@ def build_status_text(
     uptime: Optional[str] = None,
     message_count: Optional[int] = None,
     chat_id: Optional[str | int] = None,
+    daemon_uptime: Optional[str] = None,
 ) -> str:
     """
     Build the /status response.
@@ -146,9 +170,10 @@ def build_status_text(
     Args:
         session_name: tmux session name (e.g., "telegram-assistant").
         branch_name: Branch name (e.g., "assistant").
-        uptime: Optional human-readable uptime string.
-        message_count: Optional count of messages processed.
+        uptime: Optional conversation uptime (resets on /new).
+        message_count: Optional count of messages in current conversation.
         chat_id: Optional Telegram chat ID to display.
+        daemon_uptime: Optional daemon process uptime (since boot).
 
     Returns:
         Formatted status text string.
@@ -165,6 +190,8 @@ def build_status_text(
         lines.append(f"Uptime: {uptime}")
     if message_count is not None:
         lines.append(f"Messages: {message_count}")
+    if daemon_uptime:
+        lines.append(f"Daemon up: {daemon_uptime}")
 
     return "\n".join(lines)
 
@@ -279,6 +306,8 @@ def handle_standard_command(
         - tuple[str, str]: ("new", response_text) for /new command
         - None: Command is not a standard command
     """
+    json_handler.log_operation("standard_command", {"command": command, "branch": branch_name})
+
     if command == "start":
         return build_welcome_text(
             bot_name=bot_name,
@@ -327,5 +356,5 @@ def _tmux_session_exists(session_name: str) -> bool:
         )
         return result.returncode == 0
     except FileNotFoundError:
-        # tmux not installed
+        logger.warning("tmux not found while checking session '%s'", session_name)
         return False
diff --git a/src/aipass/skills/.aipass/skills/telegram/apps/handlers/tmux_manager.py b/src/aipass/skills/lib/telegram/apps/handlers/tmux_manager.py
similarity index 100%
rename from src/aipass/skills/.aipass/skills/telegram/apps/handlers/tmux_manager.py
rename to src/aipass/skills/lib/telegram/apps/handlers/tmux_manager.py
diff --git a/src/aipass/skills/.aipass/skills/telegram/apps/modules/__init__.py b/src/aipass/skills/lib/telegram/apps/modules/__init__.py
similarity index 87%
rename from src/aipass/skills/.aipass/skills/telegram/apps/modules/__init__.py
rename to src/aipass/skills/lib/telegram/apps/modules/__init__.py
index 8c07b893..ab029ba0 100644
--- a/src/aipass/skills/.aipass/skills/telegram/apps/modules/__init__.py
+++ b/src/aipass/skills/lib/telegram/apps/modules/__init__.py
@@ -3,7 +3,7 @@
 # Name: __init__.py - telegram modules package
 # Date: 2026-03-07
 # Version: 1.0.0
-# Category: skills/catalog/telegram/apps/modules
+# Category: skills/lib/telegram/apps/modules
 #
 # CHANGELOG (Max 5 entries):
 #   - v1.0.0 (2026-03-07): Initial scaffold
diff --git a/src/aipass/skills/.aipass/skills/telegram/handler.py b/src/aipass/skills/lib/telegram/handler.py
similarity index 100%
rename from src/aipass/skills/.aipass/skills/telegram/handler.py
rename to src/aipass/skills/lib/telegram/handler.py
diff --git a/src/aipass/skills/.aipass/skills/telegram/telegram-bot@.service b/src/aipass/skills/lib/telegram/telegram-bot@.service
similarity index 75%
rename from src/aipass/skills/.aipass/skills/telegram/telegram-bot@.service
rename to src/aipass/skills/lib/telegram/telegram-bot@.service
index a81f5213..8fa27af4 100644
--- a/src/aipass/skills/.aipass/skills/telegram/telegram-bot@.service
+++ b/src/aipass/skills/lib/telegram/telegram-bot@.service
@@ -19,14 +19,14 @@ Wants=network-online.target
 
 [Service]
 Type=simple
-ExecStart=%h/.venv/bin/python3 %h/Projects/AIPass/src/aipass/skills/.aipass/skills/telegram/apps/handlers/base_bot.py --bot-id %i
+ExecStart=%h/Projects/AIPass/.venv/bin/python3 -m aipass.skills.lib.telegram.apps.handlers.base_bot --bot-id %i
 WorkingDirectory=%h/Projects/AIPass
 Environment=AIPASS_BOT_ID=%i
 Environment=AIPASS_SESSION_TYPE=telegram
 Restart=on-failure
 RestartSec=10
-StandardOutput=append:%h/system_logs/telegram-bot-%i.log
-StandardError=append:%h/system_logs/telegram-bot-%i.log
+StandardOutput=append:%h/Projects/AIPass/system_logs/telegram-bot-%i.log
+StandardError=append:%h/Projects/AIPass/system_logs/telegram-bot-%i.log
 
 [Install]
 WantedBy=default.target
diff --git a/src/aipass/skills/.aipass/skills/telegram/telethon_auth.py b/src/aipass/skills/lib/telegram/telethon_auth.py
similarity index 100%
rename from src/aipass/skills/.aipass/skills/telegram/telethon_auth.py
rename to src/aipass/skills/lib/telegram/telethon_auth.py
diff --git a/src/aipass/spawn/templates/builder/apps/plugins/__init__.py b/src/aipass/skills/lib/telegram/tests/__init__.py
similarity index 100%
rename from src/aipass/spawn/templates/builder/apps/plugins/__init__.py
rename to src/aipass/skills/lib/telegram/tests/__init__.py
diff --git a/src/aipass/skills/.aipass/skills/telegram/tests/conftest.py b/src/aipass/skills/lib/telegram/tests/conftest.py
similarity index 62%
rename from src/aipass/skills/.aipass/skills/telegram/tests/conftest.py
rename to src/aipass/skills/lib/telegram/tests/conftest.py
index 7da8e307..66a1022c 100644
--- a/src/aipass/skills/.aipass/skills/telegram/tests/conftest.py
+++ b/src/aipass/skills/lib/telegram/tests/conftest.py
@@ -1,18 +1,19 @@
-# ===================AIPASS====================
-# META DATA HEADER
-# Name: conftest.py - Telegram skill test configuration
-# Date: 2026-06-15
+# =================== AIPass ====================
+# Name: conftest.py
+# Description: Telegram skill test configuration — path setup and shared fixtures
 # Version: 1.0.0
-# Category: skills/telegram/tests
-#
-# CHANGELOG (Max 5 entries):
-#   - v1.0.0 (2026-06-15): Initial implementation — prax log redirect + path setup
-#
-# CODE STANDARDS:
-#   - Adds src/ and skill root to sys.path for test imports
+# Created: 2026-06-15
+# Modified: 2026-06-29
 # =============================================
 
-"""Telegram skill test configuration."""
+"""
+Telegram skill test configuration.
+
+Sets up sys.path so that both aipass.* (installed package) and the local
+apps.handlers.* namespace are importable from tests without a full pip install.
+Also stubs the optional telethon dependency and redirects Prax logger output
+to a temp dir so test runs don't pollute production log files.
+"""
 
 import os
 import shutil
@@ -27,26 +28,24 @@ if "AIPASS_TEST_LOG_DIR" not in os.environ:
 
 import pytest
 
-# Add src/ to path so aipass.* is importable
-_src_root = Path(__file__).resolve().parents[6]  # noqa: E402
+# sys.path setup is intentional test infrastructure — both entries are needed:
+#   _src_root  → resolves aipass.* installed-package imports
+#   _skill_root → resolves the local apps.handlers.* namespace used by all tests
+_src_root = Path(__file__).resolve().parents[5]
 if str(_src_root) not in sys.path:
     sys.path.insert(0, str(_src_root))
 
-# Add telegram skill root so apps.handlers.* is importable
-_skill_root = Path(__file__).resolve().parents[1]  # noqa: E402
+_skill_root = Path(__file__).resolve().parents[1]
 if str(_skill_root) not in sys.path:
     sys.path.insert(0, str(_skill_root))
 
 
-# Telethon stub — telethon is an OPTIONAL runtime dependency (MTProto client),
-# deliberately NOT in pyproject so the core stays lightweight (botfather_client.py
-# guards it with TELETHON_AVAILABLE). The botfather_client tests mock all Telethon
-# classes (patch("telethon.TelegramClient"), etc.), but unittest.mock.patch must
-# IMPORT the target's parent module to set the attribute — which raises
-# ModuleNotFoundError when telethon isn't installed (e.g. in CI). Register a minimal
-# stub so those patch targets resolve. The guard never clobbers a real telethon if
-# one is installed. Real FloodWaitError/RPCError classes are required for the
-# success/timeout tests, where _send_and_wait imports them but does not patch them.
+# Telethon stub — telethon is an optional dependency (pyproject [telegram] extra).
+# In CI or minimal installs it may not be present. botfather_client.py guards with
+# TELETHON_AVAILABLE. The tests mock Telethon classes (patch("telethon.TelegramClient")),
+# but unittest.mock.patch must IMPORT the parent module — which raises
+# ModuleNotFoundError when telethon isn't installed. Register a minimal stub so those
+# patch targets resolve. Never clobbers a real telethon if one is installed.
 if "telethon" not in sys.modules:
     _telethon_stub = types.ModuleType("telethon")
     _telethon_errors = types.ModuleType("telethon.errors")
diff --git a/src/aipass/skills/lib/telegram/tests/test_attach_only.py b/src/aipass/skills/lib/telegram/tests/test_attach_only.py
new file mode 100644
index 00000000..0afb9a95
--- /dev/null
+++ b/src/aipass/skills/lib/telegram/tests/test_attach_only.py
@@ -0,0 +1,297 @@
+# =================== AIPass ====================
+# Name: test_attach_only.py
+# Description: Tests for attach-only mode (TDPLAN-0009 Stage 1)
+# Version: 1.0.0
+# Created: 2026-06-29
+# Modified: 2026-06-29
+# =============================================
+
+"""
+Tests for attach-only mode (TDPLAN-0009 Stage 1).
+
+The bot attaches to a pre-existing tmux session and never spawns its own.
+When attach_only=True + shared_session is set:
+  - Attaches to existing named tmux session (no spawn)
+  - Missing session → loud error, NO spawn of telegram-{bot_id}
+  - Persistent mapping file written with all CONTRACT fields + seeded cursor
+  - No lock created for the shared session
+  - inject_message reaches the session (unchanged, tested via existing tests)
+"""
+
+import json
+from unittest.mock import patch, MagicMock
+
+import pytest
+
+from apps.handlers.base_bot import BaseBot  # type: ignore[import-not-found]
+
+
+@pytest.fixture
+def _patch_base_bot_deps(tmp_path):
+    patches = [
+        patch("apps.handlers.base_bot.PENDING_DIR", tmp_path),
+        patch("apps.handlers.base_bot.signal.signal"),
+        patch("apps.handlers.base_bot.atexit.register"),
+    ]
+    for p in patches:
+        p.start()
+    yield
+    for p in patches:
+        p.stop()
+
+
+def _make_bot(tmp_path, _patch_base_bot_deps, attach_only=False, shared_session=None):
+    workdir = tmp_path / "workdir"
+    workdir.mkdir(exist_ok=True)
+    with patch("apps.handlers.base_bot.PENDING_DIR", tmp_path):
+        bot = BaseBot(
+            bot_id="mirror_test",
+            bot_token="123:FAKETOKEN",
+            work_dir=workdir,
+            bot_name="Mirror Test Bot",
+            allowed_user_ids=[111],
+            branch_name="devpulse",
+            shared_session=shared_session,
+            attach_only=attach_only,
+        )
+    bot.send_message = MagicMock(return_value={"ok": True, "message_id": 1})
+    return bot
+
+
+# =============================================
+# 1. ensure_tmux_session — attach-only behavior
+# =============================================
+
+
+class TestAttachOnly:
+    """Attach-only mode: attach to existing session, never spawn."""
+
+    def test_attaches_to_existing_session(self, tmp_path, _patch_base_bot_deps):
+        """When shared session exists, bot attaches and returns True."""
+        bot = _make_bot(tmp_path, _patch_base_bot_deps, attach_only=True, shared_session="devpulse")
+
+        result_obj = MagicMock()
+        result_obj.returncode = 0
+        with patch("subprocess.run", return_value=result_obj):
+            assert bot.ensure_tmux_session() is True
+        assert bot.session_name == "devpulse"
+        assert bot._using_shared_session is True
+
+    def test_missing_session_returns_false(self, tmp_path, _patch_base_bot_deps):
+        """When shared session is missing, attach-only returns False (no spawn)."""
+        bot = _make_bot(tmp_path, _patch_base_bot_deps, attach_only=True, shared_session="devpulse")
+
+        result_obj = MagicMock()
+        result_obj.returncode = 1
+        with patch("subprocess.run", return_value=result_obj):
+            assert bot.ensure_tmux_session() is False
+        # Session name should NOT fall back to telegram-{bot_id}
+        assert bot._using_shared_session is False
+
+    def test_missing_session_does_not_spawn(self, tmp_path, _patch_base_bot_deps):
+        """Attach-only never creates a telegram-{bot_id} session."""
+        bot = _make_bot(tmp_path, _patch_base_bot_deps, attach_only=True, shared_session="devpulse")
+
+        result_obj = MagicMock()
+        result_obj.returncode = 1
+        with patch("subprocess.run", return_value=result_obj) as mock_run:
+            bot.ensure_tmux_session()
+            # Should only have checked has-session, never new-session
+            calls = [str(c) for c in mock_run.call_args_list]
+            for call in calls:
+                assert "new-session" not in call
+
+    def test_no_shared_session_config_returns_false(self, tmp_path, _patch_base_bot_deps):
+        """Attach-only without shared_session configured returns False."""
+        bot = _make_bot(tmp_path, _patch_base_bot_deps, attach_only=True, shared_session=None)
+        assert bot.ensure_tmux_session() is False
+
+    def test_non_attach_mode_falls_back_on_missing(self, tmp_path, _patch_base_bot_deps):
+        """Without attach_only, missing shared session falls back to own session."""
+        bot = _make_bot(tmp_path, _patch_base_bot_deps, attach_only=False, shared_session="devpulse")
+
+        has_session = MagicMock(returncode=1)
+        with patch("subprocess.run", return_value=has_session):
+            # Falls back to telegram-{bot_id} and tries to spawn — we just check the name
+            bot.ensure_tmux_session()
+        assert bot.session_name == "telegram-mirror_test"
+
+    def test_handle_message_shows_error_on_attach_fail(self, tmp_path, _patch_base_bot_deps):
+        """handle_message shows specific error when no live session found."""
+        bot = _make_bot(tmp_path, _patch_base_bot_deps, attach_only=True, shared_session="devpulse")
+
+        result_obj = MagicMock()
+        result_obj.returncode = 1
+        with patch("subprocess.run", return_value=result_obj):
+            bot.handle_message(42, "hello", {"message_id": 1})
+
+        msg = bot.send_message.call_args[0][1]
+        assert "No live Claude session" in msg
+        assert "devpulse" in msg
+
+
+# =============================================
+# 2. Mirror mapping file (THE CONTRACT)
+# =============================================
+
+
+class TestMirrorMapping:
+    """Persistent mapping file written at attach with CONTRACT fields."""
+
+    def test_mapping_written_on_attach(self, tmp_path, _patch_base_bot_deps):
+        """Mapping file written when attach-only bot attaches to existing session."""
+        bot = _make_bot(tmp_path, _patch_base_bot_deps, attach_only=True, shared_session="devpulse")
+        bot._active_chat_id = 42
+
+        mapping_dir = tmp_path / ".aipass" / "telegram_bots"
+        result_obj = MagicMock()
+        result_obj.returncode = 0
+        with (
+            patch("subprocess.run", return_value=result_obj),
+            patch("pathlib.Path.home", return_value=tmp_path),
+        ):
+            bot.ensure_tmux_session()
+
+        mapping_file = mapping_dir / "bot-mirror_test.json"
+        assert mapping_file.exists()
+        data = json.loads(mapping_file.read_text())
+        assert data["chat_id"] == 42
+        assert data["bot_token"] == "123:FAKETOKEN"
+        assert data["session_name"] == "devpulse"
+        assert data["mirror"] is True
+        assert "transcript_line_after" in data
+        assert data["work_dir"] == str(tmp_path / "workdir")
+
+    def test_mapping_uses_config_chat_id(self, tmp_path, _patch_base_bot_deps):
+        """Mapping uses _config_chat_id when _active_chat_id is not set."""
+        bot = _make_bot(tmp_path, _patch_base_bot_deps, attach_only=True, shared_session="devpulse")
+        bot._config_chat_id = 99
+
+        mapping_dir = tmp_path / ".aipass" / "telegram_bots"
+        result_obj = MagicMock()
+        result_obj.returncode = 0
+        with (
+            patch("subprocess.run", return_value=result_obj),
+            patch("pathlib.Path.home", return_value=tmp_path),
+        ):
+            bot.ensure_tmux_session()
+
+        mapping_file = mapping_dir / "bot-mirror_test.json"
+        assert mapping_file.exists()
+        data = json.loads(mapping_file.read_text())
+        assert data["chat_id"] == 99
+
+    def test_mapping_deferred_when_no_chat_id(self, tmp_path, _patch_base_bot_deps):
+        """Mapping deferred if no chat_id at attach time."""
+        bot = _make_bot(tmp_path, _patch_base_bot_deps, attach_only=True, shared_session="devpulse")
+
+        mapping_dir = tmp_path / ".aipass" / "telegram_bots"
+        result_obj = MagicMock()
+        result_obj.returncode = 0
+        with (
+            patch("subprocess.run", return_value=result_obj),
+            patch("pathlib.Path.home", return_value=tmp_path),
+        ):
+            bot.ensure_tmux_session()
+
+        mapping_file = mapping_dir / "bot-mirror_test.json"
+        assert not mapping_file.exists()
+        assert bot._mirror_mapping_written is False
+
+    def test_mapping_written_once(self, tmp_path, _patch_base_bot_deps):
+        """Mapping file only written once (idempotent)."""
+        bot = _make_bot(tmp_path, _patch_base_bot_deps, attach_only=True, shared_session="devpulse")
+        bot._active_chat_id = 42
+
+        result_obj = MagicMock()
+        result_obj.returncode = 0
+        with (
+            patch("subprocess.run", return_value=result_obj),
+            patch("pathlib.Path.home", return_value=tmp_path),
+        ):
+            bot.ensure_tmux_session()
+            bot.ensure_tmux_session()
+
+        assert bot._mirror_mapping_written is True
+
+    def test_mapping_not_written_for_non_attach(self, tmp_path, _patch_base_bot_deps):
+        """Non-attach-only bots don't write mirror mapping."""
+        bot = _make_bot(tmp_path, _patch_base_bot_deps, attach_only=False, shared_session="devpulse")
+        bot._active_chat_id = 42
+
+        mapping_dir = tmp_path / ".aipass" / "telegram_bots"
+        result_obj = MagicMock()
+        result_obj.returncode = 0
+        with (
+            patch("subprocess.run", return_value=result_obj),
+            patch("pathlib.Path.home", return_value=tmp_path),
+        ):
+            bot.ensure_tmux_session()
+
+        mapping_file = mapping_dir / "bot-mirror_test.json"
+        assert not mapping_file.exists()
+
+
+# =============================================
+# 3. Lock file skipped in attach-only
+# =============================================
+
+
+class TestAttachOnlyLock:
+    """Lock file still created in attach-only (prevents duplicate pollers)."""
+
+    def test_lock_still_created_in_attach_mode(self, tmp_path, _patch_base_bot_deps):
+        """run() still creates lock in attach-only mode (one poller per bot_id)."""
+        bot = _make_bot(tmp_path, _patch_base_bot_deps, attach_only=True, shared_session="devpulse")
+
+        with (
+            patch.object(bot, "_check_lock", return_value=False) as mock_check,
+            patch.object(bot, "_create_lock") as mock_create,
+            patch.object(bot, "verify_connection", return_value=True),
+            patch.object(bot, "_set_command_menu"),
+            patch.object(bot, "_boot_monitor"),
+            patch.object(bot, "clean_stale_pending"),
+            patch.object(bot, "_load_offset", return_value=0),
+            patch.object(bot, "poll_updates", side_effect=KeyboardInterrupt),
+            patch("apps.handlers.base_bot.PENDING_DIR", tmp_path),
+        ):
+            bot.run()
+
+        mock_check.assert_called_once()
+        mock_create.assert_called_once()
+
+    def test_lock_created_in_normal_mode(self, tmp_path, _patch_base_bot_deps):
+        """run() creates lock in normal (non-attach) mode."""
+        bot = _make_bot(tmp_path, _patch_base_bot_deps, attach_only=False)
+
+        with (
+            patch.object(bot, "_check_lock", return_value=False),
+            patch.object(bot, "_create_lock") as mock_create,
+            patch.object(bot, "verify_connection", return_value=True),
+            patch.object(bot, "_set_command_menu"),
+            patch.object(bot, "_boot_monitor"),
+            patch.object(bot, "clean_stale_pending"),
+            patch.object(bot, "_load_offset", return_value=0),
+            patch.object(bot, "poll_updates", side_effect=KeyboardInterrupt),
+            patch("apps.handlers.base_bot.PENDING_DIR", tmp_path),
+        ):
+            bot.run()
+
+        mock_create.assert_called_once()
+
+
+# =============================================
+# 4. Config loading
+# =============================================
+
+
+class TestAttachOnlyConfig:
+    """attach_only flag passed through config."""
+
+    def test_attach_only_defaults_false(self, tmp_path, _patch_base_bot_deps):
+        bot = _make_bot(tmp_path, _patch_base_bot_deps)
+        assert bot._attach_only is False
+
+    def test_attach_only_set_true(self, tmp_path, _patch_base_bot_deps):
+        bot = _make_bot(tmp_path, _patch_base_bot_deps, attach_only=True)
+        assert bot._attach_only is True
diff --git a/src/aipass/skills/.aipass/skills/telegram/tests/test_bot_registry.py b/src/aipass/skills/lib/telegram/tests/test_bot_registry.py
similarity index 97%
rename from src/aipass/skills/.aipass/skills/telegram/tests/test_bot_registry.py
rename to src/aipass/skills/lib/telegram/tests/test_bot_registry.py
index 3e4da190..1cd02a06 100644
--- a/src/aipass/skills/.aipass/skills/telegram/tests/test_bot_registry.py
+++ b/src/aipass/skills/lib/telegram/tests/test_bot_registry.py
@@ -6,7 +6,6 @@ No external dependencies beyond pytest.
 """
 
 import json
-from pathlib import Path
 
 import pytest
 from apps.handlers import bot_registry  # type: ignore[import-not-found]
@@ -191,11 +190,15 @@ class TestSaveRegistry:
         assert result is True
         assert bot_registry.REGISTRY_DIR.is_dir()
 
-    def test_returns_false_on_write_failure(self, monkeypatch):
+    def test_returns_false_on_write_failure(self, monkeypatch, tmp_path):
         """Should return False when writing fails (e.g. permission error)."""
-        # Point to an impossible path
-        monkeypatch.setattr(bot_registry, "REGISTRY_DIR", Path("/proc/nonexistent/impossible"))
-        monkeypatch.setattr(bot_registry, "REGISTRY_FILE", Path("/proc/nonexistent/impossible/_registry.json"))
+        # Put a regular file where a directory is expected. mkdir(parents=True)
+        # then fails on every OS (NotADirectoryError/FileExistsError), so this is
+        # cross-platform — unlike a hardcoded Unix-only path such as /proc/...
+        blocker = tmp_path / "blocker"
+        blocker.write_text("x", encoding="utf-8")
+        monkeypatch.setattr(bot_registry, "REGISTRY_DIR", blocker / "sub")
+        monkeypatch.setattr(bot_registry, "REGISTRY_FILE", blocker / "sub" / "_registry.json")
 
         result = bot_registry.save_registry({"bots": {}, "metadata": {}})
 
diff --git a/src/aipass/skills/.aipass/skills/telegram/tests/test_botfather_client.py b/src/aipass/skills/lib/telegram/tests/test_botfather_client.py
similarity index 100%
rename from src/aipass/skills/.aipass/skills/telegram/tests/test_botfather_client.py
rename to src/aipass/skills/lib/telegram/tests/test_botfather_client.py
diff --git a/src/aipass/skills/.aipass/skills/telegram/tests/test_handler_routing.py b/src/aipass/skills/lib/telegram/tests/test_handler_routing.py
similarity index 100%
rename from src/aipass/skills/.aipass/skills/telegram/tests/test_handler_routing.py
rename to src/aipass/skills/lib/telegram/tests/test_handler_routing.py
diff --git a/src/aipass/skills/lib/telegram/tests/test_heartbeat_delivered.py b/src/aipass/skills/lib/telegram/tests/test_heartbeat_delivered.py
new file mode 100644
index 00000000..cf527fe3
--- /dev/null
+++ b/src/aipass/skills/lib/telegram/tests/test_heartbeat_delivered.py
@@ -0,0 +1,246 @@
+# =================== AIPass ====================
+# Name: test_heartbeat_delivered.py
+# Description: Tests for heartbeat delivered-flag fix (DPLAN-0223)
+# Version: 1.0.0
+# Created: 2026-06-29
+# Modified: 2026-06-29
+# =============================================
+
+"""
+Tests for heartbeat delivered-flag fix (DPLAN-0223).
+
+The heartbeat now stops when the pending file contains 'delivered': true
+(set by @hooks _advance_pending), instead of waiting for file deletion.
+
+Tests cover:
+  - Heartbeat stops when pending file has delivered=true
+  - Heartbeat continues when pending file exists but not delivered
+  - Heartbeat stops when pending file is absent (backward compat)
+  - Multi-Stop keeps file alive (delivered flag, not deletion)
+  - Reply not clobbered: heartbeat does NOT edit after delivery
+"""
+
+import json
+import time
+import pytest
+from unittest.mock import patch
+
+from apps.handlers.base_bot import BaseBot  # type: ignore[import-not-found]
+
+
+@pytest.fixture
+def _patch_base_bot_deps(tmp_path):
+    patches = [
+        patch("apps.handlers.base_bot.PENDING_DIR", tmp_path),
+        patch("apps.handlers.base_bot.signal.signal"),
+        patch("apps.handlers.base_bot.atexit.register"),
+    ]
+    for p in patches:
+        p.start()
+    yield
+    for p in patches:
+        p.stop()
+
+
+def _make_bot(tmp_path, _patch_base_bot_deps, pending_dir=None):
+    pdir = pending_dir or tmp_path
+    with patch("apps.handlers.base_bot.PENDING_DIR", pdir):
+        workdir = tmp_path / "workdir"
+        workdir.mkdir(exist_ok=True)
+        bot = BaseBot(
+            bot_id="heartbeat_test",
+            bot_token="123:FAKETOKEN",
+            work_dir=workdir,
+            bot_name="Heartbeat Test Bot",
+            allowed_user_ids=[111],
+            branch_name=None,
+        )
+    bot.pending_file = pdir / "bot-heartbeat_test.json"
+    return bot
+
+
+# =============================================
+# 1. _is_pending_delivered
+# =============================================
+
+
+class TestIsPendingDelivered:
+    """Verify _is_pending_delivered reads the delivered flag correctly."""
+
+    def test_returns_true_when_delivered(self, tmp_path, _patch_base_bot_deps):
+        bot = _make_bot(tmp_path, _patch_base_bot_deps)
+        bot.pending_file.parent.mkdir(parents=True, exist_ok=True)
+        bot.pending_file.write_text(json.dumps({"chat_id": 42, "delivered": True}), encoding="utf-8")
+        assert bot._is_pending_delivered() is True
+
+    def test_returns_false_when_not_delivered(self, tmp_path, _patch_base_bot_deps):
+        bot = _make_bot(tmp_path, _patch_base_bot_deps)
+        bot.pending_file.parent.mkdir(parents=True, exist_ok=True)
+        bot.pending_file.write_text(json.dumps({"chat_id": 42}), encoding="utf-8")
+        assert bot._is_pending_delivered() is False
+
+    def test_returns_true_when_file_absent(self, tmp_path, _patch_base_bot_deps):
+        bot = _make_bot(tmp_path, _patch_base_bot_deps)
+        assert not bot.pending_file.exists()
+        assert bot._is_pending_delivered() is True
+
+    def test_returns_false_on_corrupt_json(self, tmp_path, _patch_base_bot_deps):
+        bot = _make_bot(tmp_path, _patch_base_bot_deps)
+        bot.pending_file.parent.mkdir(parents=True, exist_ok=True)
+        bot.pending_file.write_text("not json", encoding="utf-8")
+        assert bot._is_pending_delivered() is False
+
+    def test_returns_false_when_delivered_is_false(self, tmp_path, _patch_base_bot_deps):
+        bot = _make_bot(tmp_path, _patch_base_bot_deps)
+        bot.pending_file.parent.mkdir(parents=True, exist_ok=True)
+        bot.pending_file.write_text(json.dumps({"chat_id": 42, "delivered": False}), encoding="utf-8")
+        assert bot._is_pending_delivered() is False
+
+
+# =============================================
+# 2. HEARTBEAT STOPS ON DELIVERED
+# =============================================
+
+
+class TestHeartbeatStopsOnDelivered:
+    """Heartbeat thread exits when pending file has delivered=true."""
+
+    def test_heartbeat_stops_when_delivered_mid_loop(self, tmp_path, _patch_base_bot_deps):
+        bot = _make_bot(tmp_path, _patch_base_bot_deps)
+        bot.pending_file.parent.mkdir(parents=True, exist_ok=True)
+        bot.pending_file.write_text(json.dumps({"chat_id": 42}), encoding="utf-8")
+
+        call_count = 0
+
+        def fake_edit(chat_id, msg_id, text):
+            nonlocal call_count
+            call_count += 1
+            # Simulate delivery on first heartbeat edit
+            bot.pending_file.write_text(json.dumps({"chat_id": 42, "delivered": True}), encoding="utf-8")
+
+        with (
+            patch.object(bot, "edit_message", side_effect=fake_edit),
+            patch.object(bot, "_tmux_session_exists", return_value=True),
+            patch("apps.handlers.base_bot.HEARTBEAT_INTERVAL", 0.1),
+        ):
+            bot._start_heartbeat(42, 999)
+            time.sleep(0.5)
+            bot._stop_heartbeat()
+
+        # Should have stopped after 1 edit (when delivered was set)
+        assert call_count <= 2
+
+    def test_heartbeat_continues_when_not_delivered(self, tmp_path, _patch_base_bot_deps):
+        bot = _make_bot(tmp_path, _patch_base_bot_deps)
+        bot.pending_file.parent.mkdir(parents=True, exist_ok=True)
+        bot.pending_file.write_text(json.dumps({"chat_id": 42}), encoding="utf-8")
+
+        call_count = 0
+
+        def fake_edit(chat_id, msg_id, text):
+            nonlocal call_count
+            call_count += 1
+
+        with (
+            patch.object(bot, "edit_message", side_effect=fake_edit),
+            patch.object(bot, "_tmux_session_exists", return_value=True),
+            patch("apps.handlers.base_bot.HEARTBEAT_INTERVAL", 0.1),
+        ):
+            bot._start_heartbeat(42, 999)
+            time.sleep(0.5)
+            bot._stop_heartbeat()
+
+        # Should have ticked multiple times since never delivered
+        assert call_count >= 2
+
+    def test_heartbeat_stops_when_file_absent(self, tmp_path, _patch_base_bot_deps):
+        """Backward compat: heartbeat still stops when file is gone."""
+        bot = _make_bot(tmp_path, _patch_base_bot_deps)
+        assert not bot.pending_file.exists()
+
+        with (
+            patch.object(bot, "edit_message") as mock_edit,
+            patch.object(bot, "_tmux_session_exists", return_value=True),
+            patch("apps.handlers.base_bot.HEARTBEAT_INTERVAL", 0.1),
+        ):
+            bot._start_heartbeat(42, 999)
+            time.sleep(0.4)
+            bot._stop_heartbeat()
+
+        # File never existed, so heartbeat breaks immediately — no edits
+        mock_edit.assert_not_called()
+
+
+# =============================================
+# 3. MULTI-STOP KEEPS FILE ALIVE
+# =============================================
+
+
+class TestMultiStopFileAlive:
+    """Pending file survives delivery (advanced, not deleted)."""
+
+    def test_pending_file_survives_with_delivered_flag(self, tmp_path, _patch_base_bot_deps):
+        bot = _make_bot(tmp_path, _patch_base_bot_deps)
+        bot.pending_file.parent.mkdir(parents=True, exist_ok=True)
+
+        initial_data = {"chat_id": 42, "transcript_line_after": 100}
+        bot.pending_file.write_text(json.dumps(initial_data), encoding="utf-8")
+
+        # Simulate _advance_pending behavior (what @hooks does)
+        data = json.loads(bot.pending_file.read_text(encoding="utf-8"))
+        data["delivered"] = True
+        data["transcript_line_after"] = 200
+        bot.pending_file.write_text(json.dumps(data), encoding="utf-8")
+
+        # File still exists
+        assert bot.pending_file.exists()
+        # But heartbeat sees it as delivered
+        assert bot._is_pending_delivered() is True
+        # Cursor advanced
+        reloaded = json.loads(bot.pending_file.read_text(encoding="utf-8"))
+        assert reloaded["transcript_line_after"] == 200
+
+    def test_new_message_overwrites_delivered(self, tmp_path, _patch_base_bot_deps):
+        """A new write_pending_file clears the delivered flag."""
+        bot = _make_bot(tmp_path, _patch_base_bot_deps)
+        bot.pending_file.parent.mkdir(parents=True, exist_ok=True)
+
+        # Simulate previous delivery
+        bot.pending_file.write_text(json.dumps({"chat_id": 42, "delivered": True}), encoding="utf-8")
+        assert bot._is_pending_delivered() is True
+
+        # Now write a new pending (as handle_message does)
+        with patch.object(bot, "_get_transcript_line_count", return_value=300):
+            bot.write_pending_file(42, 999, 1000)
+
+        # delivered flag should be gone
+        assert bot._is_pending_delivered() is False
+        data = json.loads(bot.pending_file.read_text(encoding="utf-8"))
+        assert "delivered" not in data
+
+
+# =============================================
+# 4. REPLY NOT CLOBBERED
+# =============================================
+
+
+class TestReplyNotClobbered:
+    """After delivery, heartbeat must NOT edit the message (no clobber)."""
+
+    def test_no_edit_after_delivered(self, tmp_path, _patch_base_bot_deps):
+        bot = _make_bot(tmp_path, _patch_base_bot_deps)
+        bot.pending_file.parent.mkdir(parents=True, exist_ok=True)
+        # Start with delivered=true (simulates hooks already delivered before heartbeat tick)
+        bot.pending_file.write_text(json.dumps({"chat_id": 42, "delivered": True}), encoding="utf-8")
+
+        with (
+            patch.object(bot, "edit_message") as mock_edit,
+            patch.object(bot, "_tmux_session_exists", return_value=True),
+            patch("apps.handlers.base_bot.HEARTBEAT_INTERVAL", 0.1),
+        ):
+            bot._start_heartbeat(42, 999)
+            time.sleep(0.4)
+            bot._stop_heartbeat()
+
+        # Heartbeat saw delivered immediately, never edited
+        mock_edit.assert_not_called()
diff --git a/src/aipass/skills/.aipass/skills/telegram/tests/test_log_streamer.py b/src/aipass/skills/lib/telegram/tests/test_log_streamer.py
similarity index 98%
rename from src/aipass/skills/.aipass/skills/telegram/tests/test_log_streamer.py
rename to src/aipass/skills/lib/telegram/tests/test_log_streamer.py
index ce2d6ec8..dbb188be 100644
--- a/src/aipass/skills/.aipass/skills/telegram/tests/test_log_streamer.py
+++ b/src/aipass/skills/lib/telegram/tests/test_log_streamer.py
@@ -62,11 +62,13 @@ def streamer(logs_dir, tmp_path):
 @pytest.fixture
 def streamer_with_files(logs_dir, tmp_path):
     """Create a LogStreamer after pre-populating matching and non-matching log files."""
-    # Create matching log files with content
-    (logs_dir / "api_main.log").write_text("line1\nline2\n", encoding="utf-8")
-    (logs_dir / "api_error.log").write_text("err1\n", encoding="utf-8")
+    # Create matching log files with content. newline="" disables newline
+    # translation so byte counts match len() on Windows too (\n stays 1 byte,
+    # not \r\n) — real log files are LF-terminated.
+    (logs_dir / "api_main.log").write_text("line1\nline2\n", encoding="utf-8", newline="")
+    (logs_dir / "api_error.log").write_text("err1\n", encoding="utf-8", newline="")
     # Create a non-matching file (should be ignored)
-    (logs_dir / "trigger_main.log").write_text("other\n", encoding="utf-8")
+    (logs_dir / "trigger_main.log").write_text("other\n", encoding="utf-8", newline="")
 
     return _make_streamer(logs_dir, tmp_path)
 
diff --git a/src/aipass/skills/lib/telegram/tests/test_mirror_session.py b/src/aipass/skills/lib/telegram/tests/test_mirror_session.py
new file mode 100644
index 00000000..c13d3f84
--- /dev/null
+++ b/src/aipass/skills/lib/telegram/tests/test_mirror_session.py
@@ -0,0 +1,456 @@
+# =================== AIPass ====================
+# Name: test_mirror_session.py
+# Description: Tests for TDPLAN-0009 FINISH — mirror session launch, transcript resolver, create→attach
+# Version: 1.0.0
+# Created: 2026-06-29
+# Modified: 2026-06-29
+# =============================================
+
+"""
+Tests for the mirror session system (TDPLAN-0009 FINISH).
+
+Covers:
+  - launch_mirror_session: tmux session with --dangerously-skip-permissions
+  - start_service: systemd user service start
+  - create_bot mirror params: shared_session, attach_only, chat_id in config
+  - _resolve_active_transcript: PID-based transcript detection
+  - _write_mirror_mapping: transcript-change detection and rewrite
+  - _config_chat_id initialization
+"""
+
+import json
+from pathlib import Path
+from unittest.mock import MagicMock, patch
+
+import pytest
+
+from apps.handlers.base_bot import BaseBot  # type: ignore[import-not-found]
+from apps.handlers.bot_factory import (  # type: ignore[import-not-found]
+    launch_mirror_session,
+    start_service,
+)
+
+
+# =============================================
+# Fixtures
+# =============================================
+
+
+@pytest.fixture
+def _patch_base_bot_deps(tmp_path):
+    patches = [
+        patch("apps.handlers.base_bot.PENDING_DIR", tmp_path),
+        patch("apps.handlers.base_bot.signal.signal"),
+        patch("apps.handlers.base_bot.atexit.register"),
+    ]
+    for p in patches:
+        p.start()
+    yield
+    for p in patches:
+        p.stop()
+
+
+def _make_bot(tmp_path, _patch_base_bot_deps, attach_only=False, shared_session=None):
+    workdir = tmp_path / "workdir"
+    workdir.mkdir(exist_ok=True)
+    with patch("apps.handlers.base_bot.PENDING_DIR", tmp_path):
+        bot = BaseBot(
+            bot_id="mirror_test",
+            bot_token="123:FAKETOKEN",
+            work_dir=workdir,
+            bot_name="Mirror Test Bot",
+            allowed_user_ids=[111],
+            branch_name="api",
+            shared_session=shared_session,
+            attach_only=attach_only,
+        )
+    bot.send_message = MagicMock(return_value={"ok": True, "message_id": 1})
+    return bot
+
+
+# =============================================
+# 1. launch_mirror_session
+# =============================================
+
+
+class TestLaunchMirrorSession:
+    """Tests for launch_mirror_session() in bot_factory."""
+
+    def test_creates_tmux_session_with_skip_perms(self):
+        """tmux new-session created and claude launched with skip-permissions."""
+        no_session = MagicMock(returncode=1)
+        ok = MagicMock(returncode=0)
+        side = [no_session, ok, ok, ok]
+
+        with (
+            patch("apps.handlers.bot_factory.subprocess.run", side_effect=side),
+            patch("time.sleep"),
+        ):
+            result = launch_mirror_session(
+                session_name="telegram-api",
+                bot_id="api",
+                work_dir="/tmp/test",
+            )
+
+        assert result is True
+
+    def test_claude_launched_with_correct_flags(self):
+        """AIPASS_SESSION_TYPE=interactive-mirror and skip-perms flag set."""
+        calls_made = []
+        first_call = True
+
+        def _track(*args, **kwargs):
+            """Record subprocess.run calls for assertion."""
+            nonlocal first_call
+            calls_made.append(args[0] if args else kwargs.get("args", []))
+            if first_call:
+                first_call = False
+                return MagicMock(returncode=1)
+            result = MagicMock(returncode=0)
+            return result
+
+        with (
+            patch("apps.handlers.bot_factory.subprocess.run", side_effect=_track),
+            patch("time.sleep"),
+        ):
+            launch_mirror_session(
+                session_name="telegram-api",
+                bot_id="api",
+                work_dir="/tmp/test",
+            )
+
+        send_keys_calls = [c for c in calls_made if "send-keys" in c]
+        claude_cmd = send_keys_calls[-1][-2]
+        assert "interactive-mirror" in claude_cmd
+
+    def test_idempotent_if_session_exists(self):
+        """Returns True without creating if session already exists."""
+        has_session = MagicMock(returncode=0)
+
+        with patch("apps.handlers.bot_factory.subprocess.run", return_value=has_session) as mock_run:
+            result = launch_mirror_session(session_name="telegram-api", bot_id="api", work_dir="/tmp/test")
+
+        assert result is True
+        assert mock_run.call_count == 1
+
+    def test_returns_false_when_tmux_not_found(self):
+        """Returns False when tmux is not installed."""
+        with patch("apps.handlers.bot_factory.subprocess.run", side_effect=FileNotFoundError):
+            result = launch_mirror_session(session_name="telegram-api", bot_id="api", work_dir="/tmp/test")
+
+        assert result is False
+
+
+# =============================================
+# 2. start_service
+# =============================================
+
+
+class TestStartService:
+    """Tests for start_service() in bot_factory."""
+
+    def test_starts_systemd_service(self):
+        """Calls systemctl --user start telegram-bot@{bot_id}."""
+        mock_result = MagicMock(returncode=0)
+        with patch("apps.handlers.bot_factory.subprocess.run", return_value=mock_result) as mock_run:
+            result = start_service("api")
+
+        assert result is True
+        mock_run.assert_called_once()
+        cmd = mock_run.call_args[0][0]
+        assert cmd == ["systemctl", "--user", "start", "telegram-bot@api"]
+
+    def test_returns_false_on_failure(self):
+        """Returns False when systemctl returns non-zero."""
+        mock_result = MagicMock(returncode=1, stderr="unit not found")
+        with patch("apps.handlers.bot_factory.subprocess.run", return_value=mock_result):
+            assert start_service("api") is False
+
+    def test_returns_false_on_timeout(self):
+        """Returns False on TimeoutExpired."""
+        import subprocess
+
+        err = subprocess.TimeoutExpired(cmd="", timeout=10)
+        with patch("apps.handlers.bot_factory.subprocess.run", side_effect=err):
+            assert start_service("api") is False
+
+
+# =============================================
+# 3. create_bot mirror params
+# =============================================
+
+
+class TestCreateBotMirror:
+    """Tests for create_bot() with mirror params."""
+
+    @pytest.fixture
+    def _mock_create_deps(self):
+        """Mock all external deps of create_bot."""
+        bot_info = {"username": "test_bot", "id": 123}
+        branch_info = {"name": "api", "path": "/home/test/api"}
+        patches = [
+            patch("apps.handlers.bot_factory.validate_token", return_value=bot_info),
+            patch("apps.handlers.bot_factory.validate_branch", return_value=branch_info),
+            patch("apps.handlers.bot_factory.get_bot", return_value=None),
+            patch("apps.handlers.bot_factory.get_bot_by_branch", return_value=None),
+            patch("apps.handlers.bot_factory.ensure_registry"),
+            patch("apps.handlers.bot_factory._api_set_secret"),
+            patch("apps.handlers.bot_factory.register_bot", return_value=True),
+            patch("apps.handlers.bot_factory.set_bot_commands"),
+            patch("apps.handlers.bot_factory.build_botfather_commands", return_value=[]),
+            patch("apps.handlers.bot_factory.enable_service", return_value=True),
+            patch("apps.handlers.bot_factory.start_bot_process", return_value=True),
+            patch("apps.handlers.bot_factory.launch_mirror_session", return_value=True),
+            patch("apps.handlers.bot_factory.start_service", return_value=True),
+            patch("apps.handlers.bot_factory._BOT_CONFIG_DIR", Path("/tmp/test_bots")),
+        ]
+        mocks = {}
+        started = []
+        for p in patches:
+            m = p.start()
+            started.append(p)
+            name = p.attribute if hasattr(p, "attribute") and p.attribute else str(p).split(".")[-1].rstrip("'>)")
+            mocks[name] = m
+        yield mocks
+        for p in started:
+            p.stop()
+
+    def test_config_includes_mirror_fields(self, _mock_create_deps, tmp_path):
+        """Config written with shared_session, attach_only, chat_id."""
+        from apps.handlers.bot_factory import create_bot  # type: ignore[import-not-found]
+
+        with patch("apps.handlers.bot_factory._BOT_CONFIG_DIR", tmp_path):
+            result = create_bot(
+                bot_id="api",
+                bot_token="123:FAKE",
+                branch_name="api",
+                shared_session="telegram-api",
+                attach_only=True,
+                chat_id=42,
+            )
+
+        assert result is not None
+        config_file = tmp_path / "api.json"
+        assert config_file.exists()
+        config = json.loads(config_file.read_text())
+        assert config["shared_session"] == "telegram-api"
+        assert config["attach_only"] is True
+        assert config["chat_id"] == 42
+
+    def test_launches_mirror_session_when_attach_only(self, _mock_create_deps, tmp_path):
+        """launch_mirror_session called when shared_session + attach_only."""
+        from apps.handlers.bot_factory import create_bot  # type: ignore[import-not-found]
+
+        with patch("apps.handlers.bot_factory._BOT_CONFIG_DIR", tmp_path):
+            create_bot(
+                bot_id="api",
+                bot_token="123:FAKE",
+                branch_name="api",
+                shared_session="telegram-api",
+                attach_only=True,
+            )
+
+        _mock_create_deps["launch_mirror_session"].assert_called_once()
+
+    def test_starts_via_systemd_when_mirror(self, _mock_create_deps, tmp_path):
+        """Mirror bot started via start_service, not start_bot_process."""
+        from apps.handlers.bot_factory import create_bot  # type: ignore[import-not-found]
+
+        with patch("apps.handlers.bot_factory._BOT_CONFIG_DIR", tmp_path):
+            create_bot(
+                bot_id="api",
+                bot_token="123:FAKE",
+                branch_name="api",
+                shared_session="telegram-api",
+                attach_only=True,
+            )
+
+        _mock_create_deps["start_service"].assert_called_once()
+        _mock_create_deps["start_bot_process"].assert_not_called()
+
+    def test_starts_via_popen_when_not_mirror(self, _mock_create_deps, tmp_path):
+        """Non-mirror bot still uses start_bot_process."""
+        from apps.handlers.bot_factory import create_bot  # type: ignore[import-not-found]
+
+        with patch("apps.handlers.bot_factory._BOT_CONFIG_DIR", tmp_path):
+            create_bot(
+                bot_id="api",
+                bot_token="123:FAKE",
+                branch_name="api",
+            )
+
+        _mock_create_deps["start_bot_process"].assert_called_once()
+        _mock_create_deps["launch_mirror_session"].assert_not_called()
+
+
+# =============================================
+# 4. Transcript resolution and mapping rewrite
+# =============================================
+
+
+class TestMirrorMappingRewrite:
+    """Tests for transcript-change detection in _write_mirror_mapping."""
+
+    def test_mapping_rewrites_on_transcript_change(self, tmp_path, _patch_base_bot_deps):
+        """When transcript path changes, mapping is rewritten with new cursor."""
+        bot = _make_bot(tmp_path, _patch_base_bot_deps, attach_only=True, shared_session="api")
+        bot._active_chat_id = 42
+        bot.session_name = "api"
+
+        mapping_dir = tmp_path / ".aipass" / "telegram_bots"
+
+        with patch("pathlib.Path.home", return_value=tmp_path):
+            with patch.object(bot, "_resolve_active_transcript", return_value=("/path/a.jsonl", 10)):
+                bot._write_mirror_mapping()
+
+            assert bot._mirror_mapping_written is True
+            assert bot._last_transcript_path == "/path/a.jsonl"
+            data1 = json.loads((mapping_dir / "bot-mirror_test.json").read_text())
+            assert data1["transcript_line_after"] == 10
+
+            with patch.object(bot, "_resolve_active_transcript", return_value=("/path/b.jsonl", 5)):
+                bot._write_mirror_mapping()
+
+            data2 = json.loads((mapping_dir / "bot-mirror_test.json").read_text())
+            assert data2["transcript_line_after"] == 5
+            assert bot._last_transcript_path == "/path/b.jsonl"
+
+    def test_mapping_not_rewritten_same_transcript(self, tmp_path, _patch_base_bot_deps):
+        """When transcript path unchanged, mapping is not rewritten."""
+        bot = _make_bot(tmp_path, _patch_base_bot_deps, attach_only=True, shared_session="api")
+        bot._active_chat_id = 42
+        bot.session_name = "api"
+
+        mapping_dir = tmp_path / ".aipass" / "telegram_bots"
+
+        with patch("pathlib.Path.home", return_value=tmp_path):
+            with patch.object(bot, "_resolve_active_transcript", return_value=("/path/a.jsonl", 10)):
+                bot._write_mirror_mapping()
+                mtime1 = (mapping_dir / "bot-mirror_test.json").stat().st_mtime
+
+            import time
+
+            time.sleep(0.05)
+
+            with patch.object(bot, "_resolve_active_transcript", return_value=("/path/a.jsonl", 20)):
+                bot._write_mirror_mapping()
+                mtime2 = (mapping_dir / "bot-mirror_test.json").stat().st_mtime
+
+        assert mtime1 == mtime2
+
+    def test_mapping_rewrites_when_transcript_none(self, tmp_path, _patch_base_bot_deps):
+        """When transcript is None both times, still written only once."""
+        bot = _make_bot(tmp_path, _patch_base_bot_deps, attach_only=True, shared_session="api")
+        bot._active_chat_id = 42
+        bot.session_name = "api"
+
+        with patch("pathlib.Path.home", return_value=tmp_path):
+            with patch.object(bot, "_resolve_active_transcript", return_value=(None, 0)):
+                bot._write_mirror_mapping()
+                assert bot._mirror_mapping_written is True
+                bot._write_mirror_mapping()
+
+    def test_last_transcript_path_updated(self, tmp_path, _patch_base_bot_deps):
+        """_last_transcript_path updated after successful write."""
+        bot = _make_bot(tmp_path, _patch_base_bot_deps, attach_only=True, shared_session="api")
+        bot._active_chat_id = 42
+        bot.session_name = "api"
+
+        assert bot._last_transcript_path is None
+
+        with patch("pathlib.Path.home", return_value=tmp_path):
+            with patch.object(bot, "_resolve_active_transcript", return_value=("/path/transcript.jsonl", 15)):
+                bot._write_mirror_mapping()
+
+        assert bot._last_transcript_path == "/path/transcript.jsonl"
+
+
+# =============================================
+# 5. Transcript resolver
+# =============================================
+
+
+class TestResolveActiveTranscript:
+    """Tests for _resolve_active_transcript."""
+
+    def test_returns_none_when_no_projects_dir(self, tmp_path, _patch_base_bot_deps):
+        """Returns (None, 0) when projects dir does not exist."""
+        bot = _make_bot(tmp_path, _patch_base_bot_deps)
+        with patch("pathlib.Path.home", return_value=tmp_path):
+            path, count = bot._resolve_active_transcript()
+        assert path is None
+        assert count == 0
+
+    def test_returns_none_when_no_jsonl_files(self, tmp_path, _patch_base_bot_deps):
+        """Returns (None, 0) when projects dir exists but no JSONL files."""
+        bot = _make_bot(tmp_path, _patch_base_bot_deps)
+        slug = str(bot.work_dir).replace("\\", "-").replace("/", "-")
+        projects_dir = tmp_path / ".claude" / "projects" / slug
+        projects_dir.mkdir(parents=True, exist_ok=True)
+
+        with patch("pathlib.Path.home", return_value=tmp_path):
+            path, count = bot._resolve_active_transcript()
+        assert path is None
+        assert count == 0
+
+    def test_falls_back_to_recent_mtime(self, tmp_path, _patch_base_bot_deps):
+        """Uses most recent JSONL when PID check fails and file is < 5min old."""
+        bot = _make_bot(tmp_path, _patch_base_bot_deps)
+        slug = str(bot.work_dir).replace("\\", "-").replace("/", "-")
+        projects_dir = tmp_path / ".claude" / "projects" / slug
+        projects_dir.mkdir(parents=True, exist_ok=True)
+
+        transcript = projects_dir / "abc123.jsonl"
+        transcript.write_text('{"type":"message"}\n{"type":"response"}\n')
+
+        with (
+            patch("pathlib.Path.home", return_value=tmp_path),
+            patch.object(bot, "_get_tmux_pane_pid", return_value=None),
+        ):
+            path, count = bot._resolve_active_transcript()
+
+        assert path == str(transcript)
+        assert count == 2
+
+    def test_ignores_old_files(self, tmp_path, _patch_base_bot_deps):
+        """JSONL files older than 5 minutes are not selected."""
+        import os
+
+        bot = _make_bot(tmp_path, _patch_base_bot_deps)
+        slug = str(bot.work_dir).replace("\\", "-").replace("/", "-")
+        projects_dir = tmp_path / ".claude" / "projects" / slug
+        projects_dir.mkdir(parents=True, exist_ok=True)
+
+        transcript = projects_dir / "old.jsonl"
+        transcript.write_text('{"type":"message"}\n')
+        old_time = 1000000.0
+        os.utime(transcript, (old_time, old_time))
+
+        with (
+            patch("pathlib.Path.home", return_value=tmp_path),
+            patch.object(bot, "_get_tmux_pane_pid", return_value=None),
+        ):
+            path, count = bot._resolve_active_transcript()
+
+        assert path is None
+        assert count == 0
+
+
+# =============================================
+# 6. _config_chat_id init
+# =============================================
+
+
+class TestConfigChatId:
+    """Tests for _config_chat_id initialization."""
+
+    def test_config_chat_id_initialized_to_none(self, tmp_path, _patch_base_bot_deps):
+        """BaseBot.__init__ initializes _config_chat_id to None."""
+        bot = _make_bot(tmp_path, _patch_base_bot_deps)
+        assert bot._config_chat_id is None
+
+    def test_config_chat_id_settable(self, tmp_path, _patch_base_bot_deps):
+        """_config_chat_id can be set after construction."""
+        bot = _make_bot(tmp_path, _patch_base_bot_deps)
+        bot._config_chat_id = 42
+        assert bot._config_chat_id == 42
diff --git a/src/aipass/skills/lib/telegram/tests/test_monitor.py b/src/aipass/skills/lib/telegram/tests/test_monitor.py
new file mode 100644
index 00000000..f5b3a820
--- /dev/null
+++ b/src/aipass/skills/lib/telegram/tests/test_monitor.py
@@ -0,0 +1,487 @@
+# =================== AIPass ====================
+# Name: test_monitor.py
+# Description: Tests for /monitor command — system-wide log subscription (DPLAN-0221)
+# Version: 1.0.0
+# Created: 2026-06-29
+# Modified: 2026-06-29
+# =============================================
+
+"""
+Tests for /monitor command — system-wide log subscription feature (DPLAN-0221).
+
+Tests cover:
+  - Subscribe persists {chat_id, mode} to local file
+  - _boot_monitor reads persisted subscription and starts the streamer
+  - LogStreamer level_filter: default keeps WARNING/ERROR/CRITICAL, drops INFO
+  - LogStreamer level_filter: 'all' keeps everything
+  - LogStreamer system_wide globs *.log (not branch-specific)
+  - /monitor off clears the subscription
+  - /monitor command routing (on, all, off, status, bare)
+"""
+
+from pathlib import Path
+
+import pytest
+from unittest.mock import patch, MagicMock
+
+from apps.handlers.log_streamer import LogStreamer  # type: ignore[import-not-found]
+
+
+# =============================================
+# HELPERS
+# =============================================
+
+
+@pytest.fixture
+def _patch_base_bot_deps(tmp_path):
+    """Patch heavy BaseBot dependencies to allow lightweight instantiation."""
+    sub_file = tmp_path / "monitor_sub.json"
+    patches = [
+        patch("apps.handlers.base_bot.PENDING_DIR", tmp_path),
+        patch("apps.handlers.base_bot.signal.signal"),
+        patch("apps.handlers.base_bot.atexit.register"),
+    ]
+    for p in patches:
+        p.start()
+    yield sub_file
+    for p in patches:
+        p.stop()
+
+
+def _make_bot(tmp_path, _patch_base_bot_deps):
+    """Create a BaseBot with monitor subscription redirected to tmp_path."""
+    from apps.handlers.base_bot import BaseBot  # type: ignore[import-not-found]
+
+    workdir = tmp_path / "workdir"
+    workdir.mkdir()
+    bot = BaseBot(
+        bot_id="monitor_test",
+        bot_token="123:FAKETOKEN",
+        work_dir=workdir,
+        bot_name="Monitor Test Bot",
+        allowed_user_ids=[111],
+        branch_name=None,
+    )
+    # Redirect subscription file to tmp_path so tests don't touch real HOME
+    sub_file: Path = _patch_base_bot_deps
+    bot._monitor_subscription_file = lambda: sub_file  # type: ignore[assignment]
+    return bot
+
+
+# =============================================
+# 1. SUBSCRIBE PERSISTS VIA @API SET_SECRET
+# =============================================
+
+
+class TestSubscribePersists:
+    """Verify _monitor_subscribe persists {chat_id, mode} and can be reloaded."""
+
+    def test_subscribe_writes_file(self, tmp_path, _patch_base_bot_deps):
+        bot = _make_bot(tmp_path, _patch_base_bot_deps)
+        sub_file: Path = _patch_base_bot_deps
+        with (
+            patch.object(bot, "send_message"),
+            patch("apps.handlers.base_bot.LogStreamer") as MockStreamer,
+        ):
+            MockStreamer.return_value = MagicMock()
+            bot._monitor_subscribe(42, "default")
+
+            import json
+
+            data = json.loads(sub_file.read_text())
+            assert data == {"chat_id": 42, "mode": "default"}
+
+    def test_subscribe_roundtrip_reload(self, tmp_path, _patch_base_bot_deps):
+        """Written file can be read back by _load_monitor_subscription."""
+        bot = _make_bot(tmp_path, _patch_base_bot_deps)
+        sub_file: Path = _patch_base_bot_deps
+        import json
+
+        sub_file.write_text(json.dumps({"chat_id": 42, "mode": "all"}))
+
+        result = bot._load_monitor_subscription()
+
+        assert result == {"chat_id": 42, "mode": "all"}
+        assert result["chat_id"] == 42
+        assert result["mode"] == "all"
+
+    def test_subscribe_starts_streamer(self, tmp_path, _patch_base_bot_deps):
+        bot = _make_bot(tmp_path, _patch_base_bot_deps)
+        with (
+            patch.object(bot, "send_message"),
+            patch("apps.handlers.base_bot.LogStreamer") as MockStreamer,
+        ):
+            mock_instance = MagicMock()
+            MockStreamer.return_value = mock_instance
+
+            bot._monitor_subscribe(42, "default")
+
+            MockStreamer.assert_called_once_with(
+                "123:FAKETOKEN",
+                42,
+                branch_name="monitor",
+                system_wide=True,
+                level_filter="default",
+            )
+            mock_instance.start.assert_called_once()
+            assert bot._monitor_streamer is mock_instance
+
+    def test_subscribe_sends_confirmation(self, tmp_path, _patch_base_bot_deps):
+        bot = _make_bot(tmp_path, _patch_base_bot_deps)
+        with (
+            patch.object(bot, "send_message") as mock_send,
+            patch("apps.handlers.base_bot.LogStreamer", return_value=MagicMock()),
+        ):
+            bot._monitor_subscribe(42, "default")
+            mock_send.assert_called_once()
+            msg = mock_send.call_args[0][1]
+            assert "errors & warnings" in msg
+
+    def test_subscribe_stops_existing_streamer(self, tmp_path, _patch_base_bot_deps):
+        bot = _make_bot(tmp_path, _patch_base_bot_deps)
+        old_streamer = MagicMock()
+        bot._monitor_streamer = old_streamer
+
+        with (
+            patch.object(bot, "send_message"),
+            patch("apps.handlers.base_bot.LogStreamer", return_value=MagicMock()),
+        ):
+            bot._monitor_subscribe(42, "all")
+            old_streamer.stop.assert_called_once()
+
+    def test_subscribe_aborts_on_save_failure(self, tmp_path, _patch_base_bot_deps):
+        bot = _make_bot(tmp_path, _patch_base_bot_deps)
+        with (
+            patch.object(bot, "_save_monitor_subscription", return_value=False),
+            patch.object(bot, "send_message") as mock_send,
+        ):
+            bot._monitor_subscribe(42, "default")
+            msg = mock_send.call_args[0][1]
+            assert "Failed" in msg
+            assert bot._monitor_streamer is None
+
+
+# =============================================
+# 2. BOOT-START READS SUBSCRIPTION
+# =============================================
+
+
+class TestBootMonitor:
+    """Verify _boot_monitor reads persisted sub and starts streamer."""
+
+    def test_boot_starts_streamer_from_persisted(self, tmp_path, _patch_base_bot_deps):
+        bot = _make_bot(tmp_path, _patch_base_bot_deps)
+        sub_file: Path = _patch_base_bot_deps
+        import json
+
+        sub_file.write_text(json.dumps({"chat_id": 42, "mode": "default"}))
+
+        with patch("apps.handlers.base_bot.LogStreamer") as MockStreamer:
+            mock_instance = MagicMock()
+            MockStreamer.return_value = mock_instance
+
+            bot._boot_monitor()
+
+            MockStreamer.assert_called_once_with(
+                "123:FAKETOKEN",
+                42,
+                branch_name="monitor",
+                system_wide=True,
+                level_filter="default",
+            )
+            mock_instance.start.assert_called_once()
+            assert bot._monitor_streamer is mock_instance
+
+    def test_boot_noop_when_no_subscription(self, tmp_path, _patch_base_bot_deps):
+        bot = _make_bot(tmp_path, _patch_base_bot_deps)
+        # No file written — subscription absent
+        with patch("apps.handlers.base_bot.LogStreamer") as MockStreamer:
+            bot._boot_monitor()
+            MockStreamer.assert_not_called()
+            assert bot._monitor_streamer is None
+
+    def test_boot_noop_when_empty_subscription(self, tmp_path, _patch_base_bot_deps):
+        bot = _make_bot(tmp_path, _patch_base_bot_deps)
+        sub_file: Path = _patch_base_bot_deps
+        sub_file.write_text("{}")
+
+        with patch("apps.handlers.base_bot.LogStreamer") as MockStreamer:
+            bot._boot_monitor()
+            MockStreamer.assert_not_called()
+
+    def test_boot_respects_mode_all(self, tmp_path, _patch_base_bot_deps):
+        bot = _make_bot(tmp_path, _patch_base_bot_deps)
+        sub_file: Path = _patch_base_bot_deps
+        import json
+
+        sub_file.write_text(json.dumps({"chat_id": 99, "mode": "all"}))
+
+        with patch("apps.handlers.base_bot.LogStreamer") as MockStreamer:
+            MockStreamer.return_value = MagicMock()
+            bot._boot_monitor()
+            MockStreamer.assert_called_once_with(
+                "123:FAKETOKEN",
+                99,
+                branch_name="monitor",
+                system_wide=True,
+                level_filter="all",
+            )
+
+
+# =============================================
+# 3. LEVEL FILTER
+# =============================================
+
+
+class TestLevelFilter:
+    """Verify LogStreamer._filter_lines keeps/drops by level."""
+
+    @pytest.fixture
+    def streamer_default(self, tmp_path):
+        logs_dir = tmp_path / "system_logs"
+        logs_dir.mkdir()
+        with patch("apps.handlers.log_streamer.SYSTEM_LOGS_DIR", logs_dir):
+            return LogStreamer("tok", 1, "x", system_wide=True, level_filter="default")
+
+    @pytest.fixture
+    def streamer_all(self, tmp_path):
+        logs_dir = tmp_path / "system_logs"
+        logs_dir.mkdir()
+        with patch("apps.handlers.log_streamer.SYSTEM_LOGS_DIR", logs_dir):
+            return LogStreamer("tok", 1, "x", system_wide=True, level_filter="all")
+
+    def test_default_keeps_warning(self, streamer_default):
+        lines = ["2026-06-24 | WARNING | something bad"]
+        assert streamer_default._filter_lines(lines) == lines
+
+    def test_default_keeps_error(self, streamer_default):
+        lines = ["2026-06-24 | ERROR | crash"]
+        assert streamer_default._filter_lines(lines) == lines
+
+    def test_default_keeps_critical(self, streamer_default):
+        lines = ["2026-06-24 | CRITICAL | meltdown"]
+        assert streamer_default._filter_lines(lines) == lines
+
+    def test_default_drops_info(self, streamer_default):
+        lines = ["2026-06-24 | INFO | all is well"]
+        assert streamer_default._filter_lines(lines) == []
+
+    def test_default_drops_debug(self, streamer_default):
+        lines = ["2026-06-24 | DEBUG | verbose detail"]
+        assert streamer_default._filter_lines(lines) == []
+
+    def test_default_mixed_keeps_only_high_severity(self, streamer_default):
+        lines = [
+            "2026-06-24 | INFO | routine",
+            "2026-06-24 | WARNING | watch out",
+            "2026-06-24 | DEBUG | trace",
+            "2026-06-24 | ERROR | failure",
+        ]
+        result = streamer_default._filter_lines(lines)
+        assert len(result) == 2
+        assert "WARNING" in result[0]
+        assert "ERROR" in result[1]
+
+    def test_all_keeps_everything(self, streamer_all):
+        lines = [
+            "2026-06-24 | INFO | routine",
+            "2026-06-24 | WARNING | watch out",
+            "2026-06-24 | DEBUG | trace",
+        ]
+        assert streamer_all._filter_lines(lines) == lines
+
+
+# =============================================
+# 4. SYSTEM-WIDE GLOB
+# =============================================
+
+
+class TestSystemWideGlob:
+    """Verify system_wide=True globs *.log, not just branch-specific."""
+
+    def test_system_wide_finds_all_logs(self, tmp_path):
+        logs_dir = tmp_path / "system_logs"
+        logs_dir.mkdir()
+        (logs_dir / "api_main.log").write_text("a\n")
+        (logs_dir / "prax_main.log").write_text("b\n")
+        (logs_dir / "trigger_events.log").write_text("c\n")
+
+        with patch("apps.handlers.log_streamer.SYSTEM_LOGS_DIR", logs_dir):
+            s = LogStreamer("tok", 1, "monitor", system_wide=True, level_filter="all")
+
+        assert len(s.log_positions) == 3
+
+    def test_non_system_wide_finds_only_branch(self, tmp_path):
+        logs_dir = tmp_path / "system_logs"
+        logs_dir.mkdir()
+        (logs_dir / "api_main.log").write_text("a\n")
+        (logs_dir / "prax_main.log").write_text("b\n")
+
+        with patch("apps.handlers.log_streamer.SYSTEM_LOGS_DIR", logs_dir):
+            s = LogStreamer("tok", 1, "api", system_wide=False, level_filter="all")
+
+        assert len(s.log_positions) == 1
+        assert any("api_main" in p for p in s.log_positions)
+
+    def test_system_wide_reads_new_lines_from_all(self, tmp_path):
+        logs_dir = tmp_path / "system_logs"
+        logs_dir.mkdir()
+        f1 = logs_dir / "api_main.log"
+        f2 = logs_dir / "prax_main.log"
+        f1.write_text("")
+        f2.write_text("")
+
+        with patch("apps.handlers.log_streamer.SYSTEM_LOGS_DIR", logs_dir):
+            s = LogStreamer("tok", 1, "monitor", system_wide=True, level_filter="all")
+
+        f1.write_text("api line\n")
+        f2.write_text("prax line\n")
+
+        with patch("apps.handlers.log_streamer.SYSTEM_LOGS_DIR", logs_dir):
+            lines = s._read_new_lines()
+
+        assert "api line" in lines
+        assert "prax line" in lines
+
+
+# =============================================
+# 5. MONITOR OFF CLEARS SUBSCRIPTION
+# =============================================
+
+
+class TestMonitorOff:
+    """Verify /monitor off stops streamer and clears persisted state."""
+
+    def test_off_stops_streamer(self, tmp_path, _patch_base_bot_deps):
+        bot = _make_bot(tmp_path, _patch_base_bot_deps)
+        mock_streamer = MagicMock()
+        bot._monitor_streamer = mock_streamer
+
+        with patch.object(bot, "send_message"):
+            bot._monitor_unsubscribe(42)
+
+        mock_streamer.stop.assert_called_once()
+        assert bot._monitor_streamer is None
+
+    def test_off_clears_subscription(self, tmp_path, _patch_base_bot_deps):
+        bot = _make_bot(tmp_path, _patch_base_bot_deps)
+        sub_file: Path = _patch_base_bot_deps
+        import json
+
+        sub_file.write_text(json.dumps({"chat_id": 42, "mode": "default"}))
+
+        with patch.object(bot, "send_message"):
+            bot._monitor_unsubscribe(42)
+
+        assert not sub_file.exists()
+
+    def test_off_sends_confirmation(self, tmp_path, _patch_base_bot_deps):
+        bot = _make_bot(tmp_path, _patch_base_bot_deps)
+        with patch.object(bot, "send_message") as mock_send:
+            bot._monitor_unsubscribe(42)
+
+        mock_send.assert_called_once()
+        assert "unsubscribed" in mock_send.call_args[0][1].lower()
+
+    def test_off_safe_when_no_streamer(self, tmp_path, _patch_base_bot_deps):
+        bot = _make_bot(tmp_path, _patch_base_bot_deps)
+        assert bot._monitor_streamer is None
+
+        with patch.object(bot, "send_message"):
+            bot._monitor_unsubscribe(42)
+
+        assert bot._monitor_streamer is None
+
+
+# =============================================
+# 6. COMMAND ROUTING
+# =============================================
+
+
+class TestMonitorCommandRouting:
+    """Verify _handle_monitor_command routes subcommands correctly."""
+
+    def test_on_routes_to_subscribe_default(self, tmp_path, _patch_base_bot_deps):
+        bot = _make_bot(tmp_path, _patch_base_bot_deps)
+        with patch.object(bot, "_monitor_subscribe") as mock_sub:
+            bot._handle_monitor_command(42, "on")
+            mock_sub.assert_called_once_with(42, mode="default")
+
+    def test_all_routes_to_subscribe_all(self, tmp_path, _patch_base_bot_deps):
+        bot = _make_bot(tmp_path, _patch_base_bot_deps)
+        with patch.object(bot, "_monitor_subscribe") as mock_sub:
+            bot._handle_monitor_command(42, "all")
+            mock_sub.assert_called_once_with(42, mode="all")
+
+    def test_off_routes_to_unsubscribe(self, tmp_path, _patch_base_bot_deps):
+        bot = _make_bot(tmp_path, _patch_base_bot_deps)
+        with patch.object(bot, "_monitor_unsubscribe") as mock_unsub:
+            bot._handle_monitor_command(42, "off")
+            mock_unsub.assert_called_once_with(42)
+
+    def test_status_routes_to_status(self, tmp_path, _patch_base_bot_deps):
+        bot = _make_bot(tmp_path, _patch_base_bot_deps)
+        with patch.object(bot, "_monitor_status") as mock_stat:
+            bot._handle_monitor_command(42, "status")
+            mock_stat.assert_called_once_with(42)
+
+    def test_bare_monitor_shows_help(self, tmp_path, _patch_base_bot_deps):
+        bot = _make_bot(tmp_path, _patch_base_bot_deps)
+        with patch.object(bot, "send_message") as mock_send:
+            bot._handle_monitor_command(42, "")
+            msg = mock_send.call_args[0][1]
+            assert "/monitor on" in msg
+            assert "/monitor off" in msg
+
+    def test_unknown_subcommand_shows_help(self, tmp_path, _patch_base_bot_deps):
+        bot = _make_bot(tmp_path, _patch_base_bot_deps)
+        with patch.object(bot, "send_message") as mock_send:
+            bot._handle_monitor_command(42, "banana")
+            msg = mock_send.call_args[0][1]
+            assert "/monitor on" in msg
+
+
+# =============================================
+# 7. STATUS REPORTING
+# =============================================
+
+
+class TestMonitorStatus:
+    """Verify _monitor_status shows correct state."""
+
+    def test_status_when_not_subscribed(self, tmp_path, _patch_base_bot_deps):
+        bot = _make_bot(tmp_path, _patch_base_bot_deps)
+        # No file written — no subscription
+        with patch.object(bot, "send_message") as mock_send:
+            bot._monitor_status(42)
+            msg = mock_send.call_args[0][1]
+            assert "not subscribed" in msg
+
+    def test_status_when_subscribed_and_running(self, tmp_path, _patch_base_bot_deps):
+        bot = _make_bot(tmp_path, _patch_base_bot_deps)
+        sub_file: Path = _patch_base_bot_deps
+        import json
+
+        sub_file.write_text(json.dumps({"chat_id": 42, "mode": "default"}))
+        mock_streamer = MagicMock()
+        mock_streamer._running = True
+        bot._monitor_streamer = mock_streamer
+
+        with patch.object(bot, "send_message") as mock_send:
+            bot._monitor_status(42)
+            msg = mock_send.call_args[0][1]
+            assert "streaming" in msg
+            assert "this chat" in msg
+
+    def test_status_shows_mode_label(self, tmp_path, _patch_base_bot_deps):
+        bot = _make_bot(tmp_path, _patch_base_bot_deps)
+        sub_file: Path = _patch_base_bot_deps
+        import json
+
+        sub_file.write_text(json.dumps({"chat_id": 42, "mode": "all"}))
+        bot._monitor_streamer = MagicMock(_running=True)
+
+        with patch.object(bot, "send_message") as mock_send:
+            bot._monitor_status(42)
+            msg = mock_send.call_args[0][1]
+            assert "firehose" in msg
diff --git a/src/aipass/skills/.aipass/skills/telegram/tests/test_multi_bot.py b/src/aipass/skills/lib/telegram/tests/test_multi_bot.py
similarity index 94%
rename from src/aipass/skills/.aipass/skills/telegram/tests/test_multi_bot.py
rename to src/aipass/skills/lib/telegram/tests/test_multi_bot.py
index dc253dc2..3f6fb88e 100644
--- a/src/aipass/skills/.aipass/skills/telegram/tests/test_multi_bot.py
+++ b/src/aipass/skills/lib/telegram/tests/test_multi_bot.py
@@ -1,9 +1,17 @@
+# =================== AIPass ====================
+# Name: test_multi_bot.py
+# Description: Comprehensive tests for BaseBot and BranchPlugin
+# Version: 1.0.0
+# Created: 2026-06-15
+# Modified: 2026-06-29
+# =============================================
+
 """
 Comprehensive pytest tests for BaseBot and BranchPlugin.
 
 Tests cover:
   - BaseBot initialization and attribute assignment
-  - Default hook methods (on_message, on_response, on_session_create)
+  - Default hook methods (on_message, on_response)
   - Security: is_user_allowed (allowlist), check_rate_limit (sliding window)
   - BranchPlugin hook overrides (message prefixing, response tagging)
   - Pending file creation and JSON content
@@ -25,8 +33,8 @@ import time
 import pytest
 from unittest.mock import patch, MagicMock
 
-from apps.handlers.base_bot import BaseBot
-from apps.handlers.branch_plugin import BranchPlugin
+from apps.handlers.base_bot import BaseBot  # type: ignore[import-not-found]
+from apps.handlers.branch_plugin import BranchPlugin  # type: ignore[import-not-found]
 
 
 # =============================================
@@ -173,11 +181,6 @@ class TestBaseBotHooks:
     def test_on_response_empty_string(self, base_bot):
         assert base_bot.on_response("") == ""
 
-    def test_on_session_create_does_nothing(self, base_bot, tmp_path):
-        # Should return None and not raise
-        result = base_bot.on_session_create("test-session", tmp_path)
-        assert result is None
-
     def test_get_custom_commands_returns_create_and_cancel(self, base_bot):
         commands = base_bot.get_custom_commands()
         assert "create" in commands
@@ -300,13 +303,6 @@ class TestBranchPluginHooks:
         result = branch_bot.on_response(response)
         assert result == f"@dev_central\n{response}"
 
-    @patch.object(BranchPlugin, "inject_message")
-    @patch("apps.handlers.branch_plugin.time.sleep")
-    def test_on_session_create_injects_hi(self, mock_sleep, mock_inject, branch_bot):
-        branch_bot.on_session_create("telegram-dev_central", Path("/tmp/test"))
-        mock_sleep.assert_called_once_with(2)
-        mock_inject.assert_called_once_with("hi")
-
     def test_branch_plugin_inherits_base_bot(self, branch_bot):
         assert isinstance(branch_bot, BaseBot)
         assert branch_bot.bot_id == "dev_central"
@@ -587,25 +583,15 @@ class TestEnsureTmuxSession:
 
     @patch("apps.handlers.base_bot.time.sleep")
     @patch("apps.handlers.base_bot.subprocess.run")
-    def test_session_created_when_not_exists(self, mock_run, mock_sleep, base_bot):
-        """When session does not exist, create it, set env, launch Claude."""
-        call_count = [0]
-
-        def side_effect(cmd, **kwargs):
-            call_count[0] += 1
-            mock_result = MagicMock()
-            if "has-session" in cmd:
-                mock_result.returncode = 1  # Session does not exist
-                return mock_result
-            mock_result.returncode = 0
-            return mock_result
-
-        mock_run.side_effect = side_effect
+    def test_no_session_returns_false(self, mock_run, mock_sleep, base_bot):
+        """When no session exists, bot returns False (never spawns own brain)."""
+        mock_run.return_value = MagicMock(returncode=1)
 
         result = base_bot.ensure_tmux_session()
-        assert result is True
-        # Should have: has-session, new-session, send-keys (env), send-keys (claude)
-        assert mock_run.call_count >= 4
+        assert result is False
+        calls = [str(c) for c in mock_run.call_args_list]
+        for call in calls:
+            assert "new-session" not in call
 
     def test_session_refuses_nonexistent_work_dir(self, tmp_path):
         """When work_dir doesn't exist, ensure_tmux_session returns False."""
@@ -619,60 +605,10 @@ class TestEnsureTmuxSession:
         result = bot.ensure_tmux_session()
         assert result is False
 
-    @patch("apps.handlers.base_bot.time.sleep")
-    @patch("apps.handlers.base_bot.subprocess.run")
-    def test_session_creation_calls_on_session_create(self, mock_run, mock_sleep, base_bot):
-        """After creating a session, on_session_create hook should be called."""
-
-        def side_effect(cmd, **kwargs):
-            mock_result = MagicMock()
-            if "has-session" in cmd:
-                mock_result.returncode = 1
-                return mock_result
-            mock_result.returncode = 0
-            return mock_result
-
-        mock_run.side_effect = side_effect
-
-        with patch.object(base_bot, "on_session_create") as mock_hook:
-            base_bot.ensure_tmux_session()
-            mock_hook.assert_called_once_with(base_bot.session_name, base_bot.work_dir)
-
-    @patch("apps.handlers.base_bot.time.sleep")
-    @patch("apps.handlers.base_bot.subprocess.run")
-    def test_session_creation_failure(self, mock_run, mock_sleep, base_bot):
-        """CalledProcessError during new-session returns False."""
-        import subprocess as sp
-
-        def side_effect(cmd, **kwargs):
-            if "has-session" in cmd:
-                mock_result = MagicMock()
-                mock_result.returncode = 1
-                return mock_result
-            if "new-session" in cmd:
-                raise sp.CalledProcessError(1, cmd, stderr=b"error")
-            return MagicMock(returncode=0)
-
-        mock_run.side_effect = side_effect
-        result = base_bot.ensure_tmux_session()
-        assert result is False
-
-    @patch("apps.handlers.base_bot.time.sleep")
-    @patch("apps.handlers.base_bot.subprocess.run")
-    def test_tmux_not_found(self, mock_run, mock_sleep, base_bot):
+    def test_tmux_not_found_returns_false(self, base_bot):
         """FileNotFoundError (tmux not installed) returns False."""
-
-        def side_effect(cmd, **kwargs):
-            if "has-session" in cmd:
-                mock_result = MagicMock()
-                mock_result.returncode = 1
-                return mock_result
-            if "new-session" in cmd:
-                raise FileNotFoundError("tmux not found")
-            return MagicMock(returncode=0)
-
-        mock_run.side_effect = side_effect
-        result = base_bot.ensure_tmux_session()
+        with patch("apps.handlers.base_bot.subprocess.run", side_effect=FileNotFoundError("tmux")):
+            result = base_bot.ensure_tmux_session()
         assert result is False
 
 
@@ -1553,6 +1489,20 @@ class TestCreateAutomated:
         state = self.bot._create_state[self.chat_id]
         assert state["branch_name"] == "flow"
 
+    @patch("apps.handlers.base_bot.get_bot_by_branch", return_value=None)
+    @patch("apps.handlers.base_bot.validate_branch")
+    @patch("apps.handlers.base_bot.check_telethon_setup")
+    def test_manual_fallback_message_shows_reason(self, mock_check, mock_validate, mock_get_bot):
+        """Manual fallback message includes the reason automation is unavailable."""
+        mock_check.return_value = (False, "Telethon library not installed. Run: pip install telethon")
+        mock_validate.return_value = {"name": "flow", "path": "/home/aipass/flow"}
+
+        self.bot._handle_create_command(self.chat_id, "chat flow")
+
+        msg = self.bot.send_message.call_args[0][1]
+        assert "Telethon library not installed" in msg
+        assert "Falling back to manual token flow" in msg
+
     @patch("apps.handlers.base_bot.create_bot")
     @patch("apps.handlers.base_bot.create_bot_via_botfather")
     def test_automated_success_message_contains_service_info(self, mock_bf_create, mock_create_bot):
@@ -1636,24 +1586,15 @@ class TestSharedSession:
 
     @patch("apps.handlers.base_bot.time.sleep")
     @patch("apps.handlers.base_bot.subprocess.run")
-    def test_ensure_falls_back_when_shared_missing(self, mock_run, mock_sleep):
-        """When shared session doesn't exist, falls back to own session."""
-
-        def side_effect(cmd, **kwargs):
-            mock = MagicMock()
-            if "has-session" in cmd and cmd[-1] == "pc":
-                mock.returncode = 1  # shared session not found
-            elif "has-session" in cmd:
-                mock.returncode = 1  # own session not found either
-            else:
-                mock.returncode = 0  # creation succeeds
-            return mock
-
-        mock_run.side_effect = side_effect
+    def test_ensure_returns_false_when_shared_missing(self, mock_run, mock_sleep):
+        """When shared session doesn't exist and no presence, returns False (no spawn)."""
+        mock_run.return_value = MagicMock(returncode=1)
         result = self.bot.ensure_tmux_session()
-        assert result is True
-        assert self.bot.session_name == "telegram-dev_central"
+        assert result is False
         assert self.bot._using_shared_session is False
+        calls = [str(c) for c in mock_run.call_args_list]
+        for call in calls:
+            assert "new-session" not in call
 
     @patch("apps.handlers.base_bot.subprocess.run")
     def test_inject_uses_shared_session_name(self, mock_run):
diff --git a/src/aipass/skills/.aipass/skills/telegram/tests/test_multibot_config.py b/src/aipass/skills/lib/telegram/tests/test_multibot_config.py
similarity index 78%
rename from src/aipass/skills/.aipass/skills/telegram/tests/test_multibot_config.py
rename to src/aipass/skills/lib/telegram/tests/test_multibot_config.py
index a2197524..46ddfe74 100644
--- a/src/aipass/skills/.aipass/skills/telegram/tests/test_multibot_config.py
+++ b/src/aipass/skills/lib/telegram/tests/test_multibot_config.py
@@ -336,7 +336,7 @@ class TestHandleStandardCommand:
             bot_name="AIPass Assistant Bot",
         )
         assert isinstance(result, str)
-        assert "Commands:" in result
+        assert "Available commands:" in result
 
     def test_new_returns_tuple(self) -> None:
         """The 'new' command returns tuple of ('new', response_text)."""
@@ -411,7 +411,7 @@ class TestBuildHelpText:
     def test_includes_all_standard_commands(self) -> None:
         """Help text includes all standard commands."""
         result = build_help_text()
-        assert "Commands:" in result
+        assert "Available commands:" in result
         for cmd in STANDARD_COMMANDS:
             assert f"/{cmd}" in result
 
@@ -430,7 +430,7 @@ class TestBuildHelpText:
     def test_includes_footer(self) -> None:
         """Help text includes the help footer."""
         result = build_help_text()
-        assert "Send any message to chat with Claude" in result
+        assert "Just send any message to talk to me" in result
 
 
 # =============================================
@@ -463,7 +463,7 @@ class TestBuildWelcomeText:
             bot_name="TestBot",
             branch_name="test",
         )
-        assert "Commands:" in result
+        assert "Available commands:" in result
         for cmd in STANDARD_COMMANDS:
             assert f"/{cmd}" in result
 
@@ -792,3 +792,202 @@ class TestGetStatusAndGetAllBots:
         result = bot_operations.get_all_bots()
         assert result == expected
         mock_list_bots.assert_called_once()
+
+
+# =============================================
+# CREATE_BOT -> LOAD_BOT_CONFIG ROUND-TRIP
+# =============================================
+
+
+class TestCreateBotRoundTrip:
+    """Prove GAP1 is closed: create_bot persists config that load_bot_config reads."""
+
+    @patch("apps.handlers.bot_factory.start_bot_process", return_value=True)
+    @patch("apps.handlers.bot_factory.enable_service", return_value=True)
+    @patch("apps.handlers.bot_factory.set_bot_commands", return_value=True)
+    @patch("apps.handlers.bot_factory.validate_token")
+    @patch("apps.handlers.bot_factory.ensure_registry")
+    def test_create_then_load_roundtrip(
+        self,
+        mock_ensure_registry,
+        mock_validate_token,
+        mock_set_commands,
+        mock_enable,
+        mock_start,
+        tmp_path,
+        monkeypatch,
+    ):
+        """After create_bot, load_bot_config returns the persisted config."""
+        from apps.handlers import bot_factory, config as tg_config
+
+        mock_validate_token.return_value = {"username": "test_bot", "id": 123}
+
+        monkeypatch.setattr(bot_factory, "_BOT_CONFIG_DIR", tmp_path)
+
+        secrets_store = {}
+
+        def fake_set_secret(provider, slug, value, *, as_json=False):
+            secrets_store[f"{provider}/{slug}"] = value
+            return tmp_path / f"{slug}.json"
+
+        def fake_get_secret(provider, slug, *, as_json=False):
+            return secrets_store.get(f"{provider}/{slug}")
+
+        monkeypatch.setattr(bot_factory, "_api_set_secret", fake_set_secret)
+        monkeypatch.setattr(tg_config, "_api_get_secret", fake_get_secret)
+
+        monkeypatch.setattr("apps.handlers.bot_registry.REGISTRY_DIR", tmp_path / "state")
+        monkeypatch.setattr(
+            "apps.handlers.bot_registry.REGISTRY_FILE",
+            tmp_path / "state" / "_registry.json",
+        )
+
+        result = bot_factory.create_bot(
+            bot_id="roundtrip_bot",
+            bot_token="111:AAA-test-token",
+            branch_name=None,
+            allowed_user_ids=[42],
+        )
+        assert result is not None
+        assert result["bot_id"] == "roundtrip_bot"
+
+        loaded = tg_config.load_bot_config("roundtrip_bot")
+        assert loaded is not None
+        assert loaded["bot_id"] == "roundtrip_bot"
+        assert loaded["bot_token"] == "111:AAA-test-token"
+        assert loaded["allowed_user_ids"] == [42]
+
+    @patch("apps.handlers.bot_factory.validate_token")
+    @patch("apps.handlers.bot_factory.ensure_registry")
+    def test_create_fails_loud_on_set_secret_error(
+        self,
+        mock_ensure_registry,
+        mock_validate_token,
+        tmp_path,
+        monkeypatch,
+    ):
+        """create_bot returns None and logs error if set_secret raises."""
+        from apps.handlers import bot_factory
+
+        mock_validate_token.return_value = {"username": "test_bot", "id": 123}
+        monkeypatch.setattr(bot_factory, "_BOT_CONFIG_DIR", tmp_path)
+
+        def failing_set_secret(*args, **kwargs):
+            raise OSError("permission denied")
+
+        monkeypatch.setattr(bot_factory, "_api_set_secret", failing_set_secret)
+
+        result = bot_factory.create_bot(
+            bot_id="fail_bot",
+            bot_token="222:BBB-test-token",
+        )
+        assert result is None
+
+
+# =============================================
+# COMMAND MENU SYNC + POPULATE TESTS
+# =============================================
+
+
+class TestCommandMenuSync:
+    """Verify /help text and Telegram menu use the same single-source command list."""
+
+    def test_menu_and_help_have_same_commands(self):
+        """The command names in build_botfather_commands match those in build_help_text."""
+        from apps.handlers.telegram_standards import (
+            build_botfather_commands,
+            build_help_text,
+        )
+        from apps.handlers.base_bot import BaseBot
+
+        custom = BaseBot.get_custom_commands(None)
+        menu_commands = build_botfather_commands(custom_commands=custom)
+        menu_names = {c["command"] for c in menu_commands}
+
+        help_text = build_help_text(custom_commands=custom)
+        help_names = set()
+        for line in help_text.split("\n"):
+            if line.startswith("/"):
+                cmd = line.split(" ")[0].lstrip("/").split("-")[0].strip()
+                help_names.add(cmd)
+
+        assert menu_names == help_names
+
+    def test_help_contains_enriched_descriptions(self):
+        """The /help text includes the enriched descriptions."""
+        from apps.handlers.telegram_standards import build_help_text
+        from apps.handlers.base_bot import BaseBot
+
+        custom = BaseBot.get_custom_commands(None)
+        help_text = build_help_text(custom_commands=custom)
+
+        assert "what this bot is and how to use it" in help_text.lower()
+        assert "show every command" in help_text.lower()
+        assert "fresh conversation" in help_text.lower()
+        assert "branch, uptime" in help_text.lower()
+        assert "create a telegram bot" in help_text.lower()
+        assert "cancel an in-progress" in help_text.lower()
+
+    def test_help_footer_updated(self):
+        """The /help footer uses the enriched text."""
+        from apps.handlers.telegram_standards import build_help_text
+
+        help_text = build_help_text()
+        assert "Just send any message to talk to me" in help_text
+
+    def test_create_bot_uses_single_source(self):
+        """create_bot calls set_bot_commands with build_botfather_commands output."""
+        from apps.handlers import bot_factory
+        from apps.handlers.telegram_standards import build_botfather_commands
+
+        expected = build_botfather_commands()
+        with patch.object(bot_factory, "set_bot_commands") as mock_set:
+            with patch.object(bot_factory, "validate_token", return_value={"username": "t", "id": 1}):
+                with patch.object(bot_factory, "ensure_registry"):
+                    with patch.object(bot_factory, "register_bot", return_value=True):
+                        with patch.object(bot_factory, "_api_set_secret", return_value=None):
+                            with patch.object(bot_factory, "enable_service"):
+                                with patch.object(bot_factory, "start_bot_process", return_value=True):
+                                    bot_factory._BOT_CONFIG_DIR.mkdir(parents=True, exist_ok=True)
+                                    bot_factory.create_bot("sync_test", "999:ZZZ-token")
+
+            mock_set.assert_called_once_with("999:ZZZ-token", expected)
+
+
+class TestBaseBotStartupMenu:
+    """Verify base_bot sets command menu on startup."""
+
+    @patch("apps.handlers.base_bot.set_bot_commands", return_value=True)
+    def test_set_command_menu_called_on_startup(self, mock_set_commands):
+        """_set_command_menu calls set_bot_commands with merged commands."""
+        from apps.handlers.base_bot import BaseBot
+        from apps.handlers.telegram_standards import build_botfather_commands
+
+        bot = BaseBot.__new__(BaseBot)
+        bot.bot_token = "123:ABC"
+        bot.custom_commands = {}
+
+        bot._set_command_menu()
+
+        mock_set_commands.assert_called_once()
+        actual_commands = mock_set_commands.call_args[0][1]
+        expected = build_botfather_commands(custom_commands=bot.get_custom_commands())
+        assert actual_commands == expected
+
+    @patch("apps.handlers.base_bot.set_bot_commands", return_value=True)
+    def test_menu_includes_custom_commands(self, mock_set_commands):
+        """Menu includes /create and /cancel from get_custom_commands."""
+        from apps.handlers.base_bot import BaseBot
+
+        bot = BaseBot.__new__(BaseBot)
+        bot.bot_token = "123:ABC"
+        bot.custom_commands = {}
+
+        bot._set_command_menu()
+
+        actual_commands = mock_set_commands.call_args[0][1]
+        cmd_names = {c["command"] for c in actual_commands}
+        assert "create" in cmd_names
+        assert "cancel" in cmd_names
+        assert "start" in cmd_names
+        assert "help" in cmd_names
diff --git a/src/aipass/skills/.aipass/skills/telegram/tests/test_multibot_integration.py b/src/aipass/skills/lib/telegram/tests/test_multibot_integration.py
similarity index 100%
rename from src/aipass/skills/.aipass/skills/telegram/tests/test_multibot_integration.py
rename to src/aipass/skills/lib/telegram/tests/test_multibot_integration.py
diff --git a/src/aipass/skills/lib/telegram/tests/test_presence_pointer.py b/src/aipass/skills/lib/telegram/tests/test_presence_pointer.py
new file mode 100644
index 00000000..9ff97bbd
--- /dev/null
+++ b/src/aipass/skills/lib/telegram/tests/test_presence_pointer.py
@@ -0,0 +1,563 @@
+# =================== AIPass ====================
+# Name: test_presence_pointer.py
+# Description: Tests for CC-native session discovery (DPLAN-0226) + transcript tail
+# Version: 2.0.0
+# Created: 2026-06-29
+# Modified: 2026-06-30
+# =============================================
+
+"""
+Tests for CC-native session discovery (DPLAN-0226).
+
+Covers:
+  - _discover_cc_session: enumerate ~/.claude/sessions, filter cwd, validate PID
+  - _is_pid_alive: PID liveness check
+  - _find_tmux_pane_by_cwd: tmux pane CWD scan
+  - _sanitize_path_for_cc: path sanitization for CC projects dir
+  - _resolve_cc_transcript_path: transcript JSONL path from session info
+  - _extract_assistant_text / _read_transcript_tail: transcript parsing
+  - ensure_tmux_session: CC-native-first resolution, legacy spawn retired
+  - handle_message: no-session error message
+"""
+
+import json
+import os
+from unittest.mock import MagicMock, patch
+
+import pytest
+
+from apps.handlers.base_bot import BaseBot  # type: ignore[import-not-found]
+
+
+# =============================================
+# Fixtures
+# =============================================
+
+
+@pytest.fixture
+def _patch_base_bot_deps(tmp_path):
+    """Patch signal and atexit for safe BaseBot construction."""
+    patches = [
+        patch("apps.handlers.base_bot.PENDING_DIR", tmp_path),
+        patch("apps.handlers.base_bot.signal.signal"),
+        patch("apps.handlers.base_bot.atexit.register"),
+    ]
+    for p in patches:
+        p.start()
+    yield
+    for p in patches:
+        p.stop()
+
+
+def _make_bot(tmp_path, _patch_base_bot_deps, branch_name="devpulse"):
+    """Create a BaseBot with test defaults."""
+    workdir = tmp_path / "workdir"
+    workdir.mkdir(exist_ok=True)
+    with patch("apps.handlers.base_bot.PENDING_DIR", tmp_path):
+        bot = BaseBot(
+            bot_id="cc_test",
+            bot_token="123:FAKETOKEN",
+            work_dir=workdir,
+            bot_name="CC Discovery Test Bot",
+            allowed_user_ids=[111],
+            branch_name=branch_name,
+        )
+    bot.send_message = MagicMock(return_value={"ok": True, "message_id": 1})
+    return bot
+
+
+def _write_cc_session(sessions_dir, pid, cwd, session_id="sess-001", started_at=1000, **extra):
+    """Write a CC session file at sessions_dir/<pid>.json."""
+    sessions_dir.mkdir(parents=True, exist_ok=True)
+    data = {
+        "pid": pid,
+        "sessionId": session_id,
+        "cwd": cwd,
+        "startedAt": started_at,
+        "kind": "interactive",
+        "name": "test-session",
+        **extra,
+    }
+    f = sessions_dir / f"{pid}.json"
+    f.write_text(json.dumps(data), encoding="utf-8")
+    return f
+
+
+def _write_transcript(projects_dir, cwd, session_id, lines):
+    """Write a transcript JSONL file at the CC-native path."""
+    slug = BaseBot._sanitize_path_for_cc(cwd)
+    transcript_dir = projects_dir / slug
+    transcript_dir.mkdir(parents=True, exist_ok=True)
+    transcript_file = transcript_dir / f"{session_id}.jsonl"
+    transcript_file.write_text("\n".join(json.dumps(item) for item in lines), encoding="utf-8")
+    return transcript_file
+
+
+# =============================================
+# 1. _discover_cc_session
+# =============================================
+
+
+class TestDiscoverCcSession:
+    """Enumerate ~/.claude/sessions, filter cwd, validate PID."""
+
+    def test_discovers_live_session(self, tmp_path, _patch_base_bot_deps):
+        """Finds a live session whose cwd matches the bot work directory."""
+        bot = _make_bot(tmp_path, _patch_base_bot_deps)
+        sessions_dir = tmp_path / "sessions"
+        _write_cc_session(sessions_dir, os.getpid(), str(bot.work_dir.resolve()))
+        with patch("apps.handlers.base_bot.CC_SESSIONS_DIR", sessions_dir):
+            result = bot._discover_cc_session()
+        assert result is not None
+        assert result["pid"] == os.getpid()
+        assert result["sessionId"] == "sess-001"
+
+    def test_returns_none_when_no_sessions_dir(self, tmp_path, _patch_base_bot_deps):
+        """Returns None when the sessions directory does not exist."""
+        bot = _make_bot(tmp_path, _patch_base_bot_deps)
+        fake_dir = tmp_path / "no_such_dir"
+        with patch("apps.handlers.base_bot.CC_SESSIONS_DIR", fake_dir):
+            result = bot._discover_cc_session()
+        assert result is None
+
+    def test_returns_none_when_no_matching_cwd(self, tmp_path, _patch_base_bot_deps):
+        """Returns None when no session file has a matching cwd."""
+        bot = _make_bot(tmp_path, _patch_base_bot_deps)
+        sessions_dir = tmp_path / "sessions"
+        _write_cc_session(sessions_dir, os.getpid(), "/some/other/dir")
+        with patch("apps.handlers.base_bot.CC_SESSIONS_DIR", sessions_dir):
+            result = bot._discover_cc_session()
+        assert result is None
+
+    def test_returns_none_for_dead_pid(self, tmp_path, _patch_base_bot_deps):
+        """Returns None when the session PID is no longer alive."""
+        bot = _make_bot(tmp_path, _patch_base_bot_deps)
+        sessions_dir = tmp_path / "sessions"
+        _write_cc_session(sessions_dir, 99999999, str(bot.work_dir.resolve()))
+        with patch("apps.handlers.base_bot.CC_SESSIONS_DIR", sessions_dir):
+            result = bot._discover_cc_session()
+        assert result is None
+
+    def test_picks_latest_when_multiple(self, tmp_path, _patch_base_bot_deps):
+        """Selects the session with the highest startedAt when multiple match."""
+        bot = _make_bot(tmp_path, _patch_base_bot_deps)
+        sessions_dir = tmp_path / "sessions"
+        cwd = str(bot.work_dir.resolve())
+        my_pid = os.getpid()
+        _write_cc_session(sessions_dir, my_pid, cwd, session_id="old", started_at=100)
+        _write_cc_session(sessions_dir, my_pid + 1, cwd, session_id="new", started_at=200)
+        with (
+            patch("apps.handlers.base_bot.CC_SESSIONS_DIR", sessions_dir),
+            patch.object(BaseBot, "_is_pid_alive", return_value=True),
+        ):
+            result = bot._discover_cc_session()
+        assert result is not None
+        assert result["sessionId"] == "new"
+
+    def test_skips_non_json_files(self, tmp_path, _patch_base_bot_deps):
+        """Ignores non-JSON files and files without numeric PID names."""
+        bot = _make_bot(tmp_path, _patch_base_bot_deps)
+        sessions_dir = tmp_path / "sessions"
+        sessions_dir.mkdir(parents=True)
+        (sessions_dir / "readme.txt").write_text("ignore me")
+        (sessions_dir / "notapid.json").write_text("{}")
+        with patch("apps.handlers.base_bot.CC_SESSIONS_DIR", sessions_dir):
+            result = bot._discover_cc_session()
+        assert result is None
+
+    def test_skips_corrupt_json(self, tmp_path, _patch_base_bot_deps):
+        """Gracefully skips session files containing invalid JSON."""
+        bot = _make_bot(tmp_path, _patch_base_bot_deps)
+        sessions_dir = tmp_path / "sessions"
+        sessions_dir.mkdir(parents=True)
+        (sessions_dir / "12345.json").write_text("not json!")
+        with patch("apps.handlers.base_bot.CC_SESSIONS_DIR", sessions_dir):
+            result = bot._discover_cc_session()
+        assert result is None
+
+    def test_resolves_symlinked_cwd(self, tmp_path, _patch_base_bot_deps):
+        """Resolved paths match even through symlinks."""
+        real_dir = tmp_path / "real_workdir"
+        real_dir.mkdir()
+        link = tmp_path / "link_workdir"
+        link.symlink_to(real_dir)
+        with patch("apps.handlers.base_bot.PENDING_DIR", tmp_path):
+            bot = BaseBot(
+                bot_id="sym_test",
+                bot_token="t",
+                work_dir=link,
+                branch_name="test",
+            )
+        sessions_dir = tmp_path / "sessions"
+        _write_cc_session(sessions_dir, os.getpid(), str(real_dir))
+        with patch("apps.handlers.base_bot.CC_SESSIONS_DIR", sessions_dir):
+            result = bot._discover_cc_session()
+        assert result is not None
+
+
+# =============================================
+# 2. _is_pid_alive
+# =============================================
+
+
+class TestIsPidAlive:
+    """PID liveness check via os.kill(pid, 0)."""
+
+    def test_own_pid_is_alive(self):
+        """Reports the current process PID as alive."""
+        assert BaseBot._is_pid_alive(os.getpid()) is True
+
+    def test_dead_pid(self):
+        """Reports a non-existent PID as dead."""
+        assert BaseBot._is_pid_alive(99999999) is False
+
+    def test_zero_pid(self):
+        """Reports PID zero as dead."""
+        assert BaseBot._is_pid_alive(0) is False
+
+    def test_negative_pid(self):
+        """Reports a negative PID as dead."""
+        assert BaseBot._is_pid_alive(-1) is False
+
+    def test_permission_error_treated_as_alive(self):
+        """Treats PermissionError from os.kill as evidence the PID is alive."""
+        with patch("os.kill", side_effect=PermissionError("denied")):
+            assert BaseBot._is_pid_alive(42) is True
+
+    def test_os_error_treated_as_dead(self):
+        """Treats a generic OSError from os.kill as evidence the PID is dead."""
+        with patch("os.kill", side_effect=OSError("some error")):
+            assert BaseBot._is_pid_alive(42) is False
+
+
+# =============================================
+# 3. _find_tmux_pane_by_cwd
+# =============================================
+
+
+class TestFindTmuxPaneByCwd:
+    """Find tmux session with a pane whose CWD matches work_dir."""
+
+    def test_finds_matching_pane(self, tmp_path, _patch_base_bot_deps):
+        """Returns the tmux session name whose pane cwd matches work_dir."""
+        bot = _make_bot(tmp_path, _patch_base_bot_deps)
+        workdir = str(bot.work_dir.resolve())
+        pane_output = f"my-session:{workdir}\nother:{tmp_path}\n"
+        with patch(
+            "subprocess.run",
+            return_value=MagicMock(returncode=0, stdout=pane_output),
+        ):
+            result = bot._find_tmux_pane_by_cwd()
+        assert result == "my-session"
+
+    def test_returns_none_when_no_match(self, tmp_path, _patch_base_bot_deps):
+        """Returns None when no tmux pane cwd matches the bot work directory."""
+        bot = _make_bot(tmp_path, _patch_base_bot_deps)
+        pane_output = f"session1:{tmp_path / 'other'}\n"
+        with patch(
+            "subprocess.run",
+            return_value=MagicMock(returncode=0, stdout=pane_output),
+        ):
+            result = bot._find_tmux_pane_by_cwd()
+        assert result is None
+
+    def test_returns_none_when_tmux_unavailable(self, tmp_path, _patch_base_bot_deps):
+        """Returns None when the tmux binary is not found."""
+        bot = _make_bot(tmp_path, _patch_base_bot_deps)
+        with patch("subprocess.run", side_effect=FileNotFoundError("tmux")):
+            result = bot._find_tmux_pane_by_cwd()
+        assert result is None
+
+    def test_returns_none_when_tmux_fails(self, tmp_path, _patch_base_bot_deps):
+        """Returns None when the tmux list-panes command exits with failure."""
+        bot = _make_bot(tmp_path, _patch_base_bot_deps)
+        with patch("subprocess.run", return_value=MagicMock(returncode=1)):
+            result = bot._find_tmux_pane_by_cwd()
+        assert result is None
+
+
+# =============================================
+# 4. _sanitize_path_for_cc
+# =============================================
+
+
+class TestSanitizePathForCc:
+    """Path sanitization: every non-alphanumeric char becomes '-'."""
+
+    def test_basic_path(self):
+        """Slashes become dashes."""
+        assert BaseBot._sanitize_path_for_cc("/opt/work/project") == "-opt-work-project"
+
+    def test_dots_and_underscores(self):
+        """Dots and underscores become dashes."""
+        assert BaseBot._sanitize_path_for_cc("/opt/work/.my_project") == "-opt-work--my-project"
+
+    def test_backslashes(self):
+        """Backslashes become dashes."""
+        assert BaseBot._sanitize_path_for_cc("D:\\Work\\project") == "D--Work-project"
+
+    def test_alphanumeric_preserved(self):
+        """Alphanumeric characters are kept as-is."""
+        assert BaseBot._sanitize_path_for_cc("abc123XYZ") == "abc123XYZ"
+
+
+# =============================================
+# 5. _resolve_cc_transcript_path
+# =============================================
+
+
+class TestResolveCcTranscriptPath:
+    """Resolve transcript JSONL path from CC session info."""
+
+    def test_resolves_existing_transcript(self, tmp_path, _patch_base_bot_deps):
+        """Returns the transcript path when the JSONL file exists on disk."""
+        bot = _make_bot(tmp_path, _patch_base_bot_deps)
+        cwd = str(bot.work_dir.resolve())
+        session = {"sessionId": "abc-123", "cwd": cwd}
+        slug = BaseBot._sanitize_path_for_cc(cwd)
+        transcript_dir = tmp_path / ".claude" / "projects" / slug
+        transcript_dir.mkdir(parents=True)
+        transcript_file = transcript_dir / "abc-123.jsonl"
+        transcript_file.write_text("{}", encoding="utf-8")
+        with patch("pathlib.Path.home", return_value=tmp_path):
+            result = bot._resolve_cc_transcript_path(session)
+        assert result is not None
+        assert result.name == "abc-123.jsonl"
+
+    def test_returns_none_when_file_missing(self, tmp_path, _patch_base_bot_deps):
+        """Returns None when the transcript JSONL file does not exist."""
+        bot = _make_bot(tmp_path, _patch_base_bot_deps)
+        session = {"sessionId": "nonexistent", "cwd": str(tmp_path)}
+        with patch("pathlib.Path.home", return_value=tmp_path):
+            result = bot._resolve_cc_transcript_path(session)
+        assert result is None
+
+    def test_returns_none_when_no_session_id(self, tmp_path, _patch_base_bot_deps):
+        """Returns None when the session dict lacks a sessionId key."""
+        bot = _make_bot(tmp_path, _patch_base_bot_deps)
+        result = bot._resolve_cc_transcript_path({"cwd": str(tmp_path)})
+        assert result is None
+
+    def test_returns_none_when_no_cwd(self, tmp_path, _patch_base_bot_deps):
+        """Returns None when the session dict lacks a cwd key."""
+        bot = _make_bot(tmp_path, _patch_base_bot_deps)
+        result = bot._resolve_cc_transcript_path({"sessionId": "abc"})
+        assert result is None
+
+
+# =============================================
+# 6. _extract_assistant_text / _read_transcript_tail
+# =============================================
+
+
+class TestTranscriptParsing:
+    """Extract assistant text from transcript JSONL entries."""
+
+    def test_extract_text_from_text_block(self):
+        """Extracts text from a content block with type 'text'."""
+        entry = {"message": {"role": "assistant", "content": [{"type": "text", "text": "Hello world"}]}}
+        assert BaseBot._extract_assistant_text(entry) == "Hello world"
+
+    def test_extract_text_from_string_content(self):
+        """Extracts text when content is a plain string instead of a list."""
+        entry = {"message": {"role": "assistant", "content": "Plain text"}}
+        assert BaseBot._extract_assistant_text(entry) == "Plain text"
+
+    def test_returns_none_for_user_message(self):
+        """Returns None for entries with role 'user'."""
+        entry = {"message": {"role": "user", "content": "question"}}
+        assert BaseBot._extract_assistant_text(entry) is None
+
+    def test_returns_none_for_tool_use_only(self):
+        """Returns None when content contains only tool_use blocks."""
+        entry = {"message": {"role": "assistant", "content": [{"type": "tool_use", "id": "t1"}]}}
+        assert BaseBot._extract_assistant_text(entry) is None
+
+    def test_returns_none_for_empty_entry(self):
+        """Returns None for an empty dict entry."""
+        assert BaseBot._extract_assistant_text({}) is None
+
+    def test_read_transcript_tail_finds_response(self, tmp_path, _patch_base_bot_deps):
+        """Returns the last assistant text from the transcript tail."""
+        bot = _make_bot(tmp_path, _patch_base_bot_deps)
+        transcript = tmp_path / "transcript.jsonl"
+        lines = [
+            json.dumps({"message": {"role": "user", "content": "hi"}}),
+            json.dumps({"message": {"role": "assistant", "content": [{"type": "text", "text": "Hello!"}]}}),
+        ]
+        transcript.write_text("\n".join(lines), encoding="utf-8")
+        bot._active_transcript_path = transcript
+        result = bot._read_transcript_tail()
+        assert result == "Hello!"
+
+    def test_read_transcript_tail_returns_none_when_no_path(self, tmp_path, _patch_base_bot_deps):
+        """Returns None when no active transcript path is set."""
+        bot = _make_bot(tmp_path, _patch_base_bot_deps)
+        bot._active_transcript_path = None
+        assert bot._read_transcript_tail() is None
+
+    def test_read_transcript_tail_returns_none_when_file_missing(self, tmp_path, _patch_base_bot_deps):
+        """Returns None when the transcript file does not exist on disk."""
+        bot = _make_bot(tmp_path, _patch_base_bot_deps)
+        bot._active_transcript_path = tmp_path / "nonexistent.jsonl"
+        assert bot._read_transcript_tail() is None
+
+
+# =============================================
+# 7. ensure_tmux_session — CC-native-first
+# =============================================
+
+
+class TestEnsureWithCcDiscovery:
+    """ensure_tmux_session follows CC-native session discovery first."""
+
+    def test_attaches_via_cc_session(self, tmp_path, _patch_base_bot_deps):
+        """Attaches to a live CC session and sets shared session state."""
+        bot = _make_bot(tmp_path, _patch_base_bot_deps)
+        workdir = str(bot.work_dir.resolve())
+        session = {
+            "pid": os.getpid(),
+            "sessionId": "s1",
+            "cwd": workdir,
+            "startedAt": 1000,
+            "name": "test",
+        }
+        pane_output = f"live-tmux:{workdir}\n"
+        with (
+            patch.object(bot, "_discover_cc_session", return_value=session),
+            patch("subprocess.run", return_value=MagicMock(returncode=0, stdout=pane_output)),
+            patch.object(bot, "_resolve_cc_transcript_path", return_value=tmp_path / "t.jsonl"),
+        ):
+            result = bot.ensure_tmux_session()
+        assert result is True
+        assert bot.session_name == "live-tmux"
+        assert bot._using_shared_session is True
+        assert bot._active_session_id == "s1"
+
+    def test_cc_no_tmux_pane_falls_through(self, tmp_path, _patch_base_bot_deps):
+        """CC session found but no tmux pane → falls through to Strategy 2."""
+        workdir = tmp_path / "workdir"
+        workdir.mkdir(exist_ok=True)
+        with patch("apps.handlers.base_bot.PENDING_DIR", tmp_path):
+            bot = BaseBot(
+                bot_id="fb_test",
+                bot_token="t",
+                work_dir=workdir,
+                branch_name="devpulse",
+                shared_session="explicit-session",
+            )
+        bot.send_message = MagicMock()
+        session = {"pid": os.getpid(), "sessionId": "s1", "cwd": str(workdir.resolve()), "startedAt": 1000}
+        with (
+            patch.object(bot, "_discover_cc_session", return_value=session),
+            patch.object(bot, "_find_tmux_pane_by_cwd", return_value=None),
+            patch("subprocess.run", return_value=MagicMock(returncode=0)),
+        ):
+            result = bot.ensure_tmux_session()
+        assert result is True
+        assert bot.session_name == "explicit-session"
+
+    def test_fallback_to_shared_session(self, tmp_path, _patch_base_bot_deps):
+        """When CC discovery returns None, falls back to shared_session config."""
+        workdir = tmp_path / "workdir"
+        workdir.mkdir(exist_ok=True)
+        with patch("apps.handlers.base_bot.PENDING_DIR", tmp_path):
+            bot = BaseBot(
+                bot_id="fb_test",
+                bot_token="t",
+                work_dir=workdir,
+                branch_name="devpulse",
+                shared_session="explicit-session",
+            )
+        bot.send_message = MagicMock()
+        with (
+            patch.object(bot, "_discover_cc_session", return_value=None),
+            patch("subprocess.run", return_value=MagicMock(returncode=0)),
+        ):
+            result = bot.ensure_tmux_session()
+        assert result is True
+        assert bot.session_name == "explicit-session"
+
+    def test_no_session_returns_false_never_spawns(self, tmp_path, _patch_base_bot_deps):
+        """When no CC session and no shared session, returns False — never spawns."""
+        bot = _make_bot(tmp_path, _patch_base_bot_deps)
+        with (
+            patch.object(bot, "_discover_cc_session", return_value=None),
+            patch("subprocess.run", return_value=MagicMock(returncode=1)),
+        ):
+            result = bot.ensure_tmux_session()
+        assert result is False
+        assert bot._using_shared_session is False
+
+    def test_rebinds_on_session_change(self, tmp_path, _patch_base_bot_deps):
+        """Bot re-reads CC sessions on each call, rebinding to new session."""
+        bot = _make_bot(tmp_path, _patch_base_bot_deps)
+        workdir = str(bot.work_dir.resolve())
+        pane_output = f"tmux-pane:{workdir}\n"
+
+        session_v1 = {"pid": os.getpid(), "sessionId": "v1", "cwd": workdir, "startedAt": 100, "name": "v1"}
+        session_v2 = {"pid": os.getpid(), "sessionId": "v2", "cwd": workdir, "startedAt": 200, "name": "v2"}
+
+        with (
+            patch.object(bot, "_discover_cc_session", return_value=session_v1),
+            patch("subprocess.run", return_value=MagicMock(returncode=0, stdout=pane_output)),
+            patch.object(bot, "_resolve_cc_transcript_path", return_value=None),
+        ):
+            bot.ensure_tmux_session()
+        assert bot._active_session_id == "v1"
+
+        with (
+            patch.object(bot, "_discover_cc_session", return_value=session_v2),
+            patch("subprocess.run", return_value=MagicMock(returncode=0, stdout=pane_output)),
+            patch.object(bot, "_resolve_cc_transcript_path", return_value=None),
+        ):
+            bot.ensure_tmux_session()
+        assert bot._active_session_id == "v2"
+
+    def test_stores_transcript_path(self, tmp_path, _patch_base_bot_deps):
+        """CC discovery stores the resolved transcript path on the bot."""
+        bot = _make_bot(tmp_path, _patch_base_bot_deps)
+        workdir = str(bot.work_dir.resolve())
+        session = {"pid": os.getpid(), "sessionId": "s1", "cwd": workdir, "startedAt": 1000, "name": "t"}
+        transcript = tmp_path / "transcript.jsonl"
+        pane_output = f"tmux:{workdir}\n"
+        with (
+            patch.object(bot, "_discover_cc_session", return_value=session),
+            patch("subprocess.run", return_value=MagicMock(returncode=0, stdout=pane_output)),
+            patch.object(bot, "_resolve_cc_transcript_path", return_value=transcript),
+        ):
+            bot.ensure_tmux_session()
+        assert bot._active_transcript_path == transcript
+
+
+# =============================================
+# 8. handle_message — no-session error
+# =============================================
+
+
+class TestHandleMessageNoSession:
+    """Error message when no live session is available."""
+
+    def test_shows_branch_name_in_error(self, tmp_path, _patch_base_bot_deps):
+        """Includes the branch name in the no-session error message."""
+        bot = _make_bot(tmp_path, _patch_base_bot_deps, branch_name="api")
+        with (
+            patch.object(bot, "_discover_cc_session", return_value=None),
+            patch("subprocess.run", return_value=MagicMock(returncode=1)),
+        ):
+            bot.handle_message(42, "hello", {"message_id": 1})
+        msg = bot.send_message.call_args[0][1]
+        assert "No live Claude session" in msg
+        assert "api" in msg
+
+    def test_shows_work_dir_name_when_no_branch_name(self, tmp_path, _patch_base_bot_deps):
+        """Falls back to work_dir name in the error when branch_name is None."""
+        bot = _make_bot(tmp_path, _patch_base_bot_deps)
+        bot.branch_name = None
+        with (
+            patch.object(bot, "_discover_cc_session", return_value=None),
+            patch("subprocess.run", return_value=MagicMock(returncode=1)),
+        ):
+            bot.handle_message(42, "hello", {"message_id": 1})
+        msg = bot.send_message.call_args[0][1]
+        assert "No live Claude session" in msg
diff --git a/src/aipass/skills/.aipass/skills/telegram/tests/test_response_router.py b/src/aipass/skills/lib/telegram/tests/test_response_router.py
similarity index 100%
rename from src/aipass/skills/.aipass/skills/telegram/tests/test_response_router.py
rename to src/aipass/skills/lib/telegram/tests/test_response_router.py
diff --git a/src/aipass/skills/lib/telegram/tests/test_scheduler_bot.py b/src/aipass/skills/lib/telegram/tests/test_scheduler_bot.py
new file mode 100644
index 00000000..8fb722d2
--- /dev/null
+++ b/src/aipass/skills/lib/telegram/tests/test_scheduler_bot.py
@@ -0,0 +1,395 @@
+"""
+Tests for SchedulerBot — dedicated Telegram bot for daemon job queue (TDPLAN-0008 P2).
+
+Tests cover:
+  - /queue parses drone @daemon queue --json and formats readable output
+  - Free-text (non-command) does NOT launch tmux/Claude
+  - Hourly digest thread posts a digest (mockable clock/sender)
+  - >4096-char digest is chunked correctly via chunk_text
+  - Bot loads telegram/scheduler config; missing secret fails loud
+  - Slash-menu includes /queue
+  - Command routing (/queue dispatched correctly)
+"""
+
+import json
+import pytest
+from unittest.mock import patch, MagicMock
+
+from apps.handlers.scheduler_bot import SchedulerBot, QUEUE_CMD  # type: ignore[import-not-found]
+
+
+# =============================================
+# HELPERS
+# =============================================
+
+
+SAMPLE_QUEUE = {
+    "generated_at": "2026-06-25T15:00:00Z",
+    "count": 2,
+    "jobs": [
+        {
+            "owner": "@api",
+            "id": "data-check",
+            "enabled": True,
+            "type": "once",
+            "schedule_human": "2026-07-02",
+            "next_run": "2026-07-02T09:00:00Z",
+            "last_run": None,
+            "last_status": "success",
+            "last_error": None,
+            "prompt_preview": "Check the live data and report...",
+            "wake": {"fresh": True, "model": "haiku"},
+        },
+        {
+            "owner": "@backup",
+            "id": "weekly-snap",
+            "enabled": False,
+            "type": "interval",
+            "schedule_human": "every 7d",
+            "next_run": "2026-07-01T00:00:00Z",
+            "last_run": "2026-06-24T00:00:00Z",
+            "last_status": "failed",
+            "last_error": "disk full",
+            "prompt_preview": "Run full backup...",
+            "wake": {"fresh": True},
+        },
+    ],
+}
+
+EMPTY_QUEUE = {"generated_at": "2026-06-25T15:00:00Z", "count": 0, "jobs": []}
+
+
+@pytest.fixture
+def _patch_base_bot_deps(tmp_path):
+    """Patch heavy BaseBot dependencies to allow lightweight instantiation."""
+    patches = [
+        patch("apps.handlers.base_bot.PENDING_DIR", tmp_path),
+        patch("apps.handlers.base_bot.signal.signal"),
+        patch("apps.handlers.base_bot.atexit.register"),
+    ]
+    for p in patches:
+        p.start()
+    yield
+    for p in patches:
+        p.stop()
+
+
+def _make_scheduler_bot(tmp_path, _patch_base_bot_deps):
+    workdir = tmp_path / "workdir"
+    workdir.mkdir()
+    bot = SchedulerBot(
+        bot_id="scheduler",
+        bot_token="123:FAKETOKEN",
+        work_dir=workdir,
+        bot_name="AIPass Scheduler Bot",
+        allowed_user_ids=[111],
+        branch_name=None,
+    )
+    return bot
+
+
+# =============================================
+# 1. /queue PARSES AND FORMATS
+# =============================================
+
+
+class TestQueueCommand:
+    """/queue fetches queue --json, formats, and sends."""
+
+    def test_queue_formats_jobs(self):
+        text = SchedulerBot._format_queue(SAMPLE_QUEUE)
+        assert "@api/data-check" in text
+        assert "@backup/weekly-snap" in text
+        assert "[disabled]" in text
+        assert "once" in text
+        assert "success" in text
+
+    def test_queue_shows_error_when_failed(self):
+        text = SchedulerBot._format_queue(SAMPLE_QUEUE)
+        assert "disk full" in text
+
+    def test_queue_empty_shows_no_jobs(self):
+        text = SchedulerBot._format_queue(EMPTY_QUEUE)
+        assert "No scheduled jobs" in text
+
+    def test_queue_shows_count(self):
+        text = SchedulerBot._format_queue(SAMPLE_QUEUE)
+        assert "2" in text
+
+    def test_queue_shows_status_icons(self):
+        text = SchedulerBot._format_queue(SAMPLE_QUEUE)
+        assert "✅" in text  # success
+        assert "❌" in text  # failed
+
+    def test_queue_command_sends_formatted(self, tmp_path, _patch_base_bot_deps):
+        bot = _make_scheduler_bot(tmp_path, _patch_base_bot_deps)
+        with (
+            patch.object(bot, "_fetch_queue", return_value=SAMPLE_QUEUE),
+            patch.object(bot, "send_message") as mock_send,
+        ):
+            bot._handle_queue_command(42)
+            mock_send.assert_called_once()
+            msg = mock_send.call_args[0][1]
+            assert "@api/data-check" in msg
+
+    def test_queue_command_handles_fetch_failure(self, tmp_path, _patch_base_bot_deps):
+        bot = _make_scheduler_bot(tmp_path, _patch_base_bot_deps)
+        with (
+            patch.object(bot, "_fetch_queue", return_value=None),
+            patch.object(bot, "send_message") as mock_send,
+        ):
+            bot._handle_queue_command(42)
+            msg = mock_send.call_args[0][1]
+            assert "Failed" in msg
+
+    def test_fetch_queue_parses_subprocess(self, tmp_path, _patch_base_bot_deps):
+        bot = _make_scheduler_bot(tmp_path, _patch_base_bot_deps)
+        mock_result = MagicMock()
+        mock_result.returncode = 0
+        mock_result.stdout = json.dumps(SAMPLE_QUEUE)
+
+        with patch("apps.handlers.scheduler_bot.subprocess.run", return_value=mock_result):
+            data = bot._fetch_queue()
+
+        assert data is not None
+        assert data["count"] == 2
+        assert len(data["jobs"]) == 2
+
+    def test_fetch_queue_returns_none_on_failure(self, tmp_path, _patch_base_bot_deps):
+        bot = _make_scheduler_bot(tmp_path, _patch_base_bot_deps)
+        mock_result = MagicMock()
+        mock_result.returncode = 1
+        mock_result.stderr = "error"
+
+        with patch("apps.handlers.scheduler_bot.subprocess.run", return_value=mock_result):
+            data = bot._fetch_queue()
+
+        assert data is None
+
+    def test_fetch_queue_returns_none_on_timeout(self, tmp_path, _patch_base_bot_deps):
+        bot = _make_scheduler_bot(tmp_path, _patch_base_bot_deps)
+        import subprocess as sp
+
+        with patch("apps.handlers.scheduler_bot.subprocess.run", side_effect=sp.TimeoutExpired(QUEUE_CMD, 15)):
+            data = bot._fetch_queue()
+
+        assert data is None
+
+
+# =============================================
+# 2. FREE-TEXT DOES NOT LAUNCH TMUX
+# =============================================
+
+
+class TestNoTmux:
+    """Free-text and file messages do NOT spin up tmux/Claude."""
+
+    def test_free_text_rejected(self, tmp_path, _patch_base_bot_deps):
+        bot = _make_scheduler_bot(tmp_path, _patch_base_bot_deps)
+        with (
+            patch.object(bot, "send_message") as mock_send,
+            patch.object(bot, "ensure_tmux_session") as mock_tmux,
+        ):
+            bot.handle_message(42, "Hello there", {"message_id": 1})
+            mock_tmux.assert_not_called()
+            msg = mock_send.call_args[0][1]
+            assert "commands" in msg.lower() or "/queue" in msg
+
+    def test_file_rejected(self, tmp_path, _patch_base_bot_deps):
+        bot = _make_scheduler_bot(tmp_path, _patch_base_bot_deps)
+        with (
+            patch.object(bot, "send_message") as mock_send,
+            patch("apps.handlers.base_bot.BaseBot.handle_file") as mock_parent_file,
+        ):
+            bot.handle_file(42, {"message_id": 1, "document": {"file_id": "abc"}})
+            mock_parent_file.assert_not_called()
+            msg = mock_send.call_args[0][1]
+            assert "file" in msg.lower() or "/queue" in msg
+
+
+# =============================================
+# 3. HOURLY DIGEST
+# =============================================
+
+
+class TestDigest:
+    """Hourly digest thread posts queue digest."""
+
+    def test_digest_posts_message(self, tmp_path, _patch_base_bot_deps):
+        bot = _make_scheduler_bot(tmp_path, _patch_base_bot_deps)
+        bot._scheduler_chat_id = 42
+
+        with (
+            patch.object(bot, "_fetch_queue", return_value=SAMPLE_QUEUE),
+            patch.object(bot, "send_message") as mock_send,
+        ):
+            bot._post_digest()
+            mock_send.assert_called_once()
+            msg = mock_send.call_args[0][1]
+            assert "Hourly Queue Digest" in msg
+            assert "@api/data-check" in msg
+
+    def test_digest_skips_on_fetch_failure(self, tmp_path, _patch_base_bot_deps):
+        bot = _make_scheduler_bot(tmp_path, _patch_base_bot_deps)
+        bot._scheduler_chat_id = 42
+
+        with (
+            patch.object(bot, "_fetch_queue", return_value=None),
+            patch.object(bot, "send_message") as mock_send,
+        ):
+            bot._post_digest()
+            mock_send.assert_not_called()
+
+    def test_digest_skips_when_no_chat_id(self, tmp_path, _patch_base_bot_deps):
+        bot = _make_scheduler_bot(tmp_path, _patch_base_bot_deps)
+        assert bot._scheduler_chat_id is None
+
+        with patch.object(bot, "send_message") as mock_send:
+            bot._post_digest()
+            mock_send.assert_not_called()
+
+    def test_start_digest_creates_thread(self, tmp_path, _patch_base_bot_deps):
+        bot = _make_scheduler_bot(tmp_path, _patch_base_bot_deps)
+        bot.start_digest(42)
+        try:
+            assert bot._digest_thread is not None
+            assert bot._digest_thread.daemon is True
+            assert bot._digest_thread.name == "scheduler-digest"
+            assert bot._scheduler_chat_id == 42
+        finally:
+            bot.stop_digest()
+
+    def test_stop_digest_cleans_up(self, tmp_path, _patch_base_bot_deps):
+        bot = _make_scheduler_bot(tmp_path, _patch_base_bot_deps)
+        bot.start_digest(42)
+        bot.stop_digest()
+        assert bot._digest_thread is None
+        assert bot._digest_stop.is_set()
+
+
+# =============================================
+# 4. CHUNKING LONG MESSAGES
+# =============================================
+
+
+class TestChunking:
+    """>4096-char messages are split via chunk_text."""
+
+    def test_long_queue_is_chunked(self, tmp_path, _patch_base_bot_deps):
+        bot = _make_scheduler_bot(tmp_path, _patch_base_bot_deps)
+        many_jobs = {
+            "generated_at": "now",
+            "count": 100,
+            "jobs": [
+                {
+                    "owner": f"@branch{i}",
+                    "id": f"job-{i}",
+                    "enabled": True,
+                    "type": "daily",
+                    "schedule_human": "every day",
+                    "next_run": "2026-07-01T00:00:00Z",
+                    "last_run": None,
+                    "last_status": None,
+                    "last_error": None,
+                    "prompt_preview": "A" * 80,
+                    "wake": {},
+                }
+                for i in range(100)
+            ],
+        }
+
+        with (
+            patch.object(bot, "_fetch_queue", return_value=many_jobs),
+            patch.object(bot, "send_message") as mock_send,
+        ):
+            bot._handle_queue_command(42)
+            assert mock_send.call_count >= 2
+
+    def test_short_queue_not_chunked(self, tmp_path, _patch_base_bot_deps):
+        bot = _make_scheduler_bot(tmp_path, _patch_base_bot_deps)
+        with (
+            patch.object(bot, "_fetch_queue", return_value=SAMPLE_QUEUE),
+            patch.object(bot, "send_message") as mock_send,
+        ):
+            bot._handle_queue_command(42)
+            assert mock_send.call_count == 1
+
+
+# =============================================
+# 5. SECRET LOADING
+# =============================================
+
+
+class TestSecretLoading:
+    """Bot loads telegram/scheduler config; missing fails loud."""
+
+    def test_missing_secret_returns_none(self):
+        """When get_secret returns None, load_bot_config returns None — bot won't start."""
+        from apps.handlers.config import load_bot_config  # type: ignore[import-not-found]
+
+        with patch("apps.handlers.config._get_secret", return_value=None):
+            config = load_bot_config("scheduler")
+            assert config is None
+
+    def test_secret_provides_chat_id(self):
+        """The scheduler config includes chat_id for digest delivery."""
+        config = {
+            "bot_id": "scheduler",
+            "bot_token": "123:FAKE",
+            "bot_name": "AIPass Scheduler Bot",
+            "branch_name": "daemon",
+            "work_dir": "/tmp",
+            "allowed_user_ids": [111],
+            "chat_id": "7235222625",
+        }
+        assert "chat_id" in config
+        assert config["chat_id"] == "7235222625"
+
+
+# =============================================
+# 6. SLASH-MENU INCLUDES /queue
+# =============================================
+
+
+class TestSlashMenu:
+    """/queue appears in get_custom_commands and the command menu."""
+
+    def test_queue_in_custom_commands(self, tmp_path, _patch_base_bot_deps):
+        bot = _make_scheduler_bot(tmp_path, _patch_base_bot_deps)
+        cmds = bot.get_custom_commands()
+        assert "queue" in cmds
+        assert "description" in cmds["queue"]
+
+    def test_inherited_commands_preserved(self, tmp_path, _patch_base_bot_deps):
+        bot = _make_scheduler_bot(tmp_path, _patch_base_bot_deps)
+        cmds = bot.get_custom_commands()
+        assert "monitor" in cmds
+        assert "create" in cmds
+
+
+# =============================================
+# 7. COMMAND ROUTING
+# =============================================
+
+
+class TestCommandRouting:
+    """/queue is dispatched correctly through _dispatch_command."""
+
+    def test_queue_routed(self, tmp_path, _patch_base_bot_deps):
+        bot = _make_scheduler_bot(tmp_path, _patch_base_bot_deps)
+        with patch.object(bot, "_handle_queue_command") as mock_q:
+            result = bot._dispatch_command(42, ("queue", ""))
+            assert result is True
+            mock_q.assert_called_once_with(42)
+
+    def test_other_commands_fall_through_to_parent(self, tmp_path, _patch_base_bot_deps):
+        bot = _make_scheduler_bot(tmp_path, _patch_base_bot_deps)
+        with patch.object(bot, "send_message"):
+            result = bot._dispatch_command(42, ("status", ""))
+            assert result is True
+
+    def test_unknown_command_falls_through(self, tmp_path, _patch_base_bot_deps):
+        bot = _make_scheduler_bot(tmp_path, _patch_base_bot_deps)
+        with patch.object(bot, "send_message"):
+            result = bot._dispatch_command(42, ("nonexistent", ""))
+            assert result is False
diff --git a/src/aipass/skills/lib/telegram/tests/test_status_reset.py b/src/aipass/skills/lib/telegram/tests/test_status_reset.py
new file mode 100644
index 00000000..879fba69
--- /dev/null
+++ b/src/aipass/skills/lib/telegram/tests/test_status_reset.py
@@ -0,0 +1,234 @@
+# =================== AIPass ====================
+# Name: test_status_reset.py
+# Description: Tests for /status conversation vs daemon uptime + /new counter reset
+# Version: 1.0.0
+# Created: 2026-06-29
+# Modified: 2026-06-29
+# =============================================
+
+"""
+Tests for /status conversation vs daemon uptime + /new counter reset.
+
+Tests cover:
+  - /new resets message_count to 0
+  - /new resets conversation_start
+  - /status shows conversation uptime (not daemon uptime) as primary
+  - /status shows daemon uptime separately
+  - build_status_text includes daemon_uptime line when provided
+  - build_status_text omits daemon_uptime line when not provided
+"""
+
+import time
+import pytest
+from unittest.mock import patch
+
+from apps.handlers.base_bot import BaseBot  # type: ignore[import-not-found]
+from apps.handlers.telegram_standards import build_status_text  # type: ignore[import-not-found]
+
+
+@pytest.fixture
+def _patch_base_bot_deps(tmp_path):
+    patches = [
+        patch("apps.handlers.base_bot.PENDING_DIR", tmp_path),
+        patch("apps.handlers.base_bot.signal.signal"),
+        patch("apps.handlers.base_bot.atexit.register"),
+    ]
+    for p in patches:
+        p.start()
+    yield
+    for p in patches:
+        p.stop()
+
+
+def _make_bot(tmp_path, _patch_base_bot_deps):
+    workdir = tmp_path / "workdir"
+    workdir.mkdir()
+    return BaseBot(
+        bot_id="status_test",
+        bot_token="123:FAKETOKEN",
+        work_dir=workdir,
+        bot_name="Status Test Bot",
+        allowed_user_ids=[111],
+        branch_name=None,
+    )
+
+
+# =============================================
+# 1. /new RESETS COUNTERS
+# =============================================
+
+
+class TestNewResetsCounters:
+    """/new resets message_count and conversation_start."""
+
+    def test_new_resets_message_count(self, tmp_path, _patch_base_bot_deps):
+        bot = _make_bot(tmp_path, _patch_base_bot_deps)
+        bot.state["message_count"] = 15
+
+        with (
+            patch.object(bot, "send_message"),
+            patch.object(bot, "_kill_tmux_session"),
+        ):
+            bot._dispatch_command(42, ("new", ""))
+
+        assert bot.state["message_count"] == 0
+
+    def test_new_resets_conversation_start(self, tmp_path, _patch_base_bot_deps):
+        bot = _make_bot(tmp_path, _patch_base_bot_deps)
+        bot.state["conversation_start"] = time.time() - 3600  # 1 hour ago
+
+        with (
+            patch.object(bot, "send_message"),
+            patch.object(bot, "_kill_tmux_session"),
+        ):
+            before = time.time()
+            bot._dispatch_command(42, ("new", ""))
+            after = time.time()
+
+        assert before <= bot.state["conversation_start"] <= after
+
+    def test_new_does_not_reset_daemon_start(self, tmp_path, _patch_base_bot_deps):
+        bot = _make_bot(tmp_path, _patch_base_bot_deps)
+        original_start = bot.state["start_time"]
+        bot.state["message_count"] = 5
+
+        with (
+            patch.object(bot, "send_message"),
+            patch.object(bot, "_kill_tmux_session"),
+        ):
+            bot._dispatch_command(42, ("new", ""))
+
+        assert bot.state["start_time"] == original_start
+
+
+# =============================================
+# 2. /status SHOWS CORRECT UPTIMES
+# =============================================
+
+
+class TestStatusUptimes:
+    """/status shows conversation uptime as primary and daemon uptime separately."""
+
+    def test_status_passes_daemon_uptime(self, tmp_path, _patch_base_bot_deps):
+        bot = _make_bot(tmp_path, _patch_base_bot_deps)
+        bot.state["start_time"] = time.time() - 7200  # daemon up 2h
+        bot.state["conversation_start"] = time.time() - 300  # conv 5m
+
+        with (
+            patch.object(bot, "send_message"),
+            patch("apps.handlers.base_bot.build_status_text", wraps=build_status_text) as mock_build,
+            patch("apps.handlers.telegram_standards._tmux_session_exists", return_value=True),
+        ):
+            bot._dispatch_command(42, ("status", ""))
+
+        call_kwargs = mock_build.call_args
+        args = call_kwargs[1] if call_kwargs[1] else {}
+        if not args:
+            _, kwargs = mock_build.call_args
+            args = kwargs
+
+        assert "daemon_uptime" in args
+        assert "2h" in args["daemon_uptime"]
+
+    def test_status_conversation_uptime_after_new(self, tmp_path, _patch_base_bot_deps):
+        bot = _make_bot(tmp_path, _patch_base_bot_deps)
+        bot.state["start_time"] = time.time() - 7200  # daemon up 2h
+
+        with (
+            patch.object(bot, "send_message"),
+            patch.object(bot, "_kill_tmux_session"),
+        ):
+            bot._dispatch_command(42, ("new", ""))
+
+        # Now check /status — conversation uptime should be near 0
+        with (
+            patch.object(bot, "send_message") as mock_send,
+            patch("apps.handlers.telegram_standards._tmux_session_exists", return_value=True),
+        ):
+            bot._dispatch_command(42, ("status", ""))
+
+        msg = mock_send.call_args[0][1]
+        assert "Uptime: 0h 0m" in msg
+        assert "Daemon up: 2h" in msg
+
+    def test_status_messages_zero_after_new(self, tmp_path, _patch_base_bot_deps):
+        bot = _make_bot(tmp_path, _patch_base_bot_deps)
+        bot.state["message_count"] = 42
+
+        with (
+            patch.object(bot, "send_message"),
+            patch.object(bot, "_kill_tmux_session"),
+        ):
+            bot._dispatch_command(42, ("new", ""))
+
+        with (
+            patch.object(bot, "send_message") as mock_send,
+            patch("apps.handlers.telegram_standards._tmux_session_exists", return_value=True),
+        ):
+            bot._dispatch_command(42, ("status", ""))
+
+        msg = mock_send.call_args[0][1]
+        assert "Messages: 0" in msg
+
+
+# =============================================
+# 3. build_status_text
+# =============================================
+
+
+class TestBuildStatusText:
+    """build_status_text renders daemon_uptime when provided."""
+
+    def test_includes_daemon_uptime(self):
+        with patch("apps.handlers.telegram_standards._tmux_session_exists", return_value=True):
+            text = build_status_text(
+                session_name="telegram-base",
+                branch_name="base",
+                uptime="0h 5m 0s",
+                message_count=3,
+                daemon_uptime="12h 0m 0s",
+            )
+        assert "Daemon up: 12h 0m 0s" in text
+        assert "Uptime: 0h 5m 0s" in text
+
+    def test_omits_daemon_uptime_when_none(self):
+        with patch("apps.handlers.telegram_standards._tmux_session_exists", return_value=True):
+            text = build_status_text(
+                session_name="telegram-base",
+                branch_name="base",
+                uptime="1h 0m 0s",
+                message_count=5,
+            )
+        assert "Daemon up" not in text
+        assert "Uptime: 1h 0m 0s" in text
+
+    def test_uptime_before_daemon_uptime(self):
+        with patch("apps.handlers.telegram_standards._tmux_session_exists", return_value=True):
+            text = build_status_text(
+                session_name="telegram-base",
+                branch_name="base",
+                uptime="0h 1m 0s",
+                daemon_uptime="5h 0m 0s",
+            )
+        uptime_pos = text.index("Uptime:")
+        daemon_pos = text.index("Daemon up:")
+        assert uptime_pos < daemon_pos
+
+
+# =============================================
+# 4. CONVERSATION_START IN STATE
+# =============================================
+
+
+class TestConversationStartState:
+    """conversation_start is initialized and tracked."""
+
+    def test_init_sets_conversation_start(self, tmp_path, _patch_base_bot_deps):
+        before = time.time()
+        bot = _make_bot(tmp_path, _patch_base_bot_deps)
+        after = time.time()
+        assert before <= bot.state["conversation_start"] <= after
+
+    def test_conversation_start_equals_start_time_at_boot(self, tmp_path, _patch_base_bot_deps):
+        bot = _make_bot(tmp_path, _patch_base_bot_deps)
+        assert abs(bot.state["conversation_start"] - bot.state["start_time"]) < 0.1
diff --git a/src/aipass/skills/lib/telegram/tests/test_streaming.py b/src/aipass/skills/lib/telegram/tests/test_streaming.py
new file mode 100644
index 00000000..e7441eae
--- /dev/null
+++ b/src/aipass/skills/lib/telegram/tests/test_streaming.py
@@ -0,0 +1,595 @@
+# =================== AIPass ====================
+# Name: test_streaming.py
+# Description: Tests for streaming edit-in-place (FPLAN-0297)
+# Version: 1.0.0
+# Created: 2026-07-01
+# Modified: 2026-07-01
+# =============================================
+
+"""
+Tests for streaming edit-in-place (FPLAN-0297).
+
+Covers:
+  - _format_content_block: single block → plain text
+  - _format_stream_entries: batch block-mapping
+  - _tail_transcript_bytes: incremental byte-offset JSONL tail
+  - _stream_edit: 429/not-modified handling
+  - _streaming_loop: full loop behaviour (throttle, rollover, fallback)
+  - write_pending_file: streaming flag in pending file
+  - Batch mode unchanged when stream=False
+"""
+
+import json
+import threading
+import time
+from pathlib import Path
+from unittest.mock import MagicMock, patch
+
+import pytest
+
+from apps.handlers.base_bot import BaseBot  # type: ignore[import-not-found]
+
+
+# =============================================
+# Fixtures
+# =============================================
+
+
+@pytest.fixture
+def _patch_deps(tmp_path):
+    """Patch signal and atexit for safe BaseBot construction."""
+    patches = [
+        patch("apps.handlers.base_bot.PENDING_DIR", tmp_path),
+        patch("apps.handlers.base_bot.signal.signal"),
+        patch("apps.handlers.base_bot.atexit.register"),
+    ]
+    for p in patches:
+        p.start()
+    yield
+    for p in patches:
+        p.stop()
+
+
+def _make_bot(tmp_path, _patch_deps, stream=False):
+    """Create a BaseBot with test defaults."""
+    workdir = tmp_path / "workdir"
+    workdir.mkdir(exist_ok=True)
+    with patch("apps.handlers.base_bot.PENDING_DIR", tmp_path):
+        bot = BaseBot(
+            bot_id="stream_test",
+            bot_token="123:FAKETOKEN",
+            work_dir=workdir,
+            bot_name="Stream Test Bot",
+            allowed_user_ids=[111],
+            branch_name="testbranch",
+            stream=stream,
+        )
+    bot.send_message = MagicMock(return_value={"ok": True, "message_id": 1})
+    bot.edit_message = MagicMock(return_value=True)
+    return bot
+
+
+def _write_transcript(path, entries):
+    """Write JSONL entries to a file. Returns the file path."""
+    path.parent.mkdir(parents=True, exist_ok=True)
+    content = "\n".join(json.dumps(e) for e in entries) + "\n"
+    path.write_bytes(content.encode("utf-8"))
+    return path
+
+
+def _assistant_entry(content_blocks, sidechain=False):
+    """Build a transcript entry with assistant role."""
+    entry: dict = {"message": {"role": "assistant", "content": content_blocks}}
+    if sidechain:
+        entry["isSidechain"] = True  # type: ignore[assignment]
+    return entry
+
+
+def _user_entry(text="hello"):
+    """Build a transcript entry with user role."""
+    return {"message": {"role": "user", "content": text}}
+
+
+# =============================================
+# 1. _format_content_block
+# =============================================
+
+
+class TestFormatContentBlock:
+    """Unit tests for _format_content_block."""
+
+    def test_text_block(self):
+        result = BaseBot._format_content_block({"type": "text", "text": "Hello world"})
+        assert result == "Hello world"
+
+    def test_text_block_empty(self):
+        result = BaseBot._format_content_block({"type": "text", "text": "   "})
+        assert result is None
+
+    def test_thinking_block(self):
+        result = BaseBot._format_content_block({"type": "thinking", "thinking": "Let me think..."})
+        assert result == "Thinking..."
+
+    def test_tool_use_block(self):
+        result = BaseBot._format_content_block({"type": "tool_use", "name": "Bash", "input": {}})
+        assert result == "Running Bash..."
+
+    def test_tool_use_no_name(self):
+        result = BaseBot._format_content_block({"type": "tool_use"})
+        assert result == "Running tool..."
+
+    def test_unknown_type(self):
+        result = BaseBot._format_content_block({"type": "server_tool_use"})
+        assert result is None
+
+    def test_not_dict(self):
+        result = BaseBot._format_content_block("not a dict")
+        assert result is None
+
+
+# =============================================
+# 2. _format_stream_entries
+# =============================================
+
+
+class TestFormatStreamEntries:
+    """Unit tests for _format_stream_entries."""
+
+    def test_text_entry(self):
+        entries = [_assistant_entry([{"type": "text", "text": "Answer here"}])]
+        result = BaseBot._format_stream_entries(entries)
+        assert result == "Answer here\n"
+
+    def test_thinking_then_text(self):
+        entries = [
+            _assistant_entry(
+                [
+                    {"type": "thinking", "thinking": "hmm"},
+                    {"type": "text", "text": "Done"},
+                ]
+            )
+        ]
+        result = BaseBot._format_stream_entries(entries)
+        assert result == "Thinking...\nDone\n"
+
+    def test_tool_use_entry(self):
+        entries = [_assistant_entry([{"type": "tool_use", "name": "Read"}])]
+        result = BaseBot._format_stream_entries(entries)
+        assert result == "Running Read...\n"
+
+    def test_skips_user_role(self):
+        entries = [_user_entry("hello")]
+        result = BaseBot._format_stream_entries(entries)
+        assert result == ""
+
+    def test_skips_sidechain(self):
+        entries = [_assistant_entry([{"type": "text", "text": "side"}], sidechain=True)]
+        result = BaseBot._format_stream_entries(entries)
+        assert result == ""
+
+    def test_multiple_entries(self):
+        entries = [
+            _assistant_entry([{"type": "tool_use", "name": "Bash"}]),
+            _assistant_entry([{"type": "text", "text": "Result"}]),
+        ]
+        result = BaseBot._format_stream_entries(entries)
+        assert result == "Running Bash...\nResult\n"
+
+    def test_string_content(self):
+        entries = [{"message": {"role": "assistant", "content": "plain string"}}]
+        result = BaseBot._format_stream_entries(entries)
+        assert result == "plain string\n"
+
+    def test_empty_entries(self):
+        result = BaseBot._format_stream_entries([])
+        assert result == ""
+
+
+# =============================================
+# 3. _tail_transcript_bytes
+# =============================================
+
+
+class TestTailTranscriptBytes:
+    """Unit tests for _tail_transcript_bytes."""
+
+    def test_new_lines_parsed(self, tmp_path, _patch_deps):
+        bot = _make_bot(tmp_path, _patch_deps)
+        transcript = tmp_path / "test.jsonl"
+        entries = [_assistant_entry([{"type": "text", "text": "Hello"}])]
+        _write_transcript(transcript, entries)
+
+        result_entries, new_offset = bot._tail_transcript_bytes(transcript, 0)
+        assert len(result_entries) == 1
+        assert result_entries[0]["message"]["content"][0]["text"] == "Hello"
+        assert new_offset > 0
+
+    def test_no_new_content(self, tmp_path, _patch_deps):
+        bot = _make_bot(tmp_path, _patch_deps)
+        transcript = tmp_path / "test.jsonl"
+        _write_transcript(transcript, [_assistant_entry([{"type": "text", "text": "Hi"}])])
+        size = transcript.stat().st_size
+
+        result_entries, new_offset = bot._tail_transcript_bytes(transcript, size)
+        assert result_entries == []
+        assert new_offset == size
+
+    def test_partial_line_not_consumed(self, tmp_path, _patch_deps):
+        bot = _make_bot(tmp_path, _patch_deps)
+        transcript = tmp_path / "test.jsonl"
+        complete = json.dumps(_assistant_entry([{"type": "text", "text": "A"}]))
+        partial = '{"incomplete": true'
+        transcript.write_bytes((complete + "\n" + partial).encode("utf-8"))
+
+        result_entries, new_offset = bot._tail_transcript_bytes(transcript, 0)
+        assert len(result_entries) == 1
+        assert new_offset == len(complete.encode("utf-8")) + 1  # includes the \n
+
+    def test_none_path(self, tmp_path, _patch_deps):
+        bot = _make_bot(tmp_path, _patch_deps)
+        result_entries, offset = bot._tail_transcript_bytes(None, 0)
+        assert result_entries == []
+        assert offset == 0
+
+    def test_missing_file(self, tmp_path, _patch_deps):
+        bot = _make_bot(tmp_path, _patch_deps)
+        missing = tmp_path / "nonexistent.jsonl"
+        result_entries, offset = bot._tail_transcript_bytes(missing, 0)
+        assert result_entries == []
+        assert offset == 0
+
+    def test_incremental_reads(self, tmp_path, _patch_deps):
+        """Two reads: first gets initial content, second gets appended content."""
+        bot = _make_bot(tmp_path, _patch_deps)
+        transcript = tmp_path / "test.jsonl"
+        entry1 = _assistant_entry([{"type": "text", "text": "First"}])
+        _write_transcript(transcript, [entry1])
+
+        entries1, offset1 = bot._tail_transcript_bytes(transcript, 0)
+        assert len(entries1) == 1
+
+        entry2 = _assistant_entry([{"type": "text", "text": "Second"}])
+        with open(transcript, "a", encoding="utf-8") as f:
+            f.write(json.dumps(entry2) + "\n")
+
+        entries2, offset2 = bot._tail_transcript_bytes(transcript, offset1)
+        assert len(entries2) == 1
+        assert entries2[0]["message"]["content"][0]["text"] == "Second"
+        assert offset2 > offset1
+
+
+# =============================================
+# 4. _stream_edit
+# =============================================
+
+
+class TestStreamEdit:
+    """Unit tests for _stream_edit (429/not-modified handling)."""
+
+    def test_success(self, tmp_path, _patch_deps):
+        bot = _make_bot(tmp_path, _patch_deps)
+        response = json.dumps({"ok": True}).encode("utf-8")
+        mock_resp = MagicMock()
+        mock_resp.read.return_value = response
+        mock_resp.__enter__ = MagicMock(return_value=mock_resp)
+        mock_resp.__exit__ = MagicMock(return_value=False)
+
+        with patch("apps.handlers.base_bot.urlopen", return_value=mock_resp):
+            ok, retry = bot._stream_edit(123, 456, "hello")
+        assert ok is True
+        assert retry == 0.0
+
+    def test_429_returns_retry_after(self, tmp_path, _patch_deps):
+        from urllib.error import HTTPError
+
+        bot = _make_bot(tmp_path, _patch_deps)
+
+        body = json.dumps(
+            {
+                "ok": False,
+                "error_code": 429,
+                "description": "Too Many Requests: retry after 15",
+                "parameters": {"retry_after": 15},
+            }
+        ).encode("utf-8")
+        err = HTTPError("url", 429, "Too Many Requests", None, None)  # type: ignore[arg-type]
+        err.read = MagicMock(return_value=body)
+
+        with patch("apps.handlers.base_bot.urlopen", side_effect=err):
+            ok, retry = bot._stream_edit(123, 456, "hello")
+        assert ok is False
+        assert retry == 15.0
+
+    def test_400_not_modified_treated_as_ok(self, tmp_path, _patch_deps):
+        from urllib.error import HTTPError
+
+        bot = _make_bot(tmp_path, _patch_deps)
+
+        body = json.dumps(
+            {
+                "ok": False,
+                "error_code": 400,
+                "description": "Bad Request: message is not modified",
+            }
+        ).encode("utf-8")
+        err = HTTPError("url", 400, "Bad Request", None, None)  # type: ignore[arg-type]
+        err.read = MagicMock(return_value=body)
+
+        with patch("apps.handlers.base_bot.urlopen", side_effect=err):
+            ok, retry = bot._stream_edit(123, 456, "same text")
+        assert ok is True
+        assert retry == 0.0
+
+    def test_other_error(self, tmp_path, _patch_deps):
+        bot = _make_bot(tmp_path, _patch_deps)
+        with patch("apps.handlers.base_bot.urlopen", side_effect=ConnectionError("fail")):
+            ok, retry = bot._stream_edit(123, 456, "hello")
+        assert ok is False
+        assert retry == 0.0
+
+
+# =============================================
+# 5. Pending file streaming flag
+# =============================================
+
+
+class TestPendingFileStreaming:
+    """Tests for streaming flag in write_pending_file."""
+
+    def test_no_streaming_key_when_off(self, tmp_path, _patch_deps):
+        bot = _make_bot(tmp_path, _patch_deps, stream=False)
+        with patch("apps.handlers.base_bot.PENDING_DIR", tmp_path):
+            bot.pending_file = tmp_path / "bot-stream_test.json"
+            bot.write_pending_file(123, 1, 2)
+        data = json.loads(bot.pending_file.read_text(encoding="utf-8"))
+        assert "streaming" not in data
+
+    def test_streaming_true_when_on(self, tmp_path, _patch_deps):
+        bot = _make_bot(tmp_path, _patch_deps, stream=True)
+        with patch("apps.handlers.base_bot.PENDING_DIR", tmp_path):
+            bot.pending_file = tmp_path / "bot-stream_test.json"
+            bot.write_pending_file(123, 1, 2)
+        data = json.loads(bot.pending_file.read_text(encoding="utf-8"))
+        assert data["streaming"] is True
+
+
+# =============================================
+# 6. Batch mode unchanged
+# =============================================
+
+
+class TestBatchModeUnchanged:
+    """Prove batch mode (stream=False) is byte-for-byte unchanged."""
+
+    def test_heartbeat_uses_edit_message_not_stream(self, tmp_path, _patch_deps):
+        """When stream=False, heartbeat calls edit_message (batch), not _stream_edit."""
+        bot = _make_bot(tmp_path, _patch_deps, stream=False)
+        bot._stream_edit = MagicMock(return_value=(True, 0.0))
+        bot._tmux_session_exists = MagicMock(return_value=True)
+
+        call_count = [0]
+
+        def delivered_after_one():
+            call_count[0] += 1
+            return call_count[0] >= 2
+
+        bot._is_pending_delivered = delivered_after_one
+        bot._heartbeat_stop = threading.Event()
+        bot._start_heartbeat(123, 456)
+        if bot._heartbeat_thread:
+            bot._heartbeat_thread.join(timeout=35)
+        bot._stream_edit.assert_not_called()
+        bot.edit_message.assert_called()
+
+    def test_stream_false_no_transcript_tail(self, tmp_path, _patch_deps):
+        """When stream=False, _tail_transcript_bytes is never called."""
+        bot = _make_bot(tmp_path, _patch_deps, stream=False)
+        bot._tail_transcript_bytes = MagicMock()
+        bot._heartbeat_stop = threading.Event()
+
+        call_count = [0]
+
+        def delivered_after_first():
+            call_count[0] += 1
+            return call_count[0] >= 1
+
+        bot._is_pending_delivered = delivered_after_first
+        bot._start_heartbeat(123, 456)
+        if bot._heartbeat_thread:
+            bot._heartbeat_thread.join(timeout=5)
+        bot._tail_transcript_bytes.assert_not_called()
+
+
+# =============================================
+# 7. Streaming loop integration
+# =============================================
+
+
+class TestStreamingLoop:
+    """Integration tests for _streaming_loop."""
+
+    def test_edits_with_transcript_content(self, tmp_path, _patch_deps):
+        """Streaming loop edits the processing message with transcript text."""
+        bot = _make_bot(tmp_path, _patch_deps, stream=True)
+        transcript = tmp_path / "transcript.jsonl"
+        bot._active_transcript_path = transcript
+
+        entry = _assistant_entry([{"type": "text", "text": "Live answer"}])
+        _write_transcript(transcript, [entry])
+
+        bot._stream_edit = MagicMock(return_value=(True, 0.0))
+
+        call_count = [0]
+
+        def stop_after_three():
+            call_count[0] += 1
+            return call_count[0] >= 3
+
+        bot._is_pending_delivered = stop_after_three
+        bot._tmux_session_exists = MagicMock(return_value=True)
+
+        # Write transcript AFTER byte_offset init (simulating turn content arriving)
+        original_stat = Path.stat
+
+        def fake_stat(self_path):
+            if self_path == transcript:
+                # Return 0 size initially so the loop reads from start
+                return type("FakeStat", (), {"st_size": 0})()
+            return original_stat(self_path)
+
+        bot._heartbeat_stop = threading.Event()
+        with patch.object(Path, "stat", fake_stat):
+            bot._streaming_loop(123, 456, time.time())
+
+        assert bot._stream_edit.call_count >= 1
+        edit_text = bot._stream_edit.call_args[0][2]
+        assert "Live answer" in edit_text
+
+    def test_skips_unchanged_buffer(self, tmp_path, _patch_deps):
+        """Streaming loop does not edit when buffer hasn't changed."""
+        bot = _make_bot(tmp_path, _patch_deps, stream=True)
+        transcript = tmp_path / "transcript.jsonl"
+        bot._active_transcript_path = transcript
+        _write_transcript(transcript, [])
+
+        call_count = [0]
+
+        def stop_after_three():
+            call_count[0] += 1
+            return call_count[0] >= 3
+
+        bot._is_pending_delivered = stop_after_three
+        bot._tmux_session_exists = MagicMock(return_value=True)
+        bot._stream_edit = MagicMock(return_value=(True, 0.0))
+        bot._heartbeat_stop = threading.Event()
+
+        bot._streaming_loop(123, 456, time.time())
+
+        # Should show "Processing..." but not re-edit identical text
+        first_call_text = bot._stream_edit.call_args_list[0][0][2] if bot._stream_edit.call_count > 0 else ""
+        for call_args in bot._stream_edit.call_args_list[1:]:
+            assert call_args[0][2] != first_call_text or "Processing..." not in first_call_text
+
+    def test_4096_rollover(self, tmp_path, _patch_deps):
+        """Buffer exceeding 4096 chars triggers message rollover."""
+        bot = _make_bot(tmp_path, _patch_deps, stream=True)
+        transcript = tmp_path / "transcript.jsonl"
+        bot._active_transcript_path = transcript
+
+        big_text = "A" * 5000
+        entry = _assistant_entry([{"type": "text", "text": big_text}])
+        _write_transcript(transcript, [entry])
+
+        bot._stream_edit = MagicMock(return_value=(True, 0.0))
+        bot.send_message = MagicMock(return_value={"message_id": 999})
+
+        call_count = [0]
+
+        def stop_after_three():
+            call_count[0] += 1
+            return call_count[0] >= 3
+
+        bot._is_pending_delivered = stop_after_three
+        bot._tmux_session_exists = MagicMock(return_value=True)
+        bot._heartbeat_stop = threading.Event()
+
+        with patch.object(Path, "stat", lambda s: type("S", (), {"st_size": 0})()):
+            bot._streaming_loop(123, 456, time.time())
+
+        # Should have called send_message for the rollover
+        bot.send_message.assert_called()
+
+    def test_429_pauses_edits(self, tmp_path, _patch_deps):
+        """After a 429, streaming loop skips edits until retry_after elapses."""
+        bot = _make_bot(tmp_path, _patch_deps, stream=True)
+        transcript = tmp_path / "transcript.jsonl"
+        bot._active_transcript_path = transcript
+
+        entry = _assistant_entry([{"type": "text", "text": "data"}])
+        _write_transcript(transcript, [entry])
+
+        edit_calls = [0]
+
+        def rate_limited_edit(_chat, _msg, _text):
+            edit_calls[0] += 1
+            if edit_calls[0] == 1:
+                return False, 9999.0  # huge backoff
+            return True, 0.0
+
+        bot._stream_edit = MagicMock(side_effect=rate_limited_edit)
+
+        tick = [0]
+
+        def stop_after_three():
+            tick[0] += 1
+            return tick[0] >= 3
+
+        bot._is_pending_delivered = stop_after_three
+        bot._tmux_session_exists = MagicMock(return_value=True)
+        bot._heartbeat_stop = threading.Event()
+
+        with patch.object(Path, "stat", lambda s: type("S", (), {"st_size": 0})()):
+            bot._streaming_loop(123, 456, time.time())
+
+        # Only 1 edit attempt — subsequent ticks skipped due to 429 backoff
+        assert bot._stream_edit.call_count == 1
+
+    def test_fallback_to_batch_when_no_transcript(self, tmp_path, _patch_deps):
+        """When stream=True but no transcript path, falls back to batch heartbeat."""
+        bot = _make_bot(tmp_path, _patch_deps, stream=True)
+        bot._active_transcript_path = None  # no transcript
+        bot._stream_edit = MagicMock(return_value=(True, 0.0))
+        bot._tmux_session_exists = MagicMock(return_value=True)
+
+        call_count = [0]
+
+        def delivered_after_one():
+            call_count[0] += 1
+            return call_count[0] >= 2
+
+        bot._is_pending_delivered = delivered_after_one
+        bot._heartbeat_stop = threading.Event()
+        bot._start_heartbeat(123, 456)
+        if bot._heartbeat_thread:
+            bot._heartbeat_thread.join(timeout=35)
+
+        # Batch mode: edit_message called, _stream_edit not called
+        bot.edit_message.assert_called()
+        bot._stream_edit.assert_not_called()
+
+    def test_mid_loop_delivery_breaks_without_edit(self, tmp_path, _patch_deps):
+        """If _is_pending_delivered flips True mid-loop, loop breaks with no _stream_edit."""
+        bot = _make_bot(tmp_path, _patch_deps, stream=True)
+        transcript = tmp_path / "transcript.jsonl"
+        bot._active_transcript_path = transcript
+
+        entry = _assistant_entry([{"type": "text", "text": "Should not be sent"}])
+        _write_transcript(transcript, [entry])
+
+        delivered = [False]
+
+        def flip_on_second_check():
+            if delivered[0]:
+                return True
+            delivered[0] = True
+            return False
+
+        bot._is_pending_delivered = flip_on_second_check
+        bot._tmux_session_exists = MagicMock(return_value=True)
+        bot._stream_edit = MagicMock(return_value=(True, 0.0))
+        bot._heartbeat_stop = threading.Event()
+
+        with patch.object(Path, "stat", lambda s: type("S", (), {"st_size": 0})()):
+            bot._streaming_loop(123, 456, time.time())
+
+        bot._stream_edit.assert_not_called()
+
+    def test_stream_flag_wired_from_init(self, tmp_path, _patch_deps):
+        """stream=True in constructor sets self._stream."""
+        bot = _make_bot(tmp_path, _patch_deps, stream=True)
+        assert bot._stream is True
+
+    def test_stream_default_false(self, tmp_path, _patch_deps):
+        """stream defaults to False."""
+        bot = _make_bot(tmp_path, _patch_deps)
+        assert bot._stream is False
diff --git a/src/aipass/skills/templates/full/apps/__init__.py b/src/aipass/skills/templates/full/apps/__init__.py
index 39ea0f03..a46acb3a 100644
--- a/src/aipass/skills/templates/full/apps/__init__.py
+++ b/src/aipass/skills/templates/full/apps/__init__.py
@@ -3,5 +3,5 @@
 # Name: __init__.py - {{SKILL_NAME}} apps package
 # Date: 2026-03-07
 # Version: 1.0.0
-# Category: skills/catalog/{{SKILL_NAME}}/apps
+# Category: skills/{{SKILL_NAME}}/apps
 # =============================================
diff --git a/src/aipass/skills/templates/full/apps/handlers/__init__.py b/src/aipass/skills/templates/full/apps/handlers/__init__.py
index 00bdc3c8..4da904bc 100644
--- a/src/aipass/skills/templates/full/apps/handlers/__init__.py
+++ b/src/aipass/skills/templates/full/apps/handlers/__init__.py
@@ -3,7 +3,7 @@
 # Name: __init__.py - {{SKILL_NAME}} handlers package
 # Date: 2026-03-07
 # Version: 1.0.0
-# Category: skills/catalog/{{SKILL_NAME}}/apps/handlers
+# Category: skills/{{SKILL_NAME}}/apps/handlers
 #
 # CHANGELOG (Max 5 entries):
 #   - v1.0.0 (2026-03-07): Initial scaffold
diff --git a/src/aipass/skills/templates/full/apps/modules/__init__.py b/src/aipass/skills/templates/full/apps/modules/__init__.py
index 37ce0633..9363b004 100644
--- a/src/aipass/skills/templates/full/apps/modules/__init__.py
+++ b/src/aipass/skills/templates/full/apps/modules/__init__.py
@@ -3,7 +3,7 @@
 # Name: __init__.py - {{SKILL_NAME}} modules package
 # Date: 2026-03-07
 # Version: 1.0.0
-# Category: skills/catalog/{{SKILL_NAME}}/apps/modules
+# Category: skills/{{SKILL_NAME}}/apps/modules
 #
 # CHANGELOG (Max 5 entries):
 #   - v1.0.0 (2026-03-07): Initial scaffold
diff --git a/src/aipass/skills/tests/test_discovery.py b/src/aipass/skills/tests/test_discovery.py
index 91acf4af..1f357224 100644
--- a/src/aipass/skills/tests/test_discovery.py
+++ b/src/aipass/skills/tests/test_discovery.py
@@ -142,7 +142,7 @@ class TestParseSimpleValue:
 
 class TestDiscoverSkillsInPath:
     def test_finds_catalog_skills(self):
-        catalog_path = Path(__file__).resolve().parent.parent / "catalog"
+        catalog_path = Path(__file__).resolve().parent.parent / "lib"
         skills = discover_skills_in_path(catalog_path, "builtin")
         names = {s["name"] for s in skills}
         assert "github" in names
@@ -159,7 +159,7 @@ class TestDiscoverSkillsInPath:
             assert skills == []
 
     def test_skill_dict_structure(self):
-        catalog_path = Path(__file__).resolve().parent.parent / "catalog"
+        catalog_path = Path(__file__).resolve().parent.parent / "lib"
         skills = discover_skills_in_path(catalog_path, "builtin")
         for skill in skills:
             assert "name" in skill
@@ -170,7 +170,7 @@ class TestDiscoverSkillsInPath:
             assert "tags" in skill
 
     def test_has_handler_flag(self):
-        catalog_path = Path(__file__).resolve().parent.parent / "catalog"
+        catalog_path = Path(__file__).resolve().parent.parent / "lib"
         skills = discover_skills_in_path(catalog_path, "builtin")
         skill_map = {s["name"]: s for s in skills}
         assert skill_map["github"]["has_handler"] is False
diff --git a/src/aipass/skills/tests/test_lifecycle.py b/src/aipass/skills/tests/test_lifecycle.py
index 7c85cfe9..423ed212 100644
--- a/src/aipass/skills/tests/test_lifecycle.py
+++ b/src/aipass/skills/tests/test_lifecycle.py
@@ -106,7 +106,7 @@ class TestCatalogSkillsLifecycle:
 
     def test_github_skill_full_cycle(self):
         """GitHub (Tier 1): discover -> load -> run returns instructions."""
-        catalog = Path(__file__).resolve().parent.parent / "catalog"
+        catalog = Path(__file__).resolve().parent.parent / "lib"
         skills = discover_skills_in_path(catalog, "builtin")
         github = [s for s in skills if s["name"] == "github"]
         assert len(github) == 1
diff --git a/src/aipass/spawn/.seedgo/bypass.json b/src/aipass/spawn/.seedgo/bypass.json
index 8858505f..13915e60 100644
--- a/src/aipass/spawn/.seedgo/bypass.json
+++ b/src/aipass/spawn/.seedgo/bypass.json
@@ -5,6 +5,11 @@
     "description": "Standards bypass configuration for this branch"
   },
   "bypass": [
+    {
+      "file": "apps/spawn.py",
+      "standard": "architecture",
+      "reason": "\"No template for citizen_class 'builder'\" does not reproduce — spawn.py contains no \"builder\" string (verified via grep). builder was renamed to aipass_framework and birthright was retired; DEFAULT_CLASS in class_registry.py is aipass_framework. Stale/cached checker finding predating the rename."
+    },
     {
       "file": "apps/handlers/json_ops.py",
       "standard": "json_structure",
@@ -96,9 +101,29 @@
       "reason": "Imports registry.find_registry — placeholder resolution needs registry path lookup. Registry is a shared data handler."
     },
     {
-      "file": "apps/handlers/passport_ops.py",
+      "file": "apps/handlers/passport_ops(disabled).py",
       "standard": "handlers",
-      "reason": "Imports metadata functions — passport creation needs branch name extraction. Metadata is a shared utility handler."
+      "reason": "RETIRED — birthright passport command disabled per TDPLAN-0010. File renamed, not deleted."
+    },
+    {
+      "file": "apps/handlers/passport_ops(disabled).py",
+      "standard": "naming",
+      "reason": "RETIRED — birthright passport command disabled per TDPLAN-0010. '(disabled)' suffix is the intentional disable-in-place marker so the module is excluded from imports/discovery without deleting history; not a snake_case violation to fix."
+    },
+    {
+      "file": "apps/modules/passport(disabled).py",
+      "standard": "handlers",
+      "reason": "RETIRED — birthright passport command disabled per TDPLAN-0010. File renamed, not deleted."
+    },
+    {
+      "file": "apps/modules/passport(disabled).py",
+      "standard": "naming",
+      "reason": "RETIRED — birthright passport command disabled per TDPLAN-0010. '(disabled)' suffix is the intentional disable-in-place marker so the module is excluded from imports/discovery without deleting history; not a snake_case violation to fix."
+    },
+    {
+      "file": "apps/modules/passport(disabled).py",
+      "standard": "architecture",
+      "reason": "RETIRED — birthright passport command disabled per TDPLAN-0010. No template for citizen_class \"builder\" is expected: builder was renamed to aipass_framework and birthright was retired; this disabled module is dead code kept for history only."
     },
     {
       "file": "apps/handlers/json/json_handler.py",
@@ -116,9 +141,9 @@
       "reason": "dest, source are local variables inside helper functions, not module-level constants. Path objects for template/branch comparison."
     },
     {
-      "file": "apps/handlers/passport_ops.py",
+      "file": "apps/handlers/passport_ops(disabled).py",
       "standard": "naming",
-      "reason": "trinity_dir, role, profile are local variables/parameters inside grant_passport(), not module-level constants."
+      "reason": "RETIRED — birthright passport command disabled per TDPLAN-0010."
     },
     {
       "file": "apps/handlers/delete_ops.py",
@@ -126,9 +151,9 @@
       "reason": "delete_branch() has a docstring at line 45 — checker doesn't recognize it due to multi-line function signature spanning lines 40-44."
     },
     {
-      "file": "apps/handlers/passport_ops.py",
+      "file": "apps/handlers/passport_ops(disabled).py",
       "standard": "documentation",
-      "reason": "grant_passport() has a docstring at line 47 — checker doesn't recognize it due to multi-line function signature spanning lines 42-46."
+      "reason": "RETIRED — birthright passport command disabled per TDPLAN-0010."
     },
     {
       "file": "apps/handlers/regenerate_registry_ops.py",
@@ -170,6 +195,52 @@
       "standard": "encapsulation",
       "reason": "Test file — tests must import handlers directly to test them in isolation. Handler imports inside test methods are intentional."
     },
+    {
+      "file": "tests/conftest.py",
+      "standard": "architecture",
+      "reason": "Test file — lives in tests/ by convention, not in the 3-layer app structure. Test files are exempt from layer architecture standard."
+    },
+    {
+      "file": "tests/conftest.py",
+      "standard": "encapsulation",
+      "reason": "Test file — shared fixtures patch handler-owned internals directly (e.g. file_ops.json_handler, json_handler._JSON_DIR) to isolate tests from real I/O. Direct handler import is required for patch.object targeting."
+    },
+    {
+      "file": "tests/conftest.py",
+      "standard": "meta",
+      "reason": "Test file — pytest fixture module, exempt from application-code META header block convention."
+    },
+    {
+      "file": "tests/conftest.py",
+      "standard": "trigger",
+      "lines": [45],
+      "reason": "backup.unlink() removes a temporary AIPASS_REGISTRY.json.test_backup file created and owned entirely within the _protect_registry test fixture (session-scoped teardown). Not a production data deletion — no trigger.fire() needed for test-harness cleanup of its own scratch file."
+    },
+    {
+      "file": "tests/test_handlers.py",
+      "standard": "architecture",
+      "reason": "Test file — lives in tests/ by convention, not in the 3-layer app structure. Test files are exempt from layer architecture standard."
+    },
+    {
+      "file": "tests/test_handlers.py",
+      "standard": "encapsulation",
+      "reason": "Test file — tests must import handlers directly to test them in isolation. Handler imports inside test methods are intentional."
+    },
+    {
+      "file": "tests/test_regenerate_registry_ops.py",
+      "standard": "architecture",
+      "reason": "Test file — lives in tests/ by convention, not in the 3-layer app structure. Test files are exempt from layer architecture standard."
+    },
+    {
+      "file": "tests/test_regenerate_registry_ops.py",
+      "standard": "encapsulation",
+      "reason": "Test file — tests must import handlers directly (regenerate_template_registry, _scan_template_directory, _next_id) to test them in isolation. Direct handler import is intentional."
+    },
+    {
+      "file": "tests/test_regenerate_registry_ops.py",
+      "standard": "documentation",
+      "reason": "Test file — pytest test_* functions are self-documenting via descriptive names (see test_lifecycle.py, test_update.py precedent); docstrings not required on individual test cases by this branch's convention."
+    },
     {
       "file": "tests/test_cli_routing.py",
       "standard": "architecture",
@@ -231,6 +302,11 @@
       "file": "apps/handlers/meta_ops.py",
       "standard": "unused_function",
       "reason": "load_branch_meta() no longer called by P1 engine but has tests and may be reused by sync-registry or P2 shared library."
+    },
+    {
+      "file": "apps/modules/core.py",
+      "standard": "encapsulation",
+      "reason": "Local import of render_all_meta_tabs from memory.apps.handlers.tracking.tab_renderer — @memory has no module entry point for this API. Cross-branch contract per FPLAN-0286."
     }
   ],
   "notes": {
diff --git a/src/aipass/spawn/README.md b/src/aipass/spawn/README.md
index 767b0b0f..66b4377e 100644
--- a/src/aipass/spawn/README.md
+++ b/src/aipass/spawn/README.md
@@ -10,8 +10,7 @@
 
 ## What I Do
 
-- Create new branches from class-scoped templates (builder, birthright)
-- Grant birthright citizenship via the `passport` command
+- Create new branches from class-scoped templates (aipass_framework)
 - Update branches from templates (single or batch by class, with --dry-run)
 - Delete branches (archive + deregister)
 - Sync registry and templates against filesystem
@@ -27,8 +26,7 @@ Every branch belongs to a **citizen class**, which determines its template:
 
 | Class | Template | What It Creates |
 |-------|----------|-----------------|
-| `builder` (default) | `templates/builder/` | Full 3-layer scaffold: .trinity/, .aipass/, apps/ (modules/ + handlers/), tests/, docs/, logs/ |
-| `birthright` | `templates/birthright/` | Minimal citizenship: .trinity/, .aipass/, README.md |
+| `aipass_framework` (default) | `templates/aipass_framework/` | Full 3-layer scaffold: .trinity/, .aipass/, apps/ (modules/ + handlers/), tests/, docs/, logs/ |
 
 ---
 
@@ -39,19 +37,11 @@ All commands run through `drone @spawn <command>`.
 ### Create
 
 ```bash
-drone @spawn create <path>                                    # Create builder branch
+drone @spawn create <path>                                    # Create aipass_framework branch
 drone @spawn create <path> --role "Analyst" --purpose "Reports"  # With identity
-drone @spawn create --template birthright <path>               # Specific class
 drone @spawn create <path> --dry-run                           # Preview without touching disk
 drone @spawn create @existing                                  # Adopt pre-existing agent
-drone @spawn create ~/Projects/MyProject/agent_name            # External project (auto-detects registry)
-```
-
-### Passport
-
-```bash
-drone @spawn passport @dirname                                 # Grant birthright citizenship
-drone @spawn passport @dirname --role "Observer" --purpose "Monitoring"
+drone @spawn create ~/Projects/MyProject/agent_name            # External project (targets that project's own registry)
 ```
 
 ### Update
@@ -61,7 +51,7 @@ Update is **preview-only by default** — `--apply` required to execute changes.
 ```bash
 drone @spawn update @branch_name                               # Preview changes (dry-run default)
 drone @spawn update @branch_name --apply                       # Execute changes
-drone @spawn update builder --all --apply                      # All builder-class branches
+drone @spawn update aipass_framework --all --apply              # All aipass_framework-class branches
 drone @spawn update @branch_name --dry-run                     # Explicit preview (same as default)
 ```
 
@@ -77,7 +67,7 @@ drone @spawn delete @branch_name                               # Archive + dereg
 drone @spawn sync-registry                                     # Report healthy/stale/unregistered
 drone @spawn sync-registry --fix                               # Rebuild .spawn/ tracking + fix passport registry_ids
 drone @spawn sync-templates                                    # Pull managed files from sources (partial — see Known Issues)
-drone @spawn regenerate-registry                               # Regenerate builder template hashes
+drone @spawn regenerate-registry                               # Regenerate aipass_framework template hashes
 drone @spawn regenerate-registry --all                         # All template classes
 
 # Repair (preview-only by default — --apply required to execute)
@@ -121,7 +111,6 @@ spawn/
 │   ├── spawn.py                         # Entry point — CLI routing, version, help
 │   ├── modules/
 │   │   ├── core.py                      # Create orchestrator (_spawn_agent, handle_command)
-│   │   ├── passport.py                  # Passport CLI — birthright citizenship
 │   │   ├── update.py                    # Update CLI — single/batch by class
 │   │   ├── delete.py                    # Delete CLI — archive + deregister
 │   │   ├── sync_registry.py             # Registry repair CLI
@@ -134,9 +123,6 @@ spawn/
 │       ├── placeholders.py              # {{PLACEHOLDER}} replacement engine
 │       ├── registry.py                  # AIPASS_REGISTRY.json CRUD, find_registry()
 │       ├── meta_ops.py                  # Branch metadata generation, hash computation
-│       ├── change_detection.py          # ID-based file diff between template and branch
-│       ├── reconcile.py                 # Registry/filesystem reconciliation
-│       ├── passport_ops.py             # Passport grant implementation
 │       ├── update_ops.py                # Update workflow (Phase 0 snapshot → detect → execute)
 │       ├── delete_ops.py                # Delete workflow (resolve → archive → cleanup → deregister)
 │       ├── sync_registry_ops.py         # Registry sync (CWD-aware, external project support)
@@ -146,9 +132,8 @@ spawn/
 │       └── json/
 │           └── json_handler.py          # Standard JSON I/O, operation logging, 7 API functions
 ├── templates/
-│   ├── builder/                         # Full scaffold template (45 files, 24 dirs)
-│   └── birthright/                      # Minimal template
-├── tests/                               # 14 test files, 316 tests
+│   └── aipass_framework/                # Full scaffold template (44 files, 23 dirs)
+├── tests/                               # 14 test files, 297 tests
 ├── spawn_json/                          # JSON tracking directory
 ├── tools/                               # Branch verification utilities
 ├── docs/                                # Documentation
@@ -165,23 +150,16 @@ spawn/
 
 ## Workflows
 
-### Create (builder class)
+### Create (aipass_framework class)
 
 1. **Resolve** — Extract branch name from target path, validate path doesn't exist
 2. **Lookup** — Resolve citizen class to template directory via class_registry
 3. **Copy** — Recursive copy of class template to target (skips `__pycache__`)
 4. **Rename** — Replace `{{BRANCH}}` in directory and file names
-5. **Replace** — Substitute all `{{PLACEHOLDER}}` patterns in file contents
-6. **Registry** — Generate `.branch_meta.json`, register in `AIPASS_REGISTRY.json`
+5. **Replace** — Substitute all `{{PLACEHOLDER}}` patterns in file contents, including `{{CITIZEN_CLASS}}` (sourced from the create call, not a baked literal)
+6. **Registry** — Generate `.branch_meta.json` (meta tabs load from `@memory` when available, degrading gracefully to empty when it's not), register in the target project's own `AIPASS_REGISTRY.json`
 7. **Validate** — Scan for any remaining `{{...}}` patterns
 
-### Passport (birthright class)
-
-1. **Check** — Verify .trinity/ doesn't already exist
-2. **Copy** — Copy birthright template (.trinity/, .aipass/, README.md)
-3. **Replace** — Substitute placeholders in copied files
-4. **Register** — Add to AIPASS_REGISTRY.json
-
 ### Update (class-aware, Phase 0)
 
 1. **Snapshot** — Back up current `.branch_meta.json` and `.template_registry.json`
@@ -199,7 +177,7 @@ spawn/
 
 ## Tests
 
-**316 tests | 0 skipped | 0 failed** across 14 test files:
+**297 tests | 0 skipped | 0 failed** across 14 test files:
 
 | File | Focus |
 |------|-------|
@@ -248,11 +226,11 @@ spawn/
 - **Seedgo:** 100% (34/34)
 - **Tests:** 253 passed, 0 skipped, 0 failed
 - **Module coverage:** 23/23 (100%)
-- **Template registry:** 45 files, 24 dirs (builder)
+- **Template registry:** 44 files, 23 dirs (aipass_framework)
 - **Battle test:** 17/17 commands pass (2026-04-22)
 
 ---
 
-*Last Updated: 2026-05-15*
+*Last Updated: 2026-07-01*
 
 [← Back to AIPass](../../../README.md)
diff --git a/src/aipass/spawn/apps/handlers/class_registry.py b/src/aipass/spawn/apps/handlers/class_registry.py
index ec54dd2e..bc898dc2 100644
--- a/src/aipass/spawn/apps/handlers/class_registry.py
+++ b/src/aipass/spawn/apps/handlers/class_registry.py
@@ -12,8 +12,7 @@ Maps citizen class names to their template directories. Each class
 defines a different level of branch scaffold.
 
 Classes:
-    builder     — Full 3-layer architecture (apps/, modules/, handlers/)
-    birthright  — Minimal citizenship (.trinity/, .aipass/, README.md only)
+    aipass_framework — Full 3-layer architecture (apps/, modules/, handlers/)
 """
 
 from pathlib import Path
@@ -23,27 +22,22 @@ _TEMPLATES_DIR = Path(__file__).parents[2] / "templates"
 
 # Registry of citizen classes and their template directories
 CITIZEN_CLASSES = {
-    "builder": {
-        "template_dir": "builder",
+    "aipass_framework": {
+        "template_dir": "aipass_framework",
         "description": "Full 3-layer branch with apps/, modules/, handlers/",
         "default": True,
     },
-    "birthright": {
-        "template_dir": "birthright",
-        "description": "Minimal citizenship — .trinity/, .aipass/, README.md",
-        "default": False,
-    },
 }
 
 # The default class when none is specified
-DEFAULT_CLASS = "builder"
+DEFAULT_CLASS = "aipass_framework"
 
 
 def get_template_dir(citizen_class: str = DEFAULT_CLASS) -> Path:
     """Return the absolute path to a citizen class template directory.
 
     Args:
-        citizen_class: Name of the citizen class (e.g. "builder", "birthright").
+        citizen_class: Name of the citizen class (e.g. "aipass_framework").
 
     Returns:
         Path to the template directory.
diff --git a/src/aipass/spawn/apps/handlers/meta_ops.py b/src/aipass/spawn/apps/handlers/meta_ops.py
index ec1844db..31f4fdce 100644
--- a/src/aipass/spawn/apps/handlers/meta_ops.py
+++ b/src/aipass/spawn/apps/handlers/meta_ops.py
@@ -36,11 +36,11 @@ _TEMPLATE_REGISTRY_FILE = ".template_registry.json"
 # =============================================================================
 
 
-def get_template_dir(citizen_class: str = "builder") -> Path:
+def get_template_dir(citizen_class: str = "aipass_framework") -> Path:
     """Return path to template directory for a citizen class.
 
     Args:
-        citizen_class: Name of the citizen class. Defaults to "builder".
+        citizen_class: Name of the citizen class. Defaults to "aipass_framework".
 
     Returns:
         Path to the template directory.
@@ -88,7 +88,7 @@ def load_template_registry(template_dir: Path) -> Optional[dict]:
     """Load .spawn/.template_registry.json from a template directory.
 
     Args:
-        template_dir: Path to the template directory (e.g. builder/).
+        template_dir: Path to the template directory (e.g. aipass_framework/).
 
     Returns:
         Parsed dict of the template registry, or None if missing/unreadable.
diff --git a/src/aipass/spawn/apps/handlers/passport_ops.py b/src/aipass/spawn/apps/handlers/passport_ops.py
deleted file mode 100644
index 7ce7c0d5..00000000
--- a/src/aipass/spawn/apps/handlers/passport_ops.py
+++ /dev/null
@@ -1,161 +0,0 @@
-# =================== AIPass ====================
-# Name: passport_ops.py
-# Description: Passport command — grants birthright citizenship to a directory
-# Version: 1.0.0
-# Created: 2026-03-07
-# Modified: 2026-03-10
-# =============================================
-
-"""Passport command implementation for granting birthright citizenship.
-
-Creates minimal citizen identity (.trinity/, .aipass/, README.md) and
-registers in AIPASS_REGISTRY.json without creating the full 3-layer scaffold.
-"""
-
-from pathlib import Path
-
-from aipass.prax import logger
-from aipass.spawn.apps.handlers.metadata import (
-    get_branch_name,
-    normalize_branch_name,
-    detect_profile,
-)
-from aipass.spawn.apps.handlers.placeholders import (
-    build_replacements_dict,
-    validate_no_placeholders,
-)
-from aipass.spawn.apps.handlers.file_ops import (
-    copy_template,
-    rename_placeholder_paths,
-    regenerate_template_registry,
-    ensure_directory,
-)
-from aipass.spawn.apps.handlers.registry import (
-    find_registry,
-    add_to_registry,
-    get_next_citizen_number,
-    ensure_project_has_owner,
-)
-from aipass.spawn.apps.handlers.class_registry import get_template_dir
-from aipass.spawn.apps.handlers.json import json_handler
-
-
-def grant_passport(
-    target_path: str,
-    role: str = "",
-    purpose: str = "",
-) -> dict:
-    """Grant birthright citizenship to a directory.
-
-    Creates .trinity/, .aipass/, README.md and registers in AIPASS_REGISTRY.json.
-    Does NOT create apps/ scaffold -- that's for builder class.
-
-    Args:
-        target_path: Path to the target directory (created if doesn't exist).
-        role: Optional role description for the passport.
-        purpose: Optional purpose description.
-
-    Returns:
-        Dict with results (success, branch_name, path, etc.)
-    """
-    target = Path(target_path).resolve()
-
-    # Check if already a citizen
-    trinity_dir = target / ".trinity"
-    if trinity_dir.exists():
-        return _error(f"Already a citizen -- .trinity/ exists at {target}")
-
-    # Get birthright template
-    template = get_template_dir("birthright")
-    if not template.exists():
-        return _error(f"Birthright template not found: {template}")
-
-    # Extract names
-    folder_name = get_branch_name(target)
-    branch_upper = normalize_branch_name(folder_name, "upper")
-    branch_lower = normalize_branch_name(folder_name, "lower")
-    detected_profile = detect_profile(target)
-
-    # Registry setup
-    reg_path = find_registry(target.parent)
-    citizen_number = get_next_citizen_number(reg_path)
-
-    # Build placeholder replacements
-    replacements = build_replacements_dict(
-        target,
-        folder_name,
-        role=role,
-        purpose=purpose or "Birthright citizen - purpose TBD",
-        profile=detected_profile,
-        citizen_number=citizen_number,
-    )
-
-    # Create directory if needed
-    ensure_directory(target)
-
-    # Copy birthright template with placeholder replacement
-    copied, _ = copy_template(template, target, replacements)
-
-    # Rename any placeholder paths
-    _ = rename_placeholder_paths(target, folder_name)
-
-    # Set owner field — first agent in the project is the owner
-    passport_path = target / ".trinity" / "passport.json"
-    if passport_path.exists():
-        passport_data = json_handler.read_json(passport_path)
-        if passport_data:
-            passport_data.setdefault("citizenship", {})["owner"] = citizen_number == 1
-            json_handler.write_json(passport_path, passport_data)
-
-    # Regenerate template registry
-    regenerate_template_registry(target)
-
-    # Register in AIPASS_REGISTRY.json (store relative path for portability)
-    try:
-        registry_branch_path = target.relative_to(reg_path.parent).as_posix()
-    except ValueError:
-        logger.warning("[passport] Cannot relativize path %s to registry %s, storing absolute", target, reg_path.parent)
-        registry_branch_path = target.as_posix()
-    registry_updated = add_to_registry(
-        reg_path,
-        branch_upper,
-        registry_branch_path,
-        detected_profile,
-        f"@{branch_lower}",
-        purpose or "Birthright citizen - purpose TBD",
-    )
-
-    # Ensure at least one agent in the project is the owner
-    ensure_project_has_owner(reg_path)
-
-    # Validate
-    issues = validate_no_placeholders(target)
-
-    logger.info(f"[passport] Granted birthright to {branch_upper} at {target}")
-    json_handler.log_operation("passport_created", data={"target": str(target)})
-
-    return {
-        "success": True,
-        "branch_name": branch_upper,
-        "path": str(target),
-        "citizen_class": "birthright",
-        "files_copied": len([c for c in copied if "(dir)" not in c]),
-        "registry_updated": registry_updated,
-        "registry_path": str(reg_path),
-        "validation_issues": issues,
-    }
-
-
-def _error(message: str) -> dict:
-    """Return error result dict."""
-    return {
-        "success": False,
-        "error": message,
-        "branch_name": "",
-        "path": "",
-        "citizen_class": "",
-        "files_copied": 0,
-        "registry_updated": False,
-        "registry_path": "",
-        "validation_issues": [],
-    }
diff --git a/src/aipass/spawn/apps/handlers/placeholders.py b/src/aipass/spawn/apps/handlers/placeholders.py
index 5afa4ecf..573bdfbf 100644
--- a/src/aipass/spawn/apps/handlers/placeholders.py
+++ b/src/aipass/spawn/apps/handlers/placeholders.py
@@ -65,12 +65,17 @@ def build_replacements_dict(target_dir, branch_name, **overrides):
         "TRAITS": overrides.get("traits", ""),
         "PURPOSE_BRIEF": overrides.get("purpose", "New agent - purpose TBD"),
         "CITIZEN_NUMBER": str(overrides.get("citizen_number", 0)),
+        "CITIZEN_CLASS": overrides.get("citizen_class", "aipass_framework"),
         "REGISTRY_ID": registry_id,
         "KEY_CAPABILITIES": "",
         "DEPENDS_ON": "",
         "PROVIDES_TO": "",
     }
 
+    meta_tabs = overrides.get("meta_tabs")
+    if meta_tabs:
+        replacements.update(meta_tabs)
+
     return replacements
 
 
diff --git a/src/aipass/spawn/apps/handlers/regenerate_registry_ops.py b/src/aipass/spawn/apps/handlers/regenerate_registry_ops.py
index f677fccd..d0f234b4 100644
--- a/src/aipass/spawn/apps/handlers/regenerate_registry_ops.py
+++ b/src/aipass/spawn/apps/handlers/regenerate_registry_ops.py
@@ -49,7 +49,7 @@ def regenerate_template_registry(template_dir: Path) -> dict:
     on content hash first, then path, before assigning new IDs.
 
     Args:
-        template_dir: Absolute path to the template directory (e.g. builder/).
+        template_dir: Absolute path to the template directory (e.g. aipass_framework/).
 
     Returns:
         dict with keys: metadata, files, directories, stats.
diff --git a/src/aipass/spawn/apps/handlers/registry.py b/src/aipass/spawn/apps/handlers/registry.py
index 21bfc368..a79581d4 100644
--- a/src/aipass/spawn/apps/handlers/registry.py
+++ b/src/aipass/spawn/apps/handlers/registry.py
@@ -34,9 +34,10 @@ def branches_as_list(branches):
 
 
 def find_registry(start_path=None):
-    """Find *_REGISTRY.json — delegates to aipass.aipass.shared.registry_discovery.
+    """Find *_REGISTRY.json — walks up from start_path only.
 
-    Passes spawn's package root as the fallback for editable installs.
+    Does NOT pass package_root — prevents silent registration in
+    AIPass's own registry when creating agents in external projects.
 
     Args:
         start_path: Directory to start searching from.
@@ -46,7 +47,7 @@ def find_registry(start_path=None):
     """
     from aipass.aipass.shared.registry_discovery import find_registry as _common_find
 
-    return _common_find(start_path=start_path, package_root=Path(__file__).resolve().parent)
+    return _common_find(start_path=start_path)
 
 
 def load_registry(registry_path):
diff --git a/src/aipass/spawn/apps/handlers/sync_registry_ops.py b/src/aipass/spawn/apps/handlers/sync_registry_ops.py
index 8ddbf823..7c35a9d4 100644
--- a/src/aipass/spawn/apps/handlers/sync_registry_ops.py
+++ b/src/aipass/spawn/apps/handlers/sync_registry_ops.py
@@ -233,22 +233,22 @@ def sync_registry(fix: bool = False) -> dict:
             if not branch_meta_path.exists():
                 # Determine citizen class from passport
                 passport_path = branch_path / ".trinity" / "passport.json"
-                citizen_class = "builder"  # default
+                citizen_class = "aipass_framework"  # default
                 if passport_path.exists():
                     try:
                         passport = json.loads(passport_path.read_text(encoding="utf-8"))
-                        citizen_class = passport.get("identity", {}).get("citizen_class", "builder")
+                        citizen_class = passport.get("identity", {}).get("citizen_class", "aipass_framework")
                     except (json.JSONDecodeError, IOError) as e:
                         logger.warning(f"Failed to read passport for citizen class detection ({name}): {e}")
 
-                # Load template registry for that class (fall back to builder if unknown)
+                # Load template registry for that class (fall back to aipass_framework if unknown)
                 try:
                     template_dir = get_template_dir(citizen_class)
                 except ValueError:
                     logger.warning(
-                        f"[sync-registry] Unknown class '{citizen_class}' for {name}, falling back to builder"
+                        f"[sync-registry] Unknown class '{citizen_class}' for {name}, falling back to aipass_framework"
                     )
-                    template_dir = get_template_dir("builder")
+                    template_dir = get_template_dir("aipass_framework")
                 template_registry = load_template_registry(template_dir)
                 if template_registry:
                     branch_meta = generate_branch_meta(branch_path, template_registry)
diff --git a/src/aipass/spawn/apps/handlers/update_ops.py b/src/aipass/spawn/apps/handlers/update_ops.py
index be9e00e0..1a97aa42 100644
--- a/src/aipass/spawn/apps/handlers/update_ops.py
+++ b/src/aipass/spawn/apps/handlers/update_ops.py
@@ -264,19 +264,21 @@ def _read_citizen_class(branch_dir: Path) -> str:
 
     passport_path = branch_dir / ".trinity" / "passport.json"
     if not passport_path.exists():
-        return "builder"
+        return "aipass_framework"
     try:
         data = json.loads(passport_path.read_text(encoding="utf-8"))
-        citizen_class = data.get("identity", {}).get("citizen_class", "builder")
+        citizen_class = data.get("identity", {}).get("citizen_class", "aipass_framework")
         if not validate_class(citizen_class):
             logger.warning(
-                "[update] Unknown citizen_class '%s' in %s, falling back to 'builder'", citizen_class, passport_path
+                "[update] Unknown citizen_class '%s' in %s, falling back to 'aipass_framework'",
+                citizen_class,
+                passport_path,
             )
-            return "builder"
+            return "aipass_framework"
         return citizen_class
     except (json.JSONDecodeError, IOError) as e:
         logger.warning("[update] Failed to read citizen_class from passport %s: %s", passport_path, e)
-        return "builder"
+        return "aipass_framework"
 
 
 def _resolve_branch_path(branch_name: str) -> Path | None:
diff --git a/src/aipass/spawn/apps/modules/core.py b/src/aipass/spawn/apps/modules/core.py
index 07e456a3..66782407 100644
--- a/src/aipass/spawn/apps/modules/core.py
+++ b/src/aipass/spawn/apps/modules/core.py
@@ -57,7 +57,44 @@ from aipass.spawn.apps.handlers.class_registry import (
 from aipass.spawn.apps.handlers.json import json_handler
 
 # Default template location (relative to spawn package root)
-DEFAULT_TEMPLATE = Path(__file__).parents[2] / "templates" / "builder"
+DEFAULT_TEMPLATE = Path(__file__).parents[2] / "templates" / "aipass_framework"
+
+_PROJECT_MARKERS = (".git", "pyproject.toml", "setup.py", "setup.cfg")
+
+
+def _find_project_registry(target: Path) -> Path:
+    """Walk up from target to find a project root, return its registry path.
+
+    Used when the default find_registry returned a registry outside the
+    target's project (e.g. AIPass's own registry for an external target).
+    """
+    for parent in [target.parent] + list(target.parent.parents):
+        if any((parent / m).exists() for m in _PROJECT_MARKERS):
+            return parent / "AIPASS_REGISTRY.json"
+        if parent == parent.parent:
+            break
+    return target.parent / "AIPASS_REGISTRY.json"
+
+
+_META_TAB_KEYS = {"TODOS_META", "KEY_LEARNINGS_META", "SESSIONS_META", "OBSERVATIONS_META"}
+
+
+def _load_meta_tabs():
+    """Load memory meta-tab values from @memory's renderer.
+
+    Returns empty dict when @memory is unavailable (standalone project).
+    """
+    try:
+        from aipass.memory.apps.handlers.tracking.tab_renderer import render_all_meta_tabs
+    except ImportError:
+        logger.info("[spawn] @memory not available — meta-tab placeholders will be empty")
+        return {}
+
+    tabs = render_all_meta_tabs()
+    missing = _META_TAB_KEYS - set(tabs or {})
+    if missing:
+        raise RuntimeError(f"render_all_meta_tabs() missing keys: {sorted(missing)}")
+    return tabs
 
 
 def print_introspection():
@@ -157,7 +194,7 @@ def _spawn_agent(
     profile=None,
     template_dir=None,
     registry_path=None,
-    citizen_class="builder",
+    citizen_class="aipass_framework",
 ):
     """
     Create a new AIPass agent from template.
@@ -170,7 +207,7 @@ def _spawn_agent(
         profile: AIPass profile override (default: auto-detect)
         template_dir: Custom template directory (default: class-based lookup)
         registry_path: Path to AIPASS_REGISTRY.json (default: auto-discover)
-        citizen_class: Citizen class name (default: "builder")
+        citizen_class: Citizen class name (default: "aipass_framework")
 
     Returns:
         Dict with creation results:
@@ -214,11 +251,17 @@ def _spawn_agent(
     branch_lower = normalize_branch_name(folder_name, "lower")
     detected_profile = profile or detect_profile(target)
 
-    # Determine citizen number from registry
+    # Determine registry — per-project, never borrow another project's
     reg_path = Path(registry_path) if registry_path else find_registry(target.parent)
+    try:
+        target.relative_to(reg_path.parent)
+    except ValueError:
+        logger.info("[spawn] Target %s outside registry %s — resolving project-local registry", target, reg_path)
+        reg_path = _find_project_registry(target)
     citizen_number = get_next_citizen_number(reg_path)
 
     # Build placeholder replacements
+    meta_tabs = _load_meta_tabs()
     replacements = build_replacements_dict(
         target,
         folder_name,
@@ -227,6 +270,8 @@ def _spawn_agent(
         purpose=purpose or "New agent - purpose TBD",
         profile=detected_profile,
         citizen_number=citizen_number,
+        citizen_class=citizen_class,
+        meta_tabs=meta_tabs,
     )
 
     # Step 1: Copy template with placeholder replacement in content
@@ -312,8 +357,6 @@ def _adopt_existing(target, purpose, profile, registry_path):
     Returns:
         Result dict matching _spawn_agent return format.
     """
-    import json as _json
-
     folder_name = get_branch_name(target)
     branch_upper = normalize_branch_name(folder_name, "upper")
     branch_lower = normalize_branch_name(folder_name, "lower")
@@ -324,12 +367,9 @@ def _adopt_existing(target, purpose, profile, registry_path):
     # Read purpose from passport if not provided
     if not purpose:
         passport_path = target / ".trinity" / "passport.json"
-        try:
-            passport = _json.loads(passport_path.read_text(encoding="utf-8"))
-            purpose = passport.get("identity", {}).get("purpose", "Adopted agent")
-        except (ValueError, OSError) as e:
-            logger.warning("Failed to read passport for purpose: %s", e)
-            purpose = "Adopted agent"
+        # read_json returns None on failure (and logs) — same pattern as line ~250.
+        passport = json_handler.read_json(passport_path)
+        purpose = (passport or {}).get("identity", {}).get("purpose", "Adopted agent")
 
     # Fix registry_id in passport if it doesn't match the current registry
     fix_passport_registry_id(target, reg_path)
diff --git a/src/aipass/spawn/apps/modules/passport.py b/src/aipass/spawn/apps/modules/passport.py
deleted file mode 100644
index a1bc16e6..00000000
--- a/src/aipass/spawn/apps/modules/passport.py
+++ /dev/null
@@ -1,171 +0,0 @@
-# =================== AIPass ====================
-# Name: passport.py
-# Description: Passport command — thin CLI layer for granting birthright citizenship
-# Version: 1.0.0
-# Created: 2026-03-07
-# Modified: 2026-03-14
-# =============================================
-
-"""Passport command orchestrator for branch lifecycle management.
-
-Thin CLI module that parses arguments and delegates to the passport handler.
-All implementation logic lives in apps/handlers/passport_ops.py.
-"""
-
-import argparse
-
-from pathlib import Path
-
-from aipass.cli.apps.modules import console, error, warning
-from aipass.prax import logger
-
-from aipass.spawn.apps.handlers.passport_ops import grant_passport
-from aipass.spawn.apps.handlers.registry import find_registry
-from aipass.spawn.apps.handlers.json import json_handler
-
-
-def print_introspection():
-    """Display module introspection info."""
-    console.print()
-    console.print("[bold cyan]passport Module[/bold cyan]")
-    console.print("Grant birthright citizenship — minimal identity (.trinity/, .aipass/, README.md)")
-    console.print()
-    console.print("[yellow]Connected Handlers:[/yellow]")
-    console.print("  [cyan]handlers/[/cyan]")
-    console.print("    [dim]- passport_ops.py (grant_passport — create minimal citizen identity and register)[/dim]")
-    console.print()
-
-
-def handle_command(command: str, args: list) -> bool:
-    """Handle commands routed by the entry point.
-
-    Args:
-        command: The command string (e.g. "passport")
-        args: List of arguments for the command
-
-    Returns:
-        True if command was handled, False otherwise.
-    """
-    if command != "passport":
-        return False
-
-    # No args → introspection
-    if not args:
-        print_introspection()
-        return True
-
-    if "--help" in args:
-        print_introspection()
-        return True
-
-    return handle_passport(args) == 0
-
-
-def _search_src_subdirs(src_dir: Path, dirname: str) -> Path | None:
-    """Search src/*/dirname for an existing directory."""
-    if not src_dir.is_dir():
-        return None
-    for sub in src_dir.iterdir():
-        if not sub.is_dir():
-            continue
-        candidate = sub / dirname
-        if candidate.exists():
-            return candidate
-    return None
-
-
-def _resolve_target(dirname: str) -> Path:
-    """Resolve a @dirname to a filesystem path.
-
-    Searches CWD, project root (via registry), and src/ subdirectories.
-    For new directories, defaults to CWD-relative.
-    """
-    # Absolute or home-relative path — use directly
-    if dirname.startswith("/") or dirname.startswith("~"):
-        return Path(dirname).expanduser()
-
-    # 1. CWD-relative
-    cwd_path = Path.cwd() / dirname
-    if cwd_path.exists():
-        return cwd_path
-
-    # 2. Project-relative via registry
-    try:
-        reg_path = find_registry()
-        project_root = reg_path.parent
-        for candidate in [
-            project_root / dirname,
-            project_root / "src" / dirname,
-        ]:
-            if candidate.exists():
-                return candidate
-        # Search src/*/dirname (e.g., src/aipass/target)
-        found = _search_src_subdirs(project_root / "src", dirname)
-        if found:
-            return found
-    except Exception as exc:
-        logger.warning("[passport] Registry lookup failed during target resolution: %s", exc)
-
-    # 3. Default: CWD-relative (passport will create it if needed)
-    return cwd_path
-
-
-def handle_passport(args: list[str]) -> int:
-    """Parse args and execute passport grant.
-
-    Args patterns:
-        ["@dirname"]                    -> grant birthright to dirname
-        ["@dirname", "--role", "X"]     -> with role
-        ["@dirname", "--purpose", "X"]  -> with purpose
-
-    Returns exit code (0=success, 1=failure).
-    """
-    if not args:
-        warning("Usage: drone @spawn passport <@dirname> [--role ...] [--purpose ...]")
-        console.print()
-        console.print("  [dim]Grant birthright citizenship to a directory[/dim]")
-        console.print()
-        console.print("  [green]@dirname[/green]     Directory to grant citizenship (created if needed)")
-        warning("--role", details="Role description for the passport")
-        warning("--purpose", details="Purpose description")
-        return 1
-
-    # Intercept --help before argparse (argparse has add_help=False)
-    if "--help" in args or "-h" in args:
-        print_introspection()
-        return 0
-
-    parser = argparse.ArgumentParser(prog="spawn passport", add_help=False)
-    parser.add_argument("target")
-    parser.add_argument("--role", default="")
-    parser.add_argument("--purpose", default="")
-
-    parsed = parser.parse_args(args)
-
-    # Strip @ prefix if present
-    target = parsed.target.lstrip("@")
-
-    # Resolve target path — CWD-aware for external project support
-    target_path = _resolve_target(target)
-
-    result = grant_passport(
-        target_path=str(target_path),
-        role=parsed.role,
-        purpose=parsed.purpose,
-    )
-
-    if result["success"]:
-        json_handler.log_operation("passport_granted", data={"branch": result["branch_name"]})
-        console.print()
-        console.print(f"[green]Passport granted: {result['branch_name']}[/green]")
-        console.print("  Class: birthright")
-        console.print(f"  Path: {result['path']}")
-        console.print(f"  Files: {result['files_copied']}")
-        console.print(f"  Registry: {'updated' if result['registry_updated'] else 'not updated'}")
-        if result["validation_issues"]:
-            warning(f"{len(result['validation_issues'])} unreplaced placeholders")
-        console.print()
-        return 0
-    else:
-        error(result["error"])
-        return 1
diff --git a/src/aipass/spawn/apps/modules/regenerate_registry.py b/src/aipass/spawn/apps/modules/regenerate_registry.py
index 91553ca7..90cc5c7e 100644
--- a/src/aipass/spawn/apps/modules/regenerate_registry.py
+++ b/src/aipass/spawn/apps/modules/regenerate_registry.py
@@ -74,9 +74,8 @@ def handle_regenerate_registry(args: list[str]) -> int:
     """Parse args and execute template registry regeneration.
 
     Args patterns:
-        []              -> regenerate builder (default)
-        ["builder"]     -> regenerate builder template
-        ["birthright"]  -> regenerate birthright template
+        []                        -> regenerate aipass_framework (default)
+        ["aipass_framework"]      -> regenerate aipass_framework template
         ["--all"]       -> regenerate all template registries
         ["--help"]      -> show help
 
@@ -115,9 +114,9 @@ def handle_regenerate_registry(args: list[str]) -> int:
             json_handler.log_operation("regenerate_registry_all", data={"classes": list(classes)})
         return 1 if had_error else 0
 
-    # Single class — default to builder
+    # Single class — default to aipass_framework
     clean_args = [a for a in args if not a.startswith("--")]
-    class_name = clean_args[0] if clean_args else "builder"
+    class_name = clean_args[0] if clean_args else "aipass_framework"
 
     available = get_available_classes()
     if class_name not in available:
@@ -153,7 +152,7 @@ def _print_help() -> None:
     """Print usage help for regenerate-registry command."""
     warning("Usage: drone @spawn regenerate-registry [class_name | --all]")
     console.print()
-    console.print("  [green](no args)[/green]       Regenerate builder template registry (default)")
+    console.print("  [green](no args)[/green]       Regenerate aipass_framework template registry (default)")
     console.print("  [green]<class>[/green]          Regenerate registry for a specific template class")
     console.print("  [green]--all[/green]            Regenerate registries for all template classes")
     console.print()
diff --git a/src/aipass/spawn/apps/modules/update.py b/src/aipass/spawn/apps/modules/update.py
index 3d72b37e..f5b04423 100644
--- a/src/aipass/spawn/apps/modules/update.py
+++ b/src/aipass/spawn/apps/modules/update.py
@@ -79,8 +79,7 @@ def handle_update(args: list[str]) -> int:
 
     Args patterns:
         ["@branch"]                -> update single branch (uses passport's class)
-        ["builder", "--all"]       -> update all builder-class branches
-        ["birthright", "--all"]    -> update all birthright-class branches
+        ["aipass_framework", "--all"] -> update all aipass_framework-class branches
         ["--all"]                  -> BLOCKED (must specify class)
         ["--dry-run", "@branch"]   -> preview mode
         ["--dry-run", "--all"]     -> BLOCKED
@@ -93,8 +92,7 @@ def handle_update(args: list[str]) -> int:
         warning("Usage: drone @spawn update <@branch|class --all> [--apply] [--dry-run] [--trace]")
         console.print()
         console.print("  [green]@branch[/green]           Update a single branch (uses its own class)")
-        console.print("  [green]builder --all[/green]     Update all builder-class branches")
-        console.print("  [green]birthright --all[/green]  Update all birthright-class branches")
+        console.print("  [green]aipass_framework --all[/green]  Update all aipass_framework-class branches")
         console.print("  [green]--apply[/green]           Execute changes (default is preview-only)")
         console.print("  [green]--dry-run[/green]         Preview changes without modifying files [dim](default)[/dim]")
         console.print("  [green]--trace[/green]           Enable verbose logging")
@@ -104,8 +102,7 @@ def handle_update(args: list[str]) -> int:
         warning("Usage: drone @spawn update <@branch|class --all> [--apply] [--dry-run] [--trace]")
         console.print()
         console.print("  [green]@branch[/green]           Update a single branch (uses its own class)")
-        console.print("  [green]builder --all[/green]     Update all builder-class branches")
-        console.print("  [green]birthright --all[/green]  Update all birthright-class branches")
+        console.print("  [green]aipass_framework --all[/green]  Update all aipass_framework-class branches")
         console.print("  [green]--apply[/green]           Execute changes (default is preview-only)")
         console.print("  [green]--dry-run[/green]         Preview changes without modifying files [dim](default)[/dim]")
         console.print("  [green]--trace[/green]           Enable verbose logging")
diff --git a/src/aipass/spawn/apps/spawn.py b/src/aipass/spawn/apps/spawn.py
index 741dee7b..0d2a4f5c 100644
--- a/src/aipass/spawn/apps/spawn.py
+++ b/src/aipass/spawn/apps/spawn.py
@@ -30,7 +30,6 @@ def print_help():
     console.print("[bold cyan]USAGE:[/bold cyan]")
     console.print()
     console.print("  [dim]drone @spawn create [class] <target_path> [options][/dim]")
-    console.print("  [dim]drone @spawn passport <@dirname> [--role ...] [--purpose ...][/dim]")
     console.print("  [dim]drone @spawn update <@branch | class --all> [--apply][/dim]")
     console.print(
         "  [dim]drone @spawn repair <project_path> [--clean-pollution | --relocate @branch <path>] [--apply][/dim]"
@@ -40,7 +39,6 @@ def print_help():
     console.print("[bold cyan]COMMANDS:[/bold cyan]")
     console.print()
     console.print("  [green]create[/green] [class] <path>         Create a new branch from template")
-    console.print("  [green]passport[/green] <@dirname>           Grant birthright citizenship (minimal)")
     console.print(
         "  [green]update[/green] <@branch>              Update single branch from templates (preview-only by default)"
     )
@@ -63,16 +61,15 @@ def print_help():
     console.print("[bold cyan]CITIZEN CLASSES:[/bold cyan]")
     console.print()
     console.print(
-        "  [green]builder[/green]      Full 3-layer scaffold (apps/, modules/, handlers/) [dim][default][/dim]"
+        "  [green]aipass_framework[/green]  Full 3-layer scaffold (apps/, modules/, handlers/) [dim][default][/dim]"
     )
-    console.print("  [green]birthright[/green]   Minimal citizenship (.trinity/, .aipass/, README.md)")
     console.print()
     console.print("[bold cyan]OPTIONS:[/bold cyan]")
     console.print()
     warning("--role", details="Agent role description")
     warning("--traits", details="Agent personality traits")
     warning("--purpose", details="Agent purpose (brief)")
-    warning("--template", details="Template class name (builder, birthright) or custom directory path")
+    warning("--template", details="Template class name (aipass_framework) or custom directory path")
     warning("--registry", details="Path to AIPASS_REGISTRY.json")
     warning("--apply", details="Execute changes (update/repair are preview-only by default)")
     warning("--dry-run", details="Preview changes without modifying files (default for update/repair)")
@@ -118,7 +115,7 @@ def handle_create(args):
 
     parsed = parser.parse_args(remaining_args)
 
-    # --template can be a class name (e.g. "builder") or a raw path
+    # --template can be a class name (e.g. "aipass_framework") or a raw path
     template_dir = parsed.template
     if parsed.template and validate_class(parsed.template):
         citizen_class = parsed.template
@@ -212,7 +209,6 @@ def print_introspection():
     console.print("    [dim]- sync_registry.py (handle_sync_registry — registry repair)[/dim]")
     console.print("    [dim]- sync_templates.py (handle_sync_templates — template synchronization)[/dim]")
     console.print("    [dim]- regenerate_registry.py (handle_regenerate_registry — regenerate template registry)[/dim]")
-    console.print("    [dim]- passport.py (handle_passport — grant birthright citizenship)[/dim]")
     console.print("    [dim]- repair.py (handle_repair — project structure repair)[/dim]")
     console.print()
 
@@ -259,11 +255,6 @@ def main():
 
         return handle_sync_templates(remaining)
 
-    if command == "passport":
-        from aipass.spawn.apps.modules.passport import handle_passport
-
-        return handle_passport(remaining)
-
     if command == "regenerate-registry":
         from aipass.spawn.apps.modules.regenerate_registry import handle_regenerate_registry
 
diff --git a/src/aipass/spawn/templates/builder/.ai_mail.local/README.md b/src/aipass/spawn/templates/aipass_framework/.ai_mail.local/README.md
similarity index 100%
rename from src/aipass/spawn/templates/builder/.ai_mail.local/README.md
rename to src/aipass/spawn/templates/aipass_framework/.ai_mail.local/README.md
diff --git a/src/aipass/spawn/templates/builder/.ai_mail.local/inbox.json b/src/aipass/spawn/templates/aipass_framework/.ai_mail.local/inbox.json
similarity index 100%
rename from src/aipass/spawn/templates/builder/.ai_mail.local/inbox.json
rename to src/aipass/spawn/templates/aipass_framework/.ai_mail.local/inbox.json
diff --git a/src/aipass/spawn/templates/builder/.aipass/README.md b/src/aipass/spawn/templates/aipass_framework/.aipass/README.md
similarity index 100%
rename from src/aipass/spawn/templates/builder/.aipass/README.md
rename to src/aipass/spawn/templates/aipass_framework/.aipass/README.md
diff --git a/src/aipass/spawn/templates/birthright/.aipass/aipass_local_prompt.md b/src/aipass/spawn/templates/aipass_framework/.aipass/aipass_local_prompt.md
similarity index 100%
rename from src/aipass/spawn/templates/birthright/.aipass/aipass_local_prompt.md
rename to src/aipass/spawn/templates/aipass_framework/.aipass/aipass_local_prompt.md
diff --git a/src/aipass/spawn/templates/builder/.archive/README.md b/src/aipass/spawn/templates/aipass_framework/.archive/README.md
similarity index 100%
rename from src/aipass/spawn/templates/builder/.archive/README.md
rename to src/aipass/spawn/templates/aipass_framework/.archive/README.md
diff --git a/src/aipass/spawn/templates/builder/.claude/README.md b/src/aipass/spawn/templates/aipass_framework/.claude/README.md
similarity index 100%
rename from src/aipass/spawn/templates/builder/.claude/README.md
rename to src/aipass/spawn/templates/aipass_framework/.claude/README.md
diff --git a/src/aipass/spawn/templates/builder/.claude/settings.local.json b/src/aipass/spawn/templates/aipass_framework/.claude/settings.local.json
similarity index 100%
rename from src/aipass/spawn/templates/builder/.claude/settings.local.json
rename to src/aipass/spawn/templates/aipass_framework/.claude/settings.local.json
diff --git a/src/aipass/spawn/templates/builder/.gitignore b/src/aipass/spawn/templates/aipass_framework/.gitignore
similarity index 100%
rename from src/aipass/spawn/templates/builder/.gitignore
rename to src/aipass/spawn/templates/aipass_framework/.gitignore
diff --git a/src/aipass/spawn/templates/builder/.seedgo/README.md b/src/aipass/spawn/templates/aipass_framework/.seedgo/README.md
similarity index 100%
rename from src/aipass/spawn/templates/builder/.seedgo/README.md
rename to src/aipass/spawn/templates/aipass_framework/.seedgo/README.md
diff --git a/src/aipass/spawn/templates/builder/.seedgo/bypass.json b/src/aipass/spawn/templates/aipass_framework/.seedgo/bypass.json
similarity index 100%
rename from src/aipass/spawn/templates/builder/.seedgo/bypass.json
rename to src/aipass/spawn/templates/aipass_framework/.seedgo/bypass.json
diff --git a/src/aipass/spawn/templates/builder/.spawn/.registry_ignore.json b/src/aipass/spawn/templates/aipass_framework/.spawn/.registry_ignore.json
similarity index 100%
rename from src/aipass/spawn/templates/builder/.spawn/.registry_ignore.json
rename to src/aipass/spawn/templates/aipass_framework/.spawn/.registry_ignore.json
diff --git a/src/aipass/spawn/templates/builder/.spawn/.template_registry.json b/src/aipass/spawn/templates/aipass_framework/.spawn/.template_registry.json
similarity index 98%
rename from src/aipass/spawn/templates/builder/.spawn/.template_registry.json
rename to src/aipass/spawn/templates/aipass_framework/.spawn/.template_registry.json
index 7b52f18e..c7b3d70a 100644
--- a/src/aipass/spawn/templates/builder/.spawn/.template_registry.json
+++ b/src/aipass/spawn/templates/aipass_framework/.spawn/.template_registry.json
@@ -184,19 +184,19 @@
       "path": ".trinity/README.md"
     },
     "f012": {
-      "content_hash": "8f8a98e42d92",
+      "content_hash": "a68a905541ee",
       "has_branch_placeholder": false,
       "name": "local.json",
       "path": ".trinity/local.json"
     },
     "f013": {
-      "content_hash": "62160dfa243c",
+      "content_hash": "e51a865855a6",
       "has_branch_placeholder": false,
       "name": "observations.json",
       "path": ".trinity/observations.json"
     },
     "f014": {
-      "content_hash": "a05a4352e7a9",
+      "content_hash": "d523dee2ef39",
       "has_branch_placeholder": false,
       "name": "passport.json",
       "path": ".trinity/passport.json"
@@ -384,7 +384,7 @@
   },
   "metadata": {
     "description": "Template file tracking registry for ID-based updates",
-    "last_updated": "2026-06-11",
+    "last_updated": "2026-07-02",
     "version": "1.0.0"
   }
 }
diff --git a/src/aipass/spawn/templates/builder/.spawn/README.md b/src/aipass/spawn/templates/aipass_framework/.spawn/README.md
similarity index 100%
rename from src/aipass/spawn/templates/builder/.spawn/README.md
rename to src/aipass/spawn/templates/aipass_framework/.spawn/README.md
diff --git a/src/aipass/spawn/templates/builder/.trinity/README.md b/src/aipass/spawn/templates/aipass_framework/.trinity/README.md
similarity index 100%
rename from src/aipass/spawn/templates/builder/.trinity/README.md
rename to src/aipass/spawn/templates/aipass_framework/.trinity/README.md
diff --git a/src/aipass/spawn/templates/birthright/.trinity/local.json b/src/aipass/spawn/templates/aipass_framework/.trinity/local.json
similarity index 68%
rename from src/aipass/spawn/templates/birthright/.trinity/local.json
rename to src/aipass/spawn/templates/aipass_framework/.trinity/local.json
index 2613c10a..9fa49282 100644
--- a/src/aipass/spawn/templates/birthright/.trinity/local.json
+++ b/src/aipass/spawn/templates/aipass_framework/.trinity/local.json
@@ -12,14 +12,17 @@
       "work_log",
       "{{BRANCHNAME}}"
     ],
-    "_usage": "Automated file — add entries within your sections; rollover trims automatically. Limits live in @memory's memory.config.json.",
+    "_usage": "Automated file — add entries within your sections, newest on top. Rollover auto-archives sessions/key_learnings (+ observations.json) to @memory; todos[] are OPERATIONAL and NEVER rolled — prune done ones by hand at /prep. Limits live in @memory's memory.config.json.",
     "status": {
       "health": "healthy",
       "last_health_check": "{{DATE}}"
     }
   },
-  "key_learnings": [],
+  "todos_meta": "{{TODOS_META}}",
   "todos": [],
+  "key_learnings_meta": "{{KEY_LEARNINGS_META}}",
+  "key_learnings": [],
+  "sessions_meta": "{{SESSIONS_META}}",
   "sessions": [
     {
       "number": 1,
diff --git a/src/aipass/spawn/templates/birthright/.trinity/observations.json b/src/aipass/spawn/templates/aipass_framework/.trinity/observations.json
similarity index 76%
rename from src/aipass/spawn/templates/birthright/.trinity/observations.json
rename to src/aipass/spawn/templates/aipass_framework/.trinity/observations.json
index 8184b599..1f3938e0 100644
--- a/src/aipass/spawn/templates/birthright/.trinity/observations.json
+++ b/src/aipass/spawn/templates/aipass_framework/.trinity/observations.json
@@ -12,7 +12,7 @@
       "patterns",
       "{{BRANCHNAME}}"
     ],
-    "_usage": "Automated file — add entries within your sections; rollover trims automatically. Limits live in @memory's memory.config.json.",
+    "_usage": "Automated file — add entries within your sections, newest on top. Rollover auto-archives sessions/key_learnings (+ observations.json) to @memory; todos[] are OPERATIONAL and NEVER rolled — prune done ones by hand at /prep. Limits live in @memory's memory.config.json.",
     "status": {
       "health": "healthy",
       "last_health_check": "{{DATE}}"
@@ -22,6 +22,7 @@
     "purpose": "Capture collaboration patterns and experiential insights over time",
     "chronological_order": "Newest entries at TOP, oldest at BOTTOM - NEVER reorder"
   },
+  "observations_meta": "{{OBSERVATIONS_META}}",
   "observations": [
     {
       "number": 1,
diff --git a/src/aipass/spawn/templates/birthright/.trinity/passport.json b/src/aipass/spawn/templates/aipass_framework/.trinity/passport.json
similarity index 95%
rename from src/aipass/spawn/templates/birthright/.trinity/passport.json
rename to src/aipass/spawn/templates/aipass_framework/.trinity/passport.json
index 8d6c1212..3ad6f7d6 100644
--- a/src/aipass/spawn/templates/birthright/.trinity/passport.json
+++ b/src/aipass/spawn/templates/aipass_framework/.trinity/passport.json
@@ -18,7 +18,7 @@
     "git_branch": "work/{{branchname}}"
   },
   "identity": {
-    "citizen_class": "birthright",
+    "citizen_class": "{{CITIZEN_CLASS}}",
     "role": "{{ROLE}}",
     "purpose": "{{PURPOSE_BRIEF}}",
     "what_i_do": [],
diff --git a/src/aipass/spawn/templates/builder/DASHBOARD.local.json b/src/aipass/spawn/templates/aipass_framework/DASHBOARD.local.json
similarity index 100%
rename from src/aipass/spawn/templates/builder/DASHBOARD.local.json
rename to src/aipass/spawn/templates/aipass_framework/DASHBOARD.local.json
diff --git a/src/aipass/spawn/templates/builder/README.md b/src/aipass/spawn/templates/aipass_framework/README.md
similarity index 100%
rename from src/aipass/spawn/templates/builder/README.md
rename to src/aipass/spawn/templates/aipass_framework/README.md
diff --git a/src/aipass/spawn/templates/builder/apps/README.md b/src/aipass/spawn/templates/aipass_framework/apps/README.md
similarity index 100%
rename from src/aipass/spawn/templates/builder/apps/README.md
rename to src/aipass/spawn/templates/aipass_framework/apps/README.md
diff --git a/src/aipass/spawn/templates/builder/apps/__init__.py b/src/aipass/spawn/templates/aipass_framework/apps/__init__.py
similarity index 100%
rename from src/aipass/spawn/templates/builder/apps/__init__.py
rename to src/aipass/spawn/templates/aipass_framework/apps/__init__.py
diff --git a/src/aipass/spawn/templates/builder/apps/handlers/README.md b/src/aipass/spawn/templates/aipass_framework/apps/handlers/README.md
similarity index 100%
rename from src/aipass/spawn/templates/builder/apps/handlers/README.md
rename to src/aipass/spawn/templates/aipass_framework/apps/handlers/README.md
diff --git a/src/aipass/spawn/templates/builder/apps/handlers/__init__.py b/src/aipass/spawn/templates/aipass_framework/apps/handlers/__init__.py
similarity index 100%
rename from src/aipass/spawn/templates/builder/apps/handlers/__init__.py
rename to src/aipass/spawn/templates/aipass_framework/apps/handlers/__init__.py
diff --git a/src/aipass/spawn/templates/builder/apps/integrations/README.md b/src/aipass/spawn/templates/aipass_framework/apps/integrations/README.md
similarity index 100%
rename from src/aipass/spawn/templates/builder/apps/integrations/README.md
rename to src/aipass/spawn/templates/aipass_framework/apps/integrations/README.md
diff --git a/src/aipass/spawn/templates/builder/apps/modules/README.md b/src/aipass/spawn/templates/aipass_framework/apps/modules/README.md
similarity index 100%
rename from src/aipass/spawn/templates/builder/apps/modules/README.md
rename to src/aipass/spawn/templates/aipass_framework/apps/modules/README.md
diff --git a/src/aipass/spawn/templates/aipass_framework/apps/modules/__init__.py b/src/aipass/spawn/templates/aipass_framework/apps/modules/__init__.py
new file mode 100644
index 00000000..e69de29b
diff --git a/src/aipass/spawn/templates/builder/apps/plugins/README.md b/src/aipass/spawn/templates/aipass_framework/apps/plugins/README.md
similarity index 100%
rename from src/aipass/spawn/templates/builder/apps/plugins/README.md
rename to src/aipass/spawn/templates/aipass_framework/apps/plugins/README.md
diff --git a/src/aipass/spawn/templates/aipass_framework/apps/plugins/__init__.py b/src/aipass/spawn/templates/aipass_framework/apps/plugins/__init__.py
new file mode 100644
index 00000000..e69de29b
diff --git a/src/aipass/spawn/templates/builder/apps/{{BRANCH}}.py b/src/aipass/spawn/templates/aipass_framework/apps/{{BRANCH}}.py
similarity index 100%
rename from src/aipass/spawn/templates/builder/apps/{{BRANCH}}.py
rename to src/aipass/spawn/templates/aipass_framework/apps/{{BRANCH}}.py
diff --git a/src/aipass/spawn/templates/builder/artifacts/README.md b/src/aipass/spawn/templates/aipass_framework/artifacts/README.md
similarity index 100%
rename from src/aipass/spawn/templates/builder/artifacts/README.md
rename to src/aipass/spawn/templates/aipass_framework/artifacts/README.md
diff --git a/src/aipass/spawn/templates/builder/artifacts/birth_certificate.json b/src/aipass/spawn/templates/aipass_framework/artifacts/birth_certificate.json
similarity index 100%
rename from src/aipass/spawn/templates/builder/artifacts/birth_certificate.json
rename to src/aipass/spawn/templates/aipass_framework/artifacts/birth_certificate.json
diff --git a/src/aipass/spawn/templates/builder/docs.local/README.md b/src/aipass/spawn/templates/aipass_framework/docs.local/README.md
similarity index 100%
rename from src/aipass/spawn/templates/builder/docs.local/README.md
rename to src/aipass/spawn/templates/aipass_framework/docs.local/README.md
diff --git a/src/aipass/spawn/templates/builder/docs.local/sub_agent_drops/README.md b/src/aipass/spawn/templates/aipass_framework/docs.local/sub_agent_drops/README.md
similarity index 100%
rename from src/aipass/spawn/templates/builder/docs.local/sub_agent_drops/README.md
rename to src/aipass/spawn/templates/aipass_framework/docs.local/sub_agent_drops/README.md
diff --git a/src/aipass/spawn/templates/builder/docs/README.md b/src/aipass/spawn/templates/aipass_framework/docs/README.md
similarity index 100%
rename from src/aipass/spawn/templates/builder/docs/README.md
rename to src/aipass/spawn/templates/aipass_framework/docs/README.md
diff --git a/src/aipass/spawn/templates/builder/dropbox/README.md b/src/aipass/spawn/templates/aipass_framework/dropbox/README.md
similarity index 100%
rename from src/aipass/spawn/templates/builder/dropbox/README.md
rename to src/aipass/spawn/templates/aipass_framework/dropbox/README.md
diff --git a/src/aipass/spawn/templates/builder/logs/README.md b/src/aipass/spawn/templates/aipass_framework/logs/README.md
similarity index 100%
rename from src/aipass/spawn/templates/builder/logs/README.md
rename to src/aipass/spawn/templates/aipass_framework/logs/README.md
diff --git a/src/aipass/spawn/templates/builder/pytest.ini b/src/aipass/spawn/templates/aipass_framework/pytest.ini
similarity index 100%
rename from src/aipass/spawn/templates/builder/pytest.ini
rename to src/aipass/spawn/templates/aipass_framework/pytest.ini
diff --git a/src/aipass/spawn/templates/builder/requirements.project.txt b/src/aipass/spawn/templates/aipass_framework/requirements.project.txt
similarity index 100%
rename from src/aipass/spawn/templates/builder/requirements.project.txt
rename to src/aipass/spawn/templates/aipass_framework/requirements.project.txt
diff --git a/src/aipass/spawn/templates/builder/templates/README.md b/src/aipass/spawn/templates/aipass_framework/templates/README.md
similarity index 100%
rename from src/aipass/spawn/templates/builder/templates/README.md
rename to src/aipass/spawn/templates/aipass_framework/templates/README.md
diff --git a/src/aipass/spawn/templates/builder/tests/README.md b/src/aipass/spawn/templates/aipass_framework/tests/README.md
similarity index 100%
rename from src/aipass/spawn/templates/builder/tests/README.md
rename to src/aipass/spawn/templates/aipass_framework/tests/README.md
diff --git a/src/aipass/spawn/templates/builder/tests/__init__.py b/src/aipass/spawn/templates/aipass_framework/tests/__init__.py
similarity index 100%
rename from src/aipass/spawn/templates/builder/tests/__init__.py
rename to src/aipass/spawn/templates/aipass_framework/tests/__init__.py
diff --git a/src/aipass/spawn/templates/builder/tests/conftest.py b/src/aipass/spawn/templates/aipass_framework/tests/conftest.py
similarity index 100%
rename from src/aipass/spawn/templates/builder/tests/conftest.py
rename to src/aipass/spawn/templates/aipass_framework/tests/conftest.py
diff --git a/src/aipass/spawn/templates/builder/tools/README.md b/src/aipass/spawn/templates/aipass_framework/tools/README.md
similarity index 100%
rename from src/aipass/spawn/templates/builder/tools/README.md
rename to src/aipass/spawn/templates/aipass_framework/tools/README.md
diff --git a/src/aipass/spawn/templates/builder/{{BRANCH}}_json/README.md b/src/aipass/spawn/templates/aipass_framework/{{BRANCH}}_json/README.md
similarity index 100%
rename from src/aipass/spawn/templates/builder/{{BRANCH}}_json/README.md
rename to src/aipass/spawn/templates/aipass_framework/{{BRANCH}}_json/README.md
diff --git a/src/aipass/spawn/templates/builder/{{BRANCH}}_json/custom_config/README.md b/src/aipass/spawn/templates/aipass_framework/{{BRANCH}}_json/custom_config/README.md
similarity index 100%
rename from src/aipass/spawn/templates/builder/{{BRANCH}}_json/custom_config/README.md
rename to src/aipass/spawn/templates/aipass_framework/{{BRANCH}}_json/custom_config/README.md
diff --git a/src/aipass/spawn/templates/birthright/README.md b/src/aipass/spawn/templates/birthright/README.md
deleted file mode 100644
index d5f4e7d0..00000000
--- a/src/aipass/spawn/templates/birthright/README.md
+++ /dev/null
@@ -1,21 +0,0 @@
-# {{BRANCHNAME}}
-
-**Purpose:** {{PURPOSE_BRIEF}}
-**Module:** `aipass.{{MODULE}}`
-**Created:** {{DATE}}
-**Citizen Class:** birthright
-
----
-
-## Overview
-
-Birthright citizen — minimal presence with identity and memory.
-
----
-
-## Identity
-
-- **Passport:** `.trinity/passport.json`
-- **Session History:** `.trinity/local.json`
-- **Observations:** `.trinity/observations.json`
-- **Branch Prompt:** `.aipass/branch_system_prompt.md`
diff --git a/src/aipass/spawn/templates/builder/.aipass/aipass_local_prompt.md b/src/aipass/spawn/templates/builder/.aipass/aipass_local_prompt.md
deleted file mode 100644
index 416f419b..00000000
--- a/src/aipass/spawn/templates/builder/.aipass/aipass_local_prompt.md
+++ /dev/null
@@ -1,87 +0,0 @@
-# {{BRANCHNAME}} — Branch Prompt
-
-<!--
-INSTRUCTIONS FOR FILLING OUT THIS TEMPLATE
-==========================================
-
-This file is your local prompt. It gets injected every turn alongside the global prompt.
-The global prompt already covers: dispatch syntax, git workflow, hard rules, logging,
-memory system, breadcrumbs philosophy, and system-wide commands. Don't repeat any of that here.
-
-Your job: fill out each section below with content specific to YOUR branch.
-Replace the guidance text (in italics) with real content, then delete this instruction block.
-
-PRINCIPLES:
-- Breadcrumbs, not encyclopedias. Enough to navigate, not everything there is to know.
-- Operational, not descriptive. Tell the agent how to ACT, not just what things ARE.
-- Include concrete reference data — lookup tables, checklists, decision trees.
-- If you can run `drone @{{BRANCH}} --help` to get it, don't duplicate it here.
-- This file should be STABLE. If it changes every session, that content belongs in
-  .trinity/ instead.
-
-WHEN YOU'RE DONE:
-- Delete this instruction block
-- Delete all italic guidance text
-- What remains should be pure operational reference
--->
-
-*Injected every turn. Breadcrumbs only — details in README, --help, .trinity/ memories.*
-
-## Identity
-
-*One line. Who you are and what your role is. This is the first thing the agent reads every turn — make it count.*
-
-You are {{BRANCHNAME}} — {one-line role description}.
-
-## What I Do
-
-*3-5 bullets covering what happens in this branch. Not a mission statement — concrete actions. Think "if someone asked what this branch does day-to-day, what would you say?"*
-
-- {Primary responsibility}
-- {Secondary responsibility}
-- {What you build/maintain/operate}
-
-## Key Commands
-
-*The 5-8 commands you use most, with real arguments. Not your full command list — just the ones you'd need in 80% of sessions. Always show the full `drone @branch command [args]` syntax.*
-
-```
-drone @{{BRANCH}} {command1} [args]    # What it does
-drone @{{BRANCH}} {command2} [args]    # What it does
-```
-
-## Architecture
-
-*Your directory tree showing the code layout. Helps the agent find things without guessing. Skip this section entirely if your branch has no apps/ directory.*
-
-```
-apps/
-├── {{BRANCH}}.py          # Entry point
-├── modules/
-│   ├── {module1}.py     # What it orchestrates
-│   └── {module2}.py     # What it orchestrates
-└── handlers/
-    ├── {domain1}/       # What it handles
-    └── {domain2}/       # What it handles
-```
-
-## Integration
-
-*Which branches you depend on or serve. Every branch connects to others — document those relationships so the agent knows who to ask and who's asking.*
-
-- **Depends on:** @{branch} for {what}, @{branch} for {what}
-- **Serves:** @{branch} uses my {feature}, @{branch} calls my {command}
-
-## Working Habits
-
-*Behavioral patterns specific to this branch. How you approach work differently from other branches. Decision frameworks, common workflows, domain-specific patterns. Only include habits that are unique to this branch — if it applies to all branches, it's in the global prompt.*
-
-- {Habit or pattern that shapes how you work}
-- {Decision framework or workflow unique to this domain}
-
-## Known Gotchas
-
-*Non-obvious quirks, hard-won lessons, things that will waste 20 minutes if you don't know them. These are the breadcrumbs that save time — the stuff you'd tell a new agent on day one.*
-
-- {Gotcha or non-obvious behavior}
-- {Hard-won lesson from a past session}
diff --git a/src/aipass/spawn/templates/builder/.trinity/local.json b/src/aipass/spawn/templates/builder/.trinity/local.json
deleted file mode 100644
index 2613c10a..00000000
--- a/src/aipass/spawn/templates/builder/.trinity/local.json
+++ /dev/null
@@ -1,32 +0,0 @@
-{
-  "document_metadata": {
-    "document_type": "session_history",
-    "document_name": "{{BRANCHNAME}}.LOCAL",
-    "version": "2.0.0",
-    "schema_version": "3.0.0",
-    "created": "{{DATE}}",
-    "last_updated": "{{DATE}}",
-    "managed_by": "{{BRANCHNAME}}",
-    "tags": [
-      "session_tracking",
-      "work_log",
-      "{{BRANCHNAME}}"
-    ],
-    "_usage": "Automated file — add entries within your sections; rollover trims automatically. Limits live in @memory's memory.config.json.",
-    "status": {
-      "health": "healthy",
-      "last_health_check": "{{DATE}}"
-    }
-  },
-  "key_learnings": [],
-  "todos": [],
-  "sessions": [
-    {
-      "number": 1,
-      "date": "{{DATE}}",
-      "summary": "Branch initialized - {{BRANCHNAME}} created by aipass init.",
-      "status": "completed",
-      "tags": []
-    }
-  ]
-}
diff --git a/src/aipass/spawn/templates/builder/.trinity/observations.json b/src/aipass/spawn/templates/builder/.trinity/observations.json
deleted file mode 100644
index 8184b599..00000000
--- a/src/aipass/spawn/templates/builder/.trinity/observations.json
+++ /dev/null
@@ -1,33 +0,0 @@
-{
-  "document_metadata": {
-    "document_type": "collaboration_patterns",
-    "document_name": "{{BRANCHNAME}}.OBSERVATIONS",
-    "version": "1.0.0",
-    "schema_version": "3.0.0",
-    "created": "{{DATE}}",
-    "last_updated": "{{DATE}}",
-    "managed_by": "{{BRANCHNAME}}",
-    "tags": [
-      "collaboration",
-      "patterns",
-      "{{BRANCHNAME}}"
-    ],
-    "_usage": "Automated file — add entries within your sections; rollover trims automatically. Limits live in @memory's memory.config.json.",
-    "status": {
-      "health": "healthy",
-      "last_health_check": "{{DATE}}"
-    }
-  },
-  "guidelines": {
-    "purpose": "Capture collaboration patterns and experiential insights over time",
-    "chronological_order": "Newest entries at TOP, oldest at BOTTOM - NEVER reorder"
-  },
-  "observations": [
-    {
-      "number": 1,
-      "date": "{{DATE}}",
-      "note": "Branch initialized. Ready to begin capturing collaboration patterns.",
-      "tags": []
-    }
-  ]
-}
diff --git a/src/aipass/spawn/templates/builder/.trinity/passport.json b/src/aipass/spawn/templates/builder/.trinity/passport.json
deleted file mode 100644
index c016d8f3..00000000
--- a/src/aipass/spawn/templates/builder/.trinity/passport.json
+++ /dev/null
@@ -1,38 +0,0 @@
-{
-  "document_metadata": {
-    "document_type": "branch_identity",
-    "document_name": "{{BRANCHNAME}}.PASSPORT",
-    "version": "1.0.0",
-    "schema_version": "1.0.0",
-    "created": "{{DATE}}",
-    "last_updated": "{{DATE}}",
-    "managed_by": "{{BRANCHNAME}}",
-    "tags": ["identity", "passport", "branch_profile"]
-  },
-  "branch_info": {
-    "branch_name": "{{BRANCHNAME}}",
-    "alias": "",
-    "path": "{{CWD}}",
-    "module": "{{MODULE}}",
-    "created": "{{DATE}}",
-    "git_branch": "work/{{branchname}}"
-  },
-  "identity": {
-    "citizen_class": "builder",
-    "role": "{{ROLE}}",
-    "purpose": "{{PURPOSE_BRIEF}}",
-    "what_i_do": [],
-    "what_i_dont_do": []
-  },
-  "principles": [
-    "Code is truth - fail honestly",
-    "Memory persists - context survives",
-    "Simple solutions over complex architecture"
-  ],
-  "citizenship": {
-    "registered": true,
-    "registry_id": "{{REGISTRY_ID}}",
-    "communications": true,
-    "memory": true
-  }
-}
diff --git a/src/aipass/spawn/tests/conftest.py b/src/aipass/spawn/tests/conftest.py
index 27511724..93ccf462 100644
--- a/src/aipass/spawn/tests/conftest.py
+++ b/src/aipass/spawn/tests/conftest.py
@@ -63,7 +63,7 @@ def mock_infrastructure(tmp_path):
         (branch / d).mkdir(parents=True)
     passport = {
         "branch_info": {"branch_name": "test_branch"},
-        "identity": {"citizen_class": "builder"},
+        "identity": {"citizen_class": "aipass_framework"},
     }
     (branch / ".trinity" / "passport.json").write_text(json.dumps(passport), encoding="utf-8")
     return branch
diff --git a/src/aipass/spawn/tests/test_citizen_classes.py b/src/aipass/spawn/tests/test_citizen_classes.py
index dde5795d..553b8b9e 100644
--- a/src/aipass/spawn/tests/test_citizen_classes.py
+++ b/src/aipass/spawn/tests/test_citizen_classes.py
@@ -1,19 +1,18 @@
 # =================== META ====================
 # Name: test_citizen_classes.py
 # Description: Integration tests for citizen class system
-# Version: 1.0.0
+# Version: 1.1.0
 # Created: 2026-03-07
-# Modified: 2026-03-07
+# Modified: 2026-07-01
 # =============================================
 
 """Integration tests for the citizen class template system.
 
-Tests class registry, passport command, class-aware create,
+Tests class registry, class-aware create,
 class-aware update, and backward compatibility.
 """
 
 import json
-import unittest.mock
 
 import pytest
 from pathlib import Path
@@ -28,19 +27,17 @@ class TestClassRegistry:
     """Tests for apps/handlers/class_registry.py"""
 
     def test_get_available_classes(self):
-        """Returns list containing 'builder' and 'birthright'."""
+        """Returns list containing 'aipass_framework'."""
         from aipass.spawn.apps.handlers.class_registry import get_available_classes
 
         classes = get_available_classes()
-        assert "builder" in classes
-        assert "birthright" in classes
+        assert "aipass_framework" in classes
 
     def test_validate_class_valid(self):
         """Known class names validate as True."""
         from aipass.spawn.apps.handlers.class_registry import validate_class
 
-        assert validate_class("builder") is True
-        assert validate_class("birthright") is True
+        assert validate_class("aipass_framework") is True
 
     def test_validate_class_invalid(self):
         """Unknown or empty class names validate as False."""
@@ -49,26 +46,24 @@ class TestClassRegistry:
         assert validate_class("nonexistent") is False
         assert validate_class("") is False
 
+    def test_validate_class_retired_birthright(self):
+        """Retired 'birthright' class should validate as False."""
+        from aipass.spawn.apps.handlers.class_registry import validate_class
+
+        assert validate_class("birthright") is False
+
     def test_get_default_class(self):
-        """Default citizen class is 'builder'."""
+        """Default citizen class is 'aipass_framework'."""
         from aipass.spawn.apps.handlers.class_registry import get_default_class
 
-        assert get_default_class() == "builder"
+        assert get_default_class() == "aipass_framework"
 
-    def test_get_template_dir_builder(self):
-        """Builder template directory exists and is named 'builder'."""
+    def test_get_template_dir_aipass_framework(self):
+        """aipass_framework template directory exists and is named 'aipass_framework'."""
         from aipass.spawn.apps.handlers.class_registry import get_template_dir
 
-        path = get_template_dir("builder")
-        assert path.name == "builder"
-        assert path.exists()
-
-    def test_get_template_dir_birthright(self):
-        """Birthright template directory exists and is named 'birthright'."""
-        from aipass.spawn.apps.handlers.class_registry import get_template_dir
-
-        path = get_template_dir("birthright")
-        assert path.name == "birthright"
+        path = get_template_dir("aipass_framework")
+        assert path.name == "aipass_framework"
         assert path.exists()
 
     def test_get_template_dir_invalid_raises(self):
@@ -79,91 +74,6 @@ class TestClassRegistry:
             get_template_dir("nonexistent")
 
 
-# =============================================================================
-# PASSPORT COMMAND TESTS
-# =============================================================================
-
-
-class TestPassportCommand:
-    """Tests for passport granting (birthright citizenship)."""
-
-    def test_grant_passport_creates_trinity(self, tmp_path):
-        """Passport grant creates .trinity/ with all identity files."""
-        from aipass.spawn.apps.handlers.passport_ops import grant_passport
-
-        target = tmp_path / "test_citizen"
-        result = grant_passport(str(target), role="tester", purpose="Testing")
-
-        assert result["success"] is True
-        assert result["citizen_class"] == "birthright"
-        assert (target / ".trinity" / "passport.json").exists()
-        assert (target / ".trinity" / "local.json").exists()
-        assert (target / ".trinity" / "observations.json").exists()
-
-    def test_grant_passport_creates_aipass(self, tmp_path):
-        """Passport grant creates .aipass/ with local prompt."""
-        from aipass.spawn.apps.handlers.passport_ops import grant_passport
-
-        target = tmp_path / "test_citizen"
-        result = grant_passport(str(target), role="tester")
-
-        assert result["success"] is True
-        assert (target / ".aipass" / "aipass_local_prompt.md").exists()
-
-    def test_grant_passport_creates_readme(self, tmp_path):
-        """Passport grant creates README.md in target directory."""
-        from aipass.spawn.apps.handlers.passport_ops import grant_passport
-
-        target = tmp_path / "test_citizen"
-        result = grant_passport(str(target))
-
-        assert result["success"] is True
-        assert (target / "README.md").exists()
-
-    def test_grant_passport_no_apps_dir(self, tmp_path):
-        """Birthright should NOT create apps/ scaffold."""
-        from aipass.spawn.apps.handlers.passport_ops import grant_passport
-
-        target = tmp_path / "test_citizen"
-        grant_passport(str(target))
-
-        assert not (target / "apps").exists()
-
-    def test_grant_passport_passport_content(self, tmp_path):
-        """Verify passport has correct citizen_class and role."""
-        from aipass.spawn.apps.handlers.passport_ops import grant_passport
-
-        target = tmp_path / "my_branch"
-        grant_passport(str(target), role="analyst", purpose="Data analysis")
-
-        passport = json.loads((target / ".trinity" / "passport.json").read_text())
-        assert passport["identity"]["citizen_class"] == "birthright"
-        assert passport["identity"]["role"] == "analyst"
-        assert "MY_BRANCH" in passport["document_metadata"]["document_name"]
-
-    def test_grant_passport_already_citizen(self, tmp_path):
-        """Cannot grant passport if .trinity/ already exists."""
-        from aipass.spawn.apps.handlers.passport_ops import grant_passport
-
-        target = tmp_path / "existing"
-        (target / ".trinity").mkdir(parents=True)
-
-        result = grant_passport(str(target))
-        assert result["success"] is False
-        assert "Already a citizen" in result["error"]
-
-    def test_grant_passport_creates_directory(self, tmp_path):
-        """If target directory doesn't exist, create it."""
-        from aipass.spawn.apps.handlers.passport_ops import grant_passport
-
-        target = tmp_path / "brand_new"
-        assert not target.exists()
-
-        result = grant_passport(str(target))
-        assert result["success"] is True
-        assert target.exists()
-
-
 # =============================================================================
 # CLASS-AWARE CREATE TESTS
 # =============================================================================
@@ -172,20 +82,20 @@ class TestPassportCommand:
 class TestClassAwareCreate:
     """Tests for class-aware agent creation."""
 
-    def test_create_builder_explicit(self, tmp_path):
-        """drone @spawn create builder @path creates full scaffold."""
+    def test_create_aipass_framework_explicit(self, tmp_path):
+        """drone @spawn create aipass_framework @path creates full scaffold."""
         from aipass.spawn.apps.modules.core import _spawn_agent
 
-        target = tmp_path / "builder_agent"
-        result = _spawn_agent(str(target), citizen_class="builder")
+        target = tmp_path / "framework_agent"
+        result = _spawn_agent(str(target), citizen_class="aipass_framework")
 
         assert result["success"] is True
         assert (target / "apps").exists()
         assert (target / "apps" / "modules").exists()
         assert (target / "apps" / "handlers").exists()
 
-    def test_create_default_is_builder(self, tmp_path):
-        """drone @spawn create @path defaults to builder."""
+    def test_create_default_is_aipass_framework(self, tmp_path):
+        """drone @spawn create @path defaults to aipass_framework."""
         from aipass.spawn.apps.modules.core import _spawn_agent
 
         target = tmp_path / "default_agent"
@@ -199,17 +109,17 @@ class TestClassAwareCreate:
         from aipass.spawn.apps.modules.core import _spawn_agent
 
         target = tmp_path / "class_test"
-        _spawn_agent(str(target), citizen_class="builder")
+        _spawn_agent(str(target), citizen_class="aipass_framework")
 
         passport = json.loads((target / ".trinity" / "passport.json").read_text())
-        assert passport["identity"]["citizen_class"] == "builder"
+        assert passport["identity"]["citizen_class"] == "aipass_framework"
 
-    def test_create_builder_includes_integrations_scaffold(self, tmp_path):
-        """Builder creation includes apps/integrations/README.md (DPLAN-0133)."""
+    def test_create_aipass_framework_includes_integrations_scaffold(self, tmp_path):
+        """aipass_framework creation includes apps/integrations/README.md (DPLAN-0133)."""
         from aipass.spawn.apps.modules.core import _spawn_agent
 
         target = tmp_path / "integrations_test"
-        result = _spawn_agent(str(target), citizen_class="builder")
+        result = _spawn_agent(str(target), citizen_class="aipass_framework")
 
         assert result["success"] is True
         assert (target / "apps" / "integrations").is_dir()
@@ -224,36 +134,25 @@ class TestClassAwareCreate:
 class TestClassAwareUpdate:
     """Tests for class-aware update behavior."""
 
-    def test_read_citizen_class_builder(self, tmp_path):
-        """Builder branches return 'builder' class."""
+    def test_read_citizen_class_aipass_framework(self, tmp_path):
+        """aipass_framework branches return 'aipass_framework' class."""
         from aipass.spawn.apps.handlers.update_ops import _read_citizen_class
 
         passport_dir = tmp_path / ".trinity"
         passport_dir.mkdir()
-        passport = {"identity": {"citizen_class": "builder", "role": "test"}}
+        passport = {"identity": {"citizen_class": "aipass_framework", "role": "test"}}
         (passport_dir / "passport.json").write_text(json.dumps(passport))
 
-        assert _read_citizen_class(tmp_path) == "builder"
-
-    def test_read_citizen_class_birthright(self, tmp_path):
-        """Birthright branches return 'birthright' class."""
-        from aipass.spawn.apps.handlers.update_ops import _read_citizen_class
-
-        passport_dir = tmp_path / ".trinity"
-        passport_dir.mkdir()
-        passport = {"identity": {"citizen_class": "birthright", "role": "test"}}
-        (passport_dir / "passport.json").write_text(json.dumps(passport))
-
-        assert _read_citizen_class(tmp_path) == "birthright"
+        assert _read_citizen_class(tmp_path) == "aipass_framework"
 
     def test_read_citizen_class_missing_passport(self, tmp_path):
-        """Missing passport defaults to 'builder'."""
+        """Missing passport defaults to 'aipass_framework'."""
         from aipass.spawn.apps.handlers.update_ops import _read_citizen_class
 
-        assert _read_citizen_class(tmp_path) == "builder"
+        assert _read_citizen_class(tmp_path) == "aipass_framework"
 
     def test_read_citizen_class_no_field(self, tmp_path):
-        """Passport without citizen_class field defaults to 'builder'."""
+        """Passport without citizen_class field defaults to 'aipass_framework'."""
         from aipass.spawn.apps.handlers.update_ops import _read_citizen_class
 
         passport_dir = tmp_path / ".trinity"
@@ -261,7 +160,7 @@ class TestClassAwareUpdate:
         passport = {"identity": {"role": "test"}}
         (passport_dir / "passport.json").write_text(json.dumps(passport))
 
-        assert _read_citizen_class(tmp_path) == "builder"
+        assert _read_citizen_class(tmp_path) == "aipass_framework"
 
     def test_update_all_requires_class_via_cli(self):
         """update --all without class should return error code."""
@@ -271,7 +170,7 @@ class TestClassAwareUpdate:
         assert result == 1
 
     def test_update_cli_accepts_class_with_all(self):
-        """update builder --all should parse correctly and call update_all with class filter."""
+        """update aipass_framework --all should parse correctly and call update_all with class filter."""
         from unittest.mock import patch
         from aipass.spawn.apps.modules.update import handle_update
 
@@ -290,10 +189,10 @@ class TestClassAwareUpdate:
             }
         ]
         with patch("aipass.spawn.apps.modules.update.update_all", return_value=mock_results) as mock_ua:
-            result = handle_update(["builder", "--all", "--dry-run"])
+            result = handle_update(["aipass_framework", "--all", "--dry-run"])
 
         assert result == 0
-        mock_ua.assert_called_once_with(dry_run=True, trace=False, citizen_class="builder")
+        mock_ua.assert_called_once_with(dry_run=True, trace=False, citizen_class="aipass_framework")
 
 
 # =============================================================================
@@ -304,58 +203,41 @@ class TestClassAwareUpdate:
 class TestTemplateStructure:
     """Tests verifying template directory structure."""
 
-    def test_builder_template_exists(self):
-        """Builder template directory has .trinity/passport.json and apps/."""
+    def test_aipass_framework_template_exists(self):
+        """aipass_framework template directory has .trinity/passport.json and apps/."""
         from aipass.spawn.apps.handlers.class_registry import get_template_dir
 
-        builder = get_template_dir("builder")
-        assert builder.is_dir()
-        assert (builder / ".trinity" / "passport.json").exists()
-        assert (builder / "apps").is_dir()
+        tpl = get_template_dir("aipass_framework")
+        assert tpl.is_dir()
+        assert (tpl / ".trinity" / "passport.json").exists()
+        assert (tpl / "apps").is_dir()
 
-    def test_birthright_template_exists(self):
-        """Birthright template has .trinity/passport.json but no apps/."""
+    def test_aipass_framework_passport_has_class_placeholder(self):
+        """aipass_framework template passport has citizen_class placeholder for rendering."""
         from aipass.spawn.apps.handlers.class_registry import get_template_dir
 
-        birthright = get_template_dir("birthright")
-        assert birthright.is_dir()
-        assert (birthright / ".trinity" / "passport.json").exists()
-        assert not (birthright / "apps").exists()
-
-    def test_builder_passport_has_class(self):
-        """Builder template passport declares citizen_class='builder'."""
-        from aipass.spawn.apps.handlers.class_registry import get_template_dir
-
-        builder = get_template_dir("builder")
-        passport = json.loads((builder / ".trinity" / "passport.json").read_text())
-        assert passport["identity"]["citizen_class"] == "builder"
-
-    def test_birthright_passport_has_class(self):
-        """Birthright template passport declares citizen_class='birthright'."""
-        from aipass.spawn.apps.handlers.class_registry import get_template_dir
-
-        birthright = get_template_dir("birthright")
-        passport = json.loads((birthright / ".trinity" / "passport.json").read_text())
-        assert passport["identity"]["citizen_class"] == "birthright"
+        tpl = get_template_dir("aipass_framework")
+        passport = json.loads((tpl / ".trinity" / "passport.json").read_text())
+        assert passport["identity"]["citizen_class"] == "{{CITIZEN_CLASS}}"
 
     def test_no_agent_template_dir(self):
         """Old agent.template directory should not exist."""
         spawn_root = Path(__file__).parents[1]
         assert not (spawn_root / "templates" / "agent.template").exists()
 
-    def test_builder_template_has_no_claude_md(self):
-        """Builder template should NOT include CLAUDE.md — project root covers it."""
+    def test_aipass_framework_template_has_no_claude_md(self):
+        """aipass_framework template should NOT include CLAUDE.md — project root covers it."""
         from aipass.spawn.apps.handlers.class_registry import get_template_dir
 
-        builder = get_template_dir("builder")
-        assert not (builder / "CLAUDE.md").exists()
+        tpl = get_template_dir("aipass_framework")
+        assert not (tpl / "CLAUDE.md").exists()
 
-    def test_builder_template_has_local_prompt(self):
-        """Builder template includes non-empty local prompt."""
+    def test_aipass_framework_template_has_local_prompt(self):
+        """aipass_framework template includes non-empty local prompt."""
         from aipass.spawn.apps.handlers.class_registry import get_template_dir
 
-        builder = get_template_dir("builder")
-        prompt = builder / ".aipass" / "aipass_local_prompt.md"
+        tpl = get_template_dir("aipass_framework")
+        prompt = tpl / ".aipass" / "aipass_local_prompt.md"
         assert prompt.exists()
         content = prompt.read_text()
         assert len(content) > 100, "Local prompt should have substantial content"
@@ -445,7 +327,7 @@ class TestMultiAgentCoexistence:
         for name in ["alpha", "beta", "gamma"]:
             passport = json.loads((tmp_path / name / ".trinity" / "passport.json").read_text())
             assert passport["branch_info"]["branch_name"] == name.upper()
-            assert passport["identity"]["citizen_class"] == "builder"
+            assert passport["identity"]["citizen_class"] == "aipass_framework"
 
 
 class TestPassportOwnerField:
@@ -496,42 +378,6 @@ class TestPassportOwnerField:
         assert passports["beta"]["citizenship"]["owner"] is False
         assert passports["gamma"]["citizenship"]["owner"] is False
 
-    def test_birthright_first_agent_is_owner(self, tmp_path):
-        """First birthright agent gets owner: true."""
-        from aipass.spawn.apps.handlers.passport_ops import grant_passport
-
-        reg = tmp_path / "TEST_REGISTRY.json"
-        reg.write_text('{"metadata":{"version":"1.0.0","total_branches":0},"branches":[]}')
-
-        target = tmp_path / "citizen"
-        target.mkdir()
-        with unittest.mock.patch("aipass.spawn.apps.handlers.passport_ops.find_registry", return_value=reg):
-            grant_passport(str(target))
-
-        passport = json.loads((target / ".trinity" / "passport.json").read_text())
-        assert passport["citizenship"]["owner"] is True
-
-    def test_birthright_second_agent_not_owner(self, tmp_path):
-        """Second birthright agent gets owner: false."""
-        from aipass.spawn.apps.handlers.passport_ops import grant_passport
-
-        reg = tmp_path / "TEST_REGISTRY.json"
-        reg.write_text('{"metadata":{"version":"1.0.0","total_branches":0},"branches":[]}')
-
-        first = tmp_path / "first"
-        first.mkdir()
-        second = tmp_path / "second"
-        second.mkdir()
-
-        with unittest.mock.patch("aipass.spawn.apps.handlers.passport_ops.find_registry", return_value=reg):
-            grant_passport(str(first))
-            grant_passport(str(second))
-
-        p1 = json.loads((first / ".trinity" / "passport.json").read_text())
-        p2 = json.loads((second / ".trinity" / "passport.json").read_text())
-        assert p1["citizenship"]["owner"] is True
-        assert p2["citizenship"]["owner"] is False
-
 
 class TestRetroactiveOwner:
     """Tests for retroactive owner assignment on legacy projects."""
diff --git a/src/aipass/spawn/tests/test_cli_routing.py b/src/aipass/spawn/tests/test_cli_routing.py
index 1cfa18ee..c124d945 100644
--- a/src/aipass/spawn/tests/test_cli_routing.py
+++ b/src/aipass/spawn/tests/test_cli_routing.py
@@ -102,11 +102,11 @@ class TestCreateHelp:
         mock_help.assert_called_once()
 
     def test_create_help_with_class(self):
-        """create builder --help shows help."""
+        """create aipass_framework --help shows help."""
         from aipass.spawn.apps.spawn import handle_create
 
         with patch("aipass.spawn.apps.spawn.print_help") as mock_help:
-            result = handle_create(["builder", "--help"])
+            result = handle_create(["aipass_framework", "--help"])
         assert result == 0
         mock_help.assert_called_once()
 
@@ -150,30 +150,6 @@ class TestCreateDryRun:
 class TestTemplateFlag:
     """Tests for --template flag as class selector."""
 
-    def test_template_flag_selects_class(self, tmp_path):
-        """--template birthright creates birthright-class agent."""
-        from aipass.spawn.apps.spawn import handle_create
-
-        target = str(tmp_path / "tmpl_test")
-        with patch("aipass.spawn.apps.spawn.console"), patch("aipass.spawn.apps.spawn.header"):
-            result = handle_create([target, "--template", "birthright"])
-        assert result == 0
-        # Birthright class: has .trinity but no apps/
-        assert (tmp_path / "tmpl_test" / ".trinity").exists()
-        assert not (tmp_path / "tmpl_test" / "apps").exists()
-
-    def test_template_flag_overrides_positional_class(self, tmp_path):
-        """--template overrides positional class arg."""
-        from aipass.spawn.apps.spawn import handle_create
-
-        target = str(tmp_path / "override_test")
-        # Positional says builder, flag says birthright
-        with patch("aipass.spawn.apps.spawn.console"), patch("aipass.spawn.apps.spawn.header"):
-            result = handle_create(["builder", target, "--template", "birthright"])
-        assert result == 0
-        # --template wins: birthright has no apps/
-        assert not (tmp_path / "override_test" / "apps").exists()
-
     def test_template_flag_unknown_treated_as_path(self, tmp_path):
         """--template with unknown value is treated as path (backward compat)."""
         from aipass.spawn.apps.spawn import handle_create
@@ -184,38 +160,6 @@ class TestTemplateFlag:
         assert result == 1
         mock_error.assert_called_once()
 
-    def test_template_flag_dry_run(self, tmp_path):
-        """--template works with --dry-run."""
-        from aipass.spawn.apps.spawn import handle_create
-
-        target = str(tmp_path / "drytest")
-        with patch("aipass.spawn.apps.spawn.console"), patch("aipass.spawn.apps.spawn.header"):
-            result = handle_create([target, "--template", "birthright", "--dry-run"])
-        assert result == 0
-        assert not (tmp_path / "drytest").exists()
-
-
-class TestPassportHelp:
-    """Tests for passport --help interception."""
-
-    def test_passport_help_flag(self):
-        """passport --help shows introspection."""
-        from aipass.spawn.apps.modules.passport import handle_passport
-
-        with patch("aipass.spawn.apps.modules.passport.print_introspection") as mock:
-            result = handle_passport(["--help"])
-        assert result == 0
-        mock.assert_called_once()
-
-    def test_passport_short_help(self):
-        """passport -h shows introspection."""
-        from aipass.spawn.apps.modules.passport import handle_passport
-
-        with patch("aipass.spawn.apps.modules.passport.print_introspection") as mock:
-            result = handle_passport(["-h"])
-        assert result == 0
-        mock.assert_called_once()
-
 
 class TestPrintHelp:
     """Tests for print_help output."""
diff --git a/src/aipass/spawn/tests/test_handlers.py b/src/aipass/spawn/tests/test_handlers.py
index 1224a220..90a78b22 100644
--- a/src/aipass/spawn/tests/test_handlers.py
+++ b/src/aipass/spawn/tests/test_handlers.py
@@ -204,12 +204,12 @@ class TestGetTemplateDir:
     """Tests for get_template_dir()."""
 
     def test_returns_path(self):
-        """Should return a Path object pointing to builder template."""
+        """Should return a Path object pointing to aipass_framework template."""
         from aipass.spawn.apps.handlers.meta_ops import get_template_dir
 
         result = get_template_dir()
         assert isinstance(result, Path)
-        assert result.name == "builder"
+        assert result.name == "aipass_framework"
 
 
 # =============================================================================
diff --git a/src/aipass/spawn/tests/test_lifecycle.py b/src/aipass/spawn/tests/test_lifecycle.py
index 06f3cfdb..cc279377 100644
--- a/src/aipass/spawn/tests/test_lifecycle.py
+++ b/src/aipass/spawn/tests/test_lifecycle.py
@@ -398,7 +398,7 @@ class TestSyncRegistryCwdAware:
         agent.mkdir(parents=True)
         (agent / ".trinity").mkdir()
         (agent / ".trinity" / "passport.json").write_text(
-            json.dumps({"name": "NAVIGATOR", "identity": {"citizen_class": "builder"}})
+            json.dumps({"name": "NAVIGATOR", "identity": {"citizen_class": "aipass_framework"}})
         )
 
         with patch("aipass.spawn.apps.handlers.sync_registry_ops.find_registry", return_value=reg_path):
@@ -422,7 +422,7 @@ class TestSyncRegistryCwdAware:
         agent.mkdir(parents=True)
         (agent / ".trinity").mkdir()
         (agent / ".trinity" / "passport.json").write_text(
-            json.dumps({"name": "DAEMON", "identity": {"citizen_class": "builder"}})
+            json.dumps({"name": "DAEMON", "identity": {"citizen_class": "aipass_framework"}})
         )
 
         with patch("aipass.spawn.apps.handlers.sync_registry_ops.find_registry", return_value=reg_path):
@@ -456,7 +456,7 @@ class TestSyncRegistryCwdAware:
         local_agent.mkdir(parents=True)
         (local_agent / ".trinity").mkdir()
         (local_agent / ".trinity" / "passport.json").write_text(
-            json.dumps({"name": "POLYGLOT", "identity": {"citizen_class": "builder"}})
+            json.dumps({"name": "POLYGLOT", "identity": {"citizen_class": "aipass_framework"}})
         )
 
         reg_path = project / "MYPROJECT_REGISTRY.json"
@@ -514,7 +514,7 @@ class TestSyncRegistryCwdAware:
         local.mkdir(parents=True)
         (local / ".trinity").mkdir()
         (local / ".trinity" / "passport.json").write_text(
-            json.dumps({"name": "MYAGENT", "identity": {"citizen_class": "builder"}})
+            json.dumps({"name": "MYAGENT", "identity": {"citizen_class": "aipass_framework"}})
         )
 
         reg_path = project / "TEST_REGISTRY.json"
@@ -579,7 +579,7 @@ class TestAdoptExisting:
             json.dumps(
                 {
                     "branch_info": {"branch_name": "my_agent"},
-                    "identity": {"citizen_class": "builder", "purpose": "Test agent"},
+                    "identity": {"citizen_class": "aipass_framework", "purpose": "Test agent"},
                 }
             )
         )
@@ -630,7 +630,7 @@ class TestAdoptExisting:
             json.dumps(
                 {
                     "branch_info": {"branch_name": "smart_agent"},
-                    "identity": {"citizen_class": "builder", "purpose": "Process reports daily"},
+                    "identity": {"citizen_class": "aipass_framework", "purpose": "Process reports daily"},
                 }
             )
         )
@@ -663,7 +663,7 @@ class TestAdoptExisting:
             json.dumps(
                 {
                     "branch_info": {"branch_name": "id_agent"},
-                    "identity": {"citizen_class": "builder", "purpose": "Test"},
+                    "identity": {"citizen_class": "aipass_framework", "purpose": "Test"},
                     "citizenship": {"registry_id": "old-uuid-1234"},
                 }
             )
@@ -701,7 +701,7 @@ class TestAdoptExisting:
             json.dumps(
                 {
                     "branch_info": {"branch_name": "matched_agent"},
-                    "identity": {"citizen_class": "builder", "purpose": "Test"},
+                    "identity": {"citizen_class": "aipass_framework", "purpose": "Test"},
                     "citizenship": {"registry_id": "correct-uuid-9999"},
                 }
             )
diff --git a/src/aipass/spawn/tests/test_regenerate_registry_ops.py b/src/aipass/spawn/tests/test_regenerate_registry_ops.py
index 7d3711f0..067d756c 100644
--- a/src/aipass/spawn/tests/test_regenerate_registry_ops.py
+++ b/src/aipass/spawn/tests/test_regenerate_registry_ops.py
@@ -561,16 +561,12 @@ class TestScanTemplateDirectoryOrdering:
 class TestHandleRegenerateRegistry:
     """Tests for handle_regenerate_registry() CLI handler."""
 
-    def test_default_regenerates_builder(self):
+    def test_default_regenerates_aipass_framework(self):
         result = handle_regenerate_registry([])
         assert result == 0
 
-    def test_explicit_builder(self):
-        result = handle_regenerate_registry(["builder"])
-        assert result == 0
-
-    def test_explicit_birthright(self):
-        result = handle_regenerate_registry(["birthright"])
+    def test_explicit_aipass_framework(self):
+        result = handle_regenerate_registry(["aipass_framework"])
         assert result == 0
 
     def test_all_flag(self):
diff --git a/src/aipass/spawn/tests/test_repair.py b/src/aipass/spawn/tests/test_repair.py
index 396bea87..84e3c08d 100644
--- a/src/aipass/spawn/tests/test_repair.py
+++ b/src/aipass/spawn/tests/test_repair.py
@@ -38,7 +38,7 @@ def _make_project(tmp_path, project_name="testproj", branches=None):
                 "path": rel_path,
                 "module": f"{project_name}.{name.lower()}",
             },
-            "identity": {"citizen_class": "builder"},
+            "identity": {"citizen_class": "aipass_framework"},
             "citizenship": {"registered": True},
         }
         (trinity / "passport.json").write_text(json.dumps(passport), encoding="utf-8")
@@ -507,13 +507,13 @@ class TestTemplateFiles:
 
     def test_builder_gitignore_has_venv(self):
         """Builder template .gitignore includes .venv/ entry."""
-        gitignore = Path(__file__).resolve().parent.parent / "templates" / "builder" / ".gitignore"
+        gitignore = Path(__file__).resolve().parent.parent / "templates" / "aipass_framework" / ".gitignore"
         content = gitignore.read_text()
         assert ".venv/" in content
 
     def test_requirements_project_exists(self):
         """Builder template includes requirements.project.txt."""
-        req = Path(__file__).resolve().parent.parent / "templates" / "builder" / "requirements.project.txt"
+        req = Path(__file__).resolve().parent.parent / "templates" / "aipass_framework" / "requirements.project.txt"
         assert req.exists()
         content = req.read_text()
         assert "Project-specific" in content
diff --git a/src/aipass/spawn/tests/test_update.py b/src/aipass/spawn/tests/test_update.py
index ae06a198..d57e89b0 100644
--- a/src/aipass/spawn/tests/test_update.py
+++ b/src/aipass/spawn/tests/test_update.py
@@ -575,6 +575,6 @@ class TestHandleUpdate:
             patch("aipass.spawn.apps.handlers.update_ops.get_template_dir", return_value=template_dir),
             patch("aipass.spawn.apps.handlers.update_ops.find_registry", return_value=mock_registry),
         ):
-            result = handle_update(["builder", "--all"])
+            result = handle_update(["aipass_framework", "--all"])
 
         assert result == 0
diff --git a/src/aipass/trigger/apps/handlers/events/bulletin_created.py b/src/aipass/trigger/apps/handlers/events/bulletin_created.py
deleted file mode 100644
index e700fbb8..00000000
--- a/src/aipass/trigger/apps/handlers/events/bulletin_created.py
+++ /dev/null
@@ -1,246 +0,0 @@
-# =================== AIPass ====================
-# Name: bulletin_created.py
-# Description: Bulletin created event handler for dashboard propagation
-# Version: 1.0.0
-# Created: 2026-01-31
-# Modified: 2026-01-31
-# =============================================
-
-"""
-Bulletin Created Event Handler
-
-Handles bulletin_created events fired when a new bulletin is created.
-Propagates the bulletin to all branch dashboards.
-
-Event data expected:
-    - bulletin_id: ID of the created bulletin
-    - title: Bulletin title
-    - message: Bulletin content
-    - priority: Bulletin priority level
-    - created_by: Who created it
-    - timestamp: When created
-"""
-
-import json
-from datetime import datetime, timezone
-from pathlib import Path
-from typing import Any, Dict, List
-from aipass.trigger.apps.config import TRIGGER_ROOT, atomic_write_json
-from aipass.trigger.apps.handlers.json import json_handler
-
-
-def _find_repo_root() -> Path:
-    """Walk up from this file to find the repo root (contains AIPASS_REGISTRY.json)."""
-    current = Path(__file__).resolve().parent
-    for parent in [current] + list(current.parents):
-        if (parent / "AIPASS_REGISTRY.json").exists():
-            return parent
-    return Path.cwd()
-
-
-_REPO_ROOT = _find_repo_root()
-
-# Paths
-BRANCH_REGISTRY = _REPO_ROOT / "AIPASS_REGISTRY.json"
-BULLETINS_PATH = _REPO_ROOT / "BULLETINS.central.json"
-
-_HANDLER_LOG = TRIGGER_ROOT / "logs" / "bulletin_handler.log"
-
-
-def _log_warning(message: str) -> None:
-    """Log warning to file (event handlers cannot import Prax logger - causes recursion)."""
-    try:
-        _HANDLER_LOG.parent.mkdir(parents=True, exist_ok=True)
-        ts = datetime.now(timezone.utc).strftime("%Y-%m-%d %H:%M:%S")
-        with open(_HANDLER_LOG, "a", encoding="utf-8") as f:
-            f.write(f"{ts} | WARNING | {message}\n")
-    except Exception:
-        pass
-
-
-def _load_branch_registry() -> List[Dict]:
-    """
-    Load branch registry silently.
-
-    Returns:
-        List of branch dicts with name, path, status.
-        Empty list on any error.
-    """
-    try:
-        if not BRANCH_REGISTRY.exists():
-            return []
-        data = json.loads(BRANCH_REGISTRY.read_text(encoding="utf-8"))
-        return data.get("branches", [])
-    except Exception as exc:
-        _log_warning(f"load branch registry failed: {exc}")
-        return []
-
-
-def _load_bulletins() -> List[Dict]:
-    """
-    Load bulletins from central storage.
-
-    Returns:
-        List of bulletin dicts. Empty list on error.
-    """
-    try:
-        if not BULLETINS_PATH.exists():
-            return []
-        data = json.loads(BULLETINS_PATH.read_text())
-        return data.get("bulletins", [])
-    except Exception as exc:
-        _log_warning(f"load bulletins failed: {exc}")
-        return []
-
-
-def _filter_active_bulletins(bulletins: List[Dict]) -> List[Dict]:
-    """
-    Filter bulletins to only active ones.
-
-    Args:
-        bulletins: List of all bulletins
-
-    Returns:
-        List of active bulletins only
-    """
-    return [b for b in bulletins if b.get("active", False)]
-
-
-def _load_dashboard(branch_path: Path) -> Dict:
-    """
-    Load existing dashboard or create minimal structure.
-
-    Args:
-        branch_path: Path to branch root
-
-    Returns:
-        Dashboard data dict (existing or minimal structure)
-    """
-    dashboard_path = branch_path / "DASHBOARD.local.json"
-
-    if dashboard_path.exists():
-        try:
-            data = json.loads(dashboard_path.read_text())
-            if "sections" not in data:
-                data["sections"] = {}
-            if "bulletin_board" not in data["sections"]:
-                data["sections"]["bulletin_board"] = {"managed_by": "aipass", "active_bulletins": [], "pending_ack": []}
-            return data
-        except Exception as exc:
-            _log_warning(f"parse dashboard JSON for {branch_path}: {exc}")
-
-    # Create minimal dashboard structure
-    return {
-        "last_refreshed": datetime.now().strftime("%Y-%m-%d %H:%M:%S"),
-        "sections": {"bulletin_board": {"managed_by": "aipass", "active_bulletins": [], "pending_ack": []}},
-    }
-
-
-def _save_dashboard(branch_path: Path, dashboard: Dict) -> bool:
-    """
-    Save dashboard to branch.
-
-    Args:
-        branch_path: Path to branch root
-        dashboard: Dashboard data to save
-
-    Returns:
-        True if saved, False on error
-    """
-    try:
-        dashboard_path = branch_path / "DASHBOARD.local.json"
-        dashboard["last_refreshed"] = datetime.now().strftime("%Y-%m-%d %H:%M:%S")
-        atomic_write_json(dashboard_path, dashboard)
-        return True
-    except Exception as exc:
-        _log_warning(f"save dashboard to {branch_path}: {exc}")
-        return False
-
-
-def _propagate_bulletins_to_branches() -> None:
-    """
-    Propagate active bulletins to all branch dashboards.
-
-    Loads active bulletins and updates each branch's dashboard
-    with the bulletin_board section.
-
-    Silent failure - catches all exceptions.
-    """
-    try:
-        # Load branch registry
-        branches = _load_branch_registry()
-        if not branches:
-            return
-
-        # Load and filter active bulletins
-        all_bulletins = _load_bulletins()
-        active_bulletins = _filter_active_bulletins(all_bulletins)
-
-        # Update each branch dashboard
-        for branch in branches:
-            branch_path_str = branch.get("path")
-            if not branch_path_str:
-                continue
-
-            branch_path = Path(branch_path_str)
-            if not branch_path.exists():
-                continue
-
-            try:
-                # Load dashboard
-                dashboard = _load_dashboard(branch_path)
-
-                # Update bulletin_board section ONLY
-                if "sections" not in dashboard:
-                    dashboard["sections"] = {}
-
-                dashboard["sections"]["bulletin_board"] = {
-                    "managed_by": "aipass",
-                    "active_bulletins": active_bulletins,
-                    "pending_ack": [],
-                }
-
-                # Save dashboard
-                _save_dashboard(branch_path, dashboard)
-            except Exception as exc:
-                _log_warning(f"propagate to branch {branch_path_str}: {exc}")
-                continue
-
-    except Exception as exc:
-        _log_warning(f"bulletin propagation failed: {exc}")
-
-
-def handle_bulletin_created(
-    _bulletin_id: str | None = None,
-    _title: str | None = None,
-    _message: str | None = None,
-    _priority: str | None = None,
-    _created_by: str | None = None,
-    _timestamp: str | None = None,
-    **_kwargs: Any,
-) -> None:
-    """
-    Handle bulletin_created event - propagate bulletin to all branch dashboards.
-
-    Event parameters are received but not used directly - we reload from
-    central storage to ensure consistency with any concurrent updates.
-
-    Args:
-        _bulletin_id: ID of the created bulletin (unused - reload from storage)
-        _title: Bulletin title (unused - reload from storage)
-        _message: Bulletin content (unused - reload from storage)
-        _priority: Bulletin priority level (unused - reload from storage)
-        _created_by: Who created it (unused - reload from storage)
-        _timestamp: When created (unused - reload from storage)
-        **_kwargs: Additional event data (ignored)
-    """
-    try:
-        # Propagate bulletins to all branches
-        # We reload from central storage to ensure consistency
-        # (the newly created bulletin should already be saved there)
-        _propagate_bulletins_to_branches()
-
-        json_handler.log_operation("bulletin_event", {"success": True})
-
-    except Exception as exc:
-        _log_warning(f"handle_bulletin_created failed: {exc}")
diff --git a/src/aipass/trigger/apps/handlers/events/registry.py b/src/aipass/trigger/apps/handlers/events/registry.py
index d035b06b..81aa4373 100644
--- a/src/aipass/trigger/apps/handlers/events/registry.py
+++ b/src/aipass/trigger/apps/handlers/events/registry.py
@@ -61,7 +61,6 @@ def setup_handlers():
     except ImportError:
         _log_warning("ai_mail not available — error notifications won't send")
     from .warning_logged import handle_warning_logged
-    from .bulletin_created import handle_bulletin_created
     from .memory_template_updated import handle_memory_template_updated
 
     # from .pr_status_sync import handle_pr_created, handle_pr_merged  # TDPLAN-0007: status-sync decommissioned
@@ -74,7 +73,6 @@ def setup_handlers():
     trigger.on("plan_file_moved", handle_plan_file_moved)
     trigger.on("error_detected", handle_error_detected)
     trigger.on("warning_logged", handle_warning_logged)
-    trigger.on("bulletin_created", handle_bulletin_created)
     trigger.on("memory_template_updated", handle_memory_template_updated)
     # trigger.on("pr_created", handle_pr_created)  # TDPLAN-0007: status-sync decommissioned
     # trigger.on("pr_merged", handle_pr_merged)  # TDPLAN-0007: status-sync decommissioned
diff --git a/src/aipass/trigger/tests/test_event_handlers.py b/src/aipass/trigger/tests/test_event_handlers.py
index 40e92bfd..e9f28c01 100644
--- a/src/aipass/trigger/tests/test_event_handlers.py
+++ b/src/aipass/trigger/tests/test_event_handlers.py
@@ -6,7 +6,7 @@
 # Modified: 2026-04-25
 # =============================================
 
-"""Tests for cli, memory_template_updated, warning_logged, and bulletin_created event handlers."""
+"""Tests for cli, memory_template_updated, and warning_logged event handlers."""
 
 import sys
 from pathlib import Path
@@ -41,7 +41,6 @@ def _mock_infrastructure(monkeypatch: pytest.MonkeyPatch, tmp_path: Path) -> Non
         "aipass.trigger.apps.handlers.events.cli",
         "aipass.trigger.apps.handlers.events.memory_template_updated",
         "aipass.trigger.apps.handlers.events.warning_logged",
-        "aipass.trigger.apps.handlers.events.bulletin_created",
     ):
         monkeypatch.delitem(sys.modules, mod_name, raising=False)
 
@@ -67,13 +66,6 @@ def _import_warning_logged():
     return m
 
 
-def _import_bulletin():
-    """Import bulletin_created handler module fresh after mocking."""
-    import aipass.trigger.apps.handlers.events.bulletin_created as m
-
-    return m
-
-
 # ---------------------------------------------------------------------------
 # cli.py -- handle_cli_header_displayed
 # ---------------------------------------------------------------------------
@@ -197,65 +189,3 @@ class TestHandleWarningLogged:
         mod = _import_warning_logged()
         result = mod.handle_warning_logged()
         assert result is None
-
-
-# ---------------------------------------------------------------------------
-# bulletin_created.py -- handle_bulletin_created
-# ---------------------------------------------------------------------------
-
-
-class TestHandleBulletinCreated:
-    """Tests for handle_bulletin_created from bulletin_created.py."""
-
-    def test_does_not_raise_when_files_missing(self) -> None:
-        """Silently handles missing registry and bulletins files."""
-        mod = _import_bulletin()
-        mod.handle_bulletin_created()
-
-    def test_logs_operation_on_success(self) -> None:
-        """Logs bulletin_event after successful propagation."""
-        mod = _import_bulletin()
-        mod._propagate_bulletins_to_branches = MagicMock()
-        from aipass.trigger.apps.handlers.json import json_handler
-
-        json_handler.log_operation.reset_mock()  # type: ignore[union-attr]
-
-        mod.handle_bulletin_created()
-
-        mod._propagate_bulletins_to_branches.assert_called_once()
-        json_handler.log_operation.assert_called_once_with(  # type: ignore[union-attr]
-            "bulletin_event", {"success": True}
-        )
-
-    def test_catches_propagation_exception(self) -> None:
-        """Does not log operation when propagation raises."""
-        mod = _import_bulletin()
-        mod._propagate_bulletins_to_branches = MagicMock(side_effect=RuntimeError("propagation failed"))
-        from aipass.trigger.apps.handlers.json import json_handler
-
-        json_handler.log_operation.reset_mock()  # type: ignore[union-attr]
-
-        mod.handle_bulletin_created()
-
-        json_handler.log_operation.assert_not_called()  # type: ignore[union-attr]
-
-    def test_accepts_all_params(self) -> None:
-        """Accepts all documented event parameters without error."""
-        mod = _import_bulletin()
-        mod._propagate_bulletins_to_branches = MagicMock()
-
-        mod.handle_bulletin_created(
-            _bulletin_id="b1",
-            _title="System update",
-            _message="Scheduled maintenance",
-            _priority="high",
-            _created_by="devpulse",
-            _timestamp="2026-04-25T10:00:00",
-        )
-
-    def test_returns_none(self) -> None:
-        """Handler returns None."""
-        mod = _import_bulletin()
-        mod._propagate_bulletins_to_branches = MagicMock()
-        result = mod.handle_bulletin_created()
-        assert result is None
diff --git a/tests/e2e/test_wiring.py b/tests/e2e/test_wiring.py
index b470656a..f0a0e794 100644
--- a/tests/e2e/test_wiring.py
+++ b/tests/e2e/test_wiring.py
@@ -241,15 +241,20 @@ def hook_workspace(tmp_path_factory: pytest.TempPathFactory) -> Path:
 
 
 def test_t2a_rm_gate_blocks(clean_venv: CleanVenv, hook_workspace: Path) -> None:
-    """rm -rf is blocked via {"decision":"block"} on STDOUT with exit code 0.
+    """rm -rf is blocked via {"decision":"block"} on STDOUT with exit code 2.
 
-    Corrected contract (NOT exit 2): the bridge writes the engine's block JSON
-    to stdout and exits 0.
+    Block contract: every security gate (rm/git/edit/subagent/presence) returns
+    exit_code 2 plus a block-JSON decision on stdout, and the bridge propagates
+    that exit code. The non-zero exit is the cross-event block signal — it is
+    what lets a UserPromptSubmit gate (presence_gate) actually cancel a prompt,
+    not just PreToolUse. Claude Code surfaces the stdout decision reason either
+    way. (Pre-FPLAN-0289 the bridge swallowed the exit code, so this test once
+    pinned exit 0; beb048d corrected the bridge to propagate it.)
     """
     sentinel = f"e2e-block-{uuid.uuid4()}"
     proc = _fire_hook(clean_venv, hook_workspace, "rm -rf /tmp/x", sentinel)
 
-    assert proc.returncode == 0, f"expected exit 0, got {proc.returncode}. stderr:\n{proc.stderr}"
+    assert proc.returncode == 2, f"expected exit 2 (block), got {proc.returncode}. stderr:\n{proc.stderr}"
     decision = json.loads(proc.stdout)
     assert decision.get("decision") == "block", f"stdout was: {proc.stdout!r}"