@staix/agent-hub 0.7.1 → 0.7.3

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog
 
+## Unreleased
+
+## 0.7.3
+
+- A peer that detaches mid-upgrade no longer wedges the recovery: readiness ignores a now-offline peer's stale identity (a reattach with a different thread still blocks), an already-exited terminal is closed as a no-op instead of being waited on, and resume can drive the operation to release once the peer returns (#21).
+- The check.sh leak guard matches tmp test roots only, so a real hub in a directory starting with `ahub-` no longer trips it (#56).
+
+## 0.7.2
+
+- Local inference defaults to a bounded Ollama MLX runtime: `ahub models setup/start/stop` manages it, the configured context is advertised to Pi, and the legacy standalone MLX runtime needs an explicit legacy provider (#51, #52).
+- `ahub init` writes the managed block to `AGENTS.md` only and never creates `CLAUDE.md`: any `CLAUDE.md` stops Claude Code from loading `AGENTS.md`. A block an older `init` left in `CLAUDE.md` is removed, and a `CLAUDE.md` that held nothing else is deleted; a symlinked or hard-linked `CLAUDE.md` is left alone. The one template now tells every agent how it receives and answers hub messages (#54).
+- Stop orphaned hub daemons from leaking and spinning: a rejected peer stop no longer blocks shutdown, a 15 s hard deadline ends a hung stop, the recovery fence waits with backoff and a timeout instead of spinning, and a daemon or manager whose project root or state dir vanished stops itself. A surviving Pi TUI owner is torn down by verified process identity before the hub reports stopped (#56).
+- `ahub doctor --orphans [--kill]` lists registrations whose project root is gone and kills only processes whose argv names that project's hub daemon exactly (#56).
+- A recovery commit no longer blocks when its stop-poll lands in the moment a stopping hub already refuses connections but has not removed its manifest yet: the inspection reports "unavailable" and the poll retries instead of failing the operation (#21).
+- The test suite records and sweeps every hub and manager pid it starts, and `scripts/check.sh` fails the gate on any leaked `ahub-*` test daemon (#56).
+
 ## 0.7.1
 
 - Restore native sessions while unrelated agents remain in the same worktree; the coordinator continues to fence uncertain terminal creations (#48).

package/README.md

@@ -4,7 +4,7 @@ Native multi-agent hub for one developer's machine: Claude Code, Codex, Kimi Cod
 hub-owned local-LLM worker collaborate as peers in independent project directories, with
 task-aware model routing (Switchyard) in front of a self-hosted gateway (OmniRoute).
 
-Status: 0.7.1, control protocol 10. Durable delivery records distinguish queued
+Status: 0.7.3, control protocol 10. Durable delivery records distinguish queued
 work from uncertain execution. The [smoke checklist](docs/smoke.md) records
 verified paths and remaining prerequisites.
 
@@ -28,7 +28,7 @@ cd <your project> && ahub init && ahub up && ahub tail
 Or install the same version from GitHub:
 
 ```bash
-bun add -g github:STAIxBWLB/agent-hub#v0.7.1 && ahub setup
+bun add -g github:STAIxBWLB/agent-hub#v0.7.3 && ahub setup
 ```
 
 The installed commands remain `ahub` and `agent-hub`.
@@ -69,8 +69,8 @@ peer with the hub. The project uses its existing OmniRoute connection for DGX;
 `pi.dgx_coding` and `pi.dgx_fast` select the gateway's configured model IDs.
 
 ```bash
-ahub models setup       # dedicated Python 3.12 environment and pinned Qwen3 8B MLX weights
-ahub models start       # loopback-only Apple Silicon runtime
+ahub models setup       # prepare bounded Qwen3.5 4B MLX in an existing Ollama service
+ahub models start       # verify loopback Ollama/model readiness (no daemon spawn)
 ahub models status
 ahub pi --mode headless --backend auto
 ahub say @pi "Read the project and summarize the next small implementation task"
@@ -92,11 +92,22 @@ Tool-call receipts survive daemon restart; an interrupted operation with an
 unknown outcome must be reconciled before repeating it. Cancelling a Pi turn
 does not automatically hand its task to a cloud peer.
 
-MLX uses a pinned Qwen3 8B 4-bit model, a 16K input budget and one generation
-at a time. `ahub models stop` stops only the runtime whose process identity
-matches its ownership record. Project hubs share the runtime; stopping a hub
-does not stop MLX. The relay can fall back from MLX to DGX before streaming
-starts. Inspect `ahub status` for requested routes and reported backend models.
+The `mlx/fast` alias now defaults to an externally managed Ollama MLX backend.
+Install and start Ollama separately, with `OLLAMA_NO_CLOUD=1`,
+`OLLAMA_NUM_PARALLEL=1`, `OLLAMA_MAX_LOADED_MODELS=1`, and a finite
+`OLLAMA_KEEP_ALIVE` (five minutes is the tested setting). `models setup`
+prepares `agenthub-fast-mlx:4b-8k` from `qwen3.5:4b-mlx`, with an 8K total
+context and a 2K output cap. The relay budgets input separately at 6,000
+estimated tokens and serializes local requests across project hubs.
+
+`models status` distinguishes model availability from memory residency.
+`models stop` refuses to unload an externally managed Ollama model: other
+clients may be using it. Ollama owns idle eviction; stopping a hub never
+kills Ollama. The OpenAI compatibility endpoint does not enforce a request
+`keep_alive` field, so configure the server and verify its expiry readback.
+The relay can fall back to DGX before streaming starts as before. See the
+[Ollama migration procedure](docs/operations.md#ollama-mlx-migration-issue-51)
+for existing Python runtime/configuration cleanup and rollback.
 
 A project has one managed Pi session owner. Mode changes require the agent to
 settle and preserve the session file. Before the first generation, a live source

package/docs/operations.md

@@ -1,6 +1,6 @@
 # Operations guide
 
-This guide describes ahub 0.7.1 and control protocol 10. Live verification
+This guide describes ahub 0.7.3 and control protocol 10. Live verification
 results and remaining prerequisites are recorded separately in [the smoke ledger](smoke.md).
 
 ## Install and start
@@ -144,33 +144,65 @@ peers. A stopped daemon does not delete task records or the durable journal.
 Do not kill a native terminal by PID or start a replacement while ownership is
 uncertain.
 
+Shutdown is bounded: once it begins, a daemon that cannot finish within
+15 seconds exits anyway, and a peer that refuses to stop is logged rather than
+allowed to block state cleanup. A native Pi TUI owner that does not exit
+gracefully is terminated by its verified process identity (never a bare PID),
+so a restarted hub never launches beside a survivor. A hub whose project root
+or state directory was deleted stops itself within about 10 seconds; the
+dashboard manager does the same when its home directory vanishes.
+
+## Orphaned daemons
+
+Daemons from before those guards, or daemons whose project directory was
+deleted while they were stopped mid-shutdown, are found with:
+
+```bash
+ahub doctor --orphans
+```
+
+It lists registrations whose project root is gone, with any live process
+candidates (the registry claim, the state manifest, the legacy pid file).
+To stop them:
+
+```bash
+ahub doctor --orphans --kill
+```
+
+`--kill` sends SIGTERM, then SIGKILL, but only while the process argv names
+that project's hub daemon exactly (the argument after `--project` must equal
+the registered root); a bare, reused, or merely prefix-matching PID is never
+killed.
+Rows without a live process are stale registrations; forget them with
+`ahub projects remove <id>`.
+
 ## Upgrade and crash recovery
 
 For an upgrade from 0.6.4 (protocol 9) or 0.7.0, use the patched coordinator without
 replacing the global CLI prematurely. Run from the project directory:
 
 ```bash
-bunx --package @staix/agent-hub@0.7.1 ahub upgrade --to 0.7.1 --dry-run
-bunx --package @staix/agent-hub@0.7.1 ahub upgrade --to 0.7.1 --yes
+bunx --package @staix/agent-hub@0.7.3 ahub upgrade --to 0.7.3 --dry-run
+bunx --package @staix/agent-hub@0.7.3 ahub upgrade --to 0.7.3 --yes
 ```
 
 The coordinator verifies and retains the exact target package, preserves its
 own source, and promotes the global CLI only after restored projects pass
 readback. Do not use the old protocol-9 coordinator to target protocol 10.
 
-Once the installed CLI is 0.7.1, review the current project or all registered
+Once the installed CLI is 0.7.3, review the current project or all registered
 projects first:
 
 ```bash
 ahub restart --dry-run
-ahub upgrade --to 0.7.1 --dry-run
+ahub upgrade --to 0.7.3 --dry-run
 ```
 
 Apply only after reviewing the plan:
 
 ```bash
 ahub restart --yes
-ahub upgrade --to 0.7.1 --yes
+ahub upgrade --to 0.7.3 --yes
 ahub recovery status <operation-id>
 ahub recovery resume <operation-id>
 ahub recovery abort <operation-id>
@@ -207,7 +239,8 @@ not a latency or reliability benchmark.
 The 0.6.4 production readback retained two envelopes for a disconnected Codex
 peer with identical IDs before and after recovery; general status lists attached
 peers and therefore did not show that backlog. No messages were deleted. The
-0.7.0 queue readback and receipt semantics remain pending live verification.
+0.7.1 attended cutover and production readback verified queue visibility and
+completion receipts; see the final section of the smoke checklist.
 
 Issue [#12](https://github.com/STAIxBWLB/agent-hub/issues/12) remains open for
 off-campus Access credentials and a natural near-limit budget pause. Tests,
@@ -215,3 +248,62 @@ synthetic approvals, and an authenticated internal network do not close those
 prerequisites. Adapter acceptance is not task completion, and package
 installation or a passing test suite is not proof of a successful production
 cutover.
+
+
+## Ollama MLX migration (issue #51)
+
+The routing names `mlx/fast` and `--backend mlx` are retained. The normal
+runtime provider is now Ollama; the standalone Python server is legacy.
+Use an Apple Silicon Ollama build with MLX support and keep it bound to
+loopback. Configure its finite keep-alive and one-model/one-generation
+limits before use. The model is prepared only by explicit `models setup`;
+an incoming generation does not download models or start a service.
+
+Project `.agenthub/config.json` example:
+
+```json
+{
+  "mlx": {
+    "provider": "ollama",
+    "host": "127.0.0.1",
+    "port": 11434,
+    "model": "agenthub-fast-mlx:4b-8k",
+    "sourceModel": "qwen3.5:4b-mlx",
+    "contextWindow": 8192,
+    "maxInputTokens": 6000,
+    "maxTokens": 2048,
+    "maxConcurrency": 1
+  }
+}
+```
+
+1. Record the current project/hub state. Do not restart stopped hubs or
+   replay queued tasks as part of model migration.
+2. If the old Python server is still running, use the old matching CLI's
+   `models stop` before changing configuration, or explicitly select
+   `provider: "legacy"` temporarily. Its PID, start time and command must
+   match the ownership record. Never kill by process name. Preserve model
+   files and the old configuration for rollback.
+3. Apply the Ollama configuration above, removing legacy `modelPath`,
+   `runtimeDir` and Python binary settings. Existing custom legacy paths
+   without an explicit provider fail with a migration error. Old 16K input
+   overrides must also be reduced; the new total context is 8K.
+4. Run `ahub models setup`, `ahub models start`, and `ahub models status`.
+   Setup creates a dedicated derived model; an existing model is inspected
+   rather than silently overwritten. A wrong context recipe must be fixed
+   deliberately under a new model name or after an explicit model change.
+5. Verify a streamed completion and tool call through the authenticated
+   relay. Check Ollama logs for the MLX runner, `/api/ps` for context and
+   finite expiry, then confirm idle eviction. Catalog availability does
+   not mean the model is resident. Unit tests are not this live proof.
+
+Ollama is shared and external. `models stop` refuses in Ollama mode rather
+than interrupting another client. Hub shutdown releases local handles and
+requests, not the server. Normal idle eviction is Ollama's responsibility;
+no AgentHub timer unloads a potentially shared active model.
+
+The relay's input budget is an estimate, not exact model tokenization. Keep
+headroom for templates/tool metadata and choose a larger dedicated recipe
+only after measuring memory. This path does not change local-worker PII
+routing or the DGX backend. Rollback requires explicitly restoring the old
+config with `provider: "legacy"`; Ollama errors never launch Python.

package/docs/quickstart.md

@@ -17,7 +17,7 @@ ahub setup                                # installs the Claude Code channel plu
 Or use the matching GitHub release:
 
 ```bash
-bun add -g github:STAIxBWLB/agent-hub#v0.7.1
+bun add -g github:STAIxBWLB/agent-hub#v0.7.3
 ahub setup
 ```
 
@@ -33,7 +33,7 @@ and upgrade or crash recovery, see the [operations guide](operations.md).
 In your project directory, one terminal each:
 
 ```bash
-ahub init          # .agenthub/config.json, .agenthub/routing.toml, marker blocks in CLAUDE.md and AGENTS.md
+ahub init          # .agenthub/config.json, .agenthub/routing.toml, the marker block in AGENTS.md
 ahub up            # the daemon for this directory (loopback only)
 ahub tail          # keep open: the conversation, state changes, permission requests
 ahub kimi          # Kimi, headless

package/docs/smoke.md

@@ -511,7 +511,7 @@ pause.
   npm integrity against the new coordinator. Protocol 9 to 10 migration reached
   `released`; exact queued envelope IDs, manual pauses and task identity/state
   digest were preserved. The disposable daemon was stopped afterward.
-- Real Kimi 2.0.1 and Pi ran in a disposable project using the 0.7.0 code.
+- Real Kimi and Pi ran in a disposable project using the 0.7.0 code.
   Kimi requested a read-only task-list approval before answering the no-action
   note as FYI; 85.361 seconds includes operator waiting and is not model latency.
   No follow-on recipient delivery occurred.
@@ -543,3 +543,89 @@ reached `completed` with its project `verified`.
 coordinator's pending-create fence and returned terminal/session verification.
 Regression tests include unrelated terminals and delayed close inventory.
 The 0.7.1 attended repeat is recorded separately after application.
+
+
+## 0.7.1 verified production application (2026-09-20)
+
+- Local full gate: 328 pass, 0 fail, 1732 assertions, `check: OK`. Ubuntu and
+  macOS CI passed for the merged patch. npm publication with provenance and
+  GitHub Release completed; the staged package matched registry integrity.
+- The patched coordinator recreated the captured Claude session while the
+  unrelated Codex and Qwen terminals remained open. It did not require manual
+  terminal creation. The native development-channel confirmation still required
+  an attended acknowledgement; resume adopted that same replacement terminal.
+- Recovery completed with the project verified and the live daemon released.
+  Global CLI, daemon and Claude plugin report 0.7.1, control protocol 10.
+  The installed runtime digest matches the verified staged artifact.
+- Claude and Pi session identities match the pre-0.7.0 plan. Kimi reattached
+  with a fresh session by design. Queue/manual-pause/task/budget integrity
+  matched the recovery snapshot; the board still has three approved tasks.
+- The disconnected Codex recipient is visible with the same two queued
+  messages. They were neither dispatched nor discarded during validation.
+- A production Pi read returned an exact random marker through MLX in 6.067
+  seconds. Its journal receipt reached `completed`; its FYI answer triggered
+  zero other-peer turns. The daemon instance and Pi session stayed unchanged,
+  and the temporary file was removed.
+- `ahub doctor` reported all configured checks healthy, including the delivery
+  journal and Claude recovery identity. The hwp-cli hub remained stopped.
+- These are supervised live checks. Native confirmation screens, uncertain
+  delivery review, and the infrastructure prerequisites in #12 remain explicit
+  operator responsibilities; this does not certify unattended operation.
+
+
+## 0.7.1 live status re-measurement (2026-09-21)
+
+Read-only checks against the running production daemon one day after the
+verified application; no daemon, plugin, terminal, or journal mutation.
+
+- `ahub --version` returned 0.7.1 and `ahub status` showed the daemon
+  (pid 48154, control 127.0.0.1:4600) with claude offline (queued 0), kimi
+  idle, pi idle on `mlx/fast`, and the disconnected Codex recipient still
+  carrying two queued messages (`oldest 68615s`). The board still shows
+  three approved tasks.
+- `ahub doctor` reported all 14 configured checks ok, including delivery
+  recovery (`journal healthy; no deliveries need review`), the Claude plugin
+  at 0.7.1, omniroute and switchyard 0.2.0, Pi MLX, and claude-mem 13.25.2.
+- `ahub queue list --json` (protocol 10) read back the two Codex receipts as
+  `queued` at revision 16 with their envelope IDs unchanged from the 0.7.1
+  validation, and the Pi read receipt as `completed` with `important: true`.
+  Neither Codex message was dispatched or discarded.
+- `bun run check` on the current HEAD passed with 328 tests, 0 failures and
+  1734 expect() calls, `check: OK`. The count is two above the 1732 recorded
+  for the 0.7.1 application; no source change is present on HEAD.
+- Kimi reports 2.0.2 in doctor; earlier live legs on this page used 2.0.1.
+
+Issue [#12](https://github.com/STAIxBWLB/agent-hub/issues/12) remains open
+for off-campus Access credentials and a natural near-limit budget pause.
+
+
+## Ollama MLX migration validation (issue #51, 2026-09-22)
+
+The repository gate passed with 343 tests, zero failures, and `check: OK`.
+A source-build smoke on Apple silicon/macOS 27.0 with Ollama 0.34.2 verified:
+
+- Official `qwen3.5:4b-mlx` was prepared as the dedicated model
+  `agenthub-fast-mlx:4b-8k` (digest prefix `975ef418e0df`). Model metadata and
+  resident status both reported context length 8192; output is capped at 2048.
+- `bun scripts/smoke-ollama.ts` sent a completion, streamed a `get_status`
+  tool call, and sent back a synthetic tool result through the authenticated
+  AgentHub relay. The final response was nonempty and the relay reported
+  actual model `agenthub-fast-mlx:4b-8k`. No real tool or DGX fallback ran.
+- Ollama logged `starting mlx runner subprocess`. A short direct completion
+  recorded approximately 3.87 GiB peak; after tool calls the resident model
+  was approximately 4.6 GB by Ollama's accounting. These are short smoke
+  samples, not a long-context peak-memory guarantee or a controlled
+  like-for-like comparison with the former Qwen3-8B Python process.
+- A separate native-API 15-second keep-alive probe expired and `/api/ps`
+  became empty. The OpenAI relay requests independently reported a five-minute
+  expiry from the external service configuration. After the last relay
+  request at 08:19:21 KST, `/api/ps` was empty at 08:24:27 without an explicit
+  unload. This does not mean the relay sets a per-request keep-alive on the
+  OpenAI endpoint.
+- The Homebrew Ollama build logged a missing optional xgrammar library.
+  Ordinary text and tool calls passed; grammar-constrained structured JSON
+  output is not certified by this smoke.
+
+The live harness is opt-in and is not called by the hermetic repository
+check. `AHUB_SMOKE_PROJECT` selects a project configuration without starting
+its daemon or replaying its queue. It deliberately forbids remote inference.

package/docs/specs/2026-09-19-agent-hub-design.md

@@ -274,7 +274,8 @@ peer. Peer ids claimed over the control WS must not be `user` or a hub-managed a
   natively. This replaces Codex `dynamicTools`: no rewriting of proxied TUI traffic.
 - Role contract: Claude in the plugin `instructions`, Codex, Kimi and `local` with the
   standing instruction of their first delivery, all of them in the `AGENT_HUB` marker
-  blocks; `roles` in `.agenthub/config.json` is the source. Codex `developerInstructions`
+  block of `AGENTS.md` (`ahub init` writes no `CLAUDE.md`: one hides `AGENTS.md` from
+  Claude Code); `roles` in `.agenthub/config.json` is the source. Codex `developerInstructions`
   injection is dropped for the same reason as `dynamicTools`.
 - PII (amended in M4): a task matching `signals.pii_patterns` is owned by `local` or by
   nobody; its envelopes are `private` (console tail and `hub.log` print a stub), lists show
@@ -502,10 +503,10 @@ src/memory/         claude-mem worker client, capture for the local worker, reca
 src/cli/            up, claude, codex, kimi, local, say, tail, board, route, budget, status, logs, kill, init
 plugins/agent-hub/  .claude-plugin/plugin.json, .mcp.json, server bundle, hooks (SessionStart health, Stop announce)
 .claude-plugin/marketplace.json
-templates/          CLAUDE.md and AGENTS.md marker blocks, routing.toml default, config.json default
+templates/          AGENTS.md marker block, routing.toml default, config.json default
 scripts/            check.sh, build.mjs, smoke-*.ts
 docs/specs/         this file
-CLAUDE.md, REVIEW.md
+AGENTS.md, REVIEW.md
 ```
 
 ## Acceptance criteria
@@ -673,3 +674,22 @@ ownership and a separate optional dashboard manager. Runtime data and routing
 remain per project. Native memory aliases remain compatible and shared.
 Control protocol 7 adds project/instance identity and console-only dashboard
 snapshot/action forwarding. Existing project-local UI security rules still apply.
+
+
+## Amendment: externally managed Ollama MLX (issue #51)
+
+The `mlx/fast` route retains its name but defaults to `mlx.provider=ollama`.
+The hub connects to a loopback Ollama service and a dedicated bounded model,
+without spawning Python or owning the Ollama PID. Setup explicitly prepares
+Qwen3.5 4B MLX with an 8K context; input and output budgets and shared
+cross-process admission bound each request. Status separates catalog
+availability, residency, expiry and provider readiness. Shared-service
+shutdown/unload is not a hub operation; finite idle eviction is configured
+and verified in Ollama. Legacy Python lifecycle functions remain available
+only through explicit project configuration for migration/rollback.
+
+The authenticated relay, cancellation, tool streaming, Pi backend aliases,
+pre-stream DGX fallback and PII policy remain intact. Ollama model/context
+mismatch fails explicitly, and errors do not resurrect a Python runtime.
+See issue #51 for the acceptance contract and docs/operations.md for the
+non-destructive migration procedure.

package/docs/specs/2026-09-20-durable-delivery-design.md

@@ -1,6 +1,6 @@
 # Durable delivery and supervised operations
 
-Status: Implemented on `feat/durable-delivery-operations`; release application pending
+Status: Implemented in #47; applied and verified with the #48/#49 recovery patch in 0.7.1
 Date: 2026-09-20
 Target: 0.7.0, protocol 10
 
@@ -58,7 +58,7 @@ Update README and quickstart, add an English operations guide covering installat
 - [x] Queue operator controls and status/dashboard visibility.
 - [x] Cross-version recovery compatibility and actionable diagnostics.
 - [x] English guides and recorded live evidence.
-- [ ] Fault tests, independent review, CI, release and verified application.
+- [x] Fault tests, independent review, CI, release and verified application.
 
 ## Integration decision
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@staix/agent-hub",
-  "version": "0.7.1",
+  "version": "0.7.3",
   "description": "Native multi-agent hub: Claude Code, Codex, Kimi Code, Pi and local inference as peers in one project",
   "license": "MIT",
   "type": "module",

package/plugins/agent-hub/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-hub",
-  "version": "0.7.1",
+  "version": "0.7.3",
   "description": "Channel between Claude Code and the agent-hub daemon: peer messages from Codex, Kimi and the local worker arrive as channel events; hub_send replies.",
   "author": {
     "name": "Young Joon Lee",

package/plugins/agent-hub/server.js

@@ -15727,7 +15727,7 @@ class ControlClient {
 // package.json
 var package_default = {
   name: "@staix/agent-hub",
-  version: "0.7.1",
+  version: "0.7.3",
   description: "Native multi-agent hub: Claude Code, Codex, Kimi Code, Pi and local inference as peers in one project",
   license: "MIT",
   type: "module",

package/src/adapters/pi.ts

@@ -17,6 +17,8 @@ export interface PiOptions {
   selectModel?: (envs: Envelope[]) => Promise<string | undefined>; maxSteps?: number;
   onTurnFailure?: (envs: Envelope[], reason: string) => Promise<void>;
   watchdogMs?: number; log?: (line: string) => void;
+  /** How long stop() waits for a graceful TUI owner exit before verified teardown. Tests shrink this. */
+  stopGraceMs?: number;
 }
 export interface PiTuiLaunch { cmd: string; args: string[]; env: NodeJS.ProcessEnv; }
 type RpcMessage = { type?: string; id?: string | number; command?: string; success?: boolean; data?: any; [key: string]: any };
@@ -212,22 +214,25 @@ export class PiPeer extends BasePeer {
     this.stopping = true;
     this.clearOwnerMonitor();
     if (this.opts.mode === "tui") {
+      const grace = this.opts.stopGraceMs ?? 5_000;
       const alive = () => !!this.ownerPid && ownerStillAlive(this.ownerPid, this.ownerSignature);
       if (this.ownerClaimed && alive()) {
         try {
           await Promise.race([this.sendTui({ type: "shutdown" }), (async () => {
-            const deadline = Date.now() + 5_000;
+            const deadline = Date.now() + grace;
             while (alive() && Date.now() < deadline) await Bun.sleep(50);
             if (alive()) throw new Error("Pi TUI shutdown was not acknowledged");
           })()]);
         }
         catch (error) {
-          if (alive()) { this.setState("busy"); this.startOwnerMonitor(); throw error; }
+          // A lost shutdown acknowledgement is not a reason to leave a native owner running
+          // next to its replacement: tear it down by verified identity, or fail stop (#56).
+          if (alive() && !(await this.stopSurvivingOwner())) { this.setState("busy"); this.startOwnerMonitor(); throw error; }
         }
       }
-      const deadline = Date.now() + 5_000;
+      const deadline = Date.now() + grace;
       while (alive() && Date.now() < deadline) await Bun.sleep(50);
-      if (alive()) { this.setState("busy"); this.startOwnerMonitor(); throw new Error("Pi TUI owner process did not exit"); }
+      if (alive() && !(await this.stopSurvivingOwner()) && alive()) { this.setState("busy"); this.startOwnerMonitor(); throw new Error("Pi TUI owner process did not exit"); }
       this.ownerClaimed = false;
       this.resolveTuiExit?.(); this.resolveTuiExit = undefined;
     }
@@ -243,6 +248,26 @@ export class PiPeer extends BasePeer {
     this.server?.stop(true); this.server = undefined; this.setState("offline");
   }
 
+  /**
+   * Terminate a verified TUI owner that outlived its graceful shutdown. Every signal is
+   * guarded by ownerStillAlive, which re-reads the process signature on each poll, so a
+   * reused PID is never signaled. True once the owner is confirmed gone.
+   */
+  private async stopSurvivingOwner(): Promise<boolean> {
+    const pid = this.ownerPid;
+    const signature = this.ownerSignature;
+    const gone = () => !pid || !ownerStillAlive(pid, signature);
+    if (!pid || !signature || gone()) return true;
+    try { process.kill(pid, "SIGTERM"); } catch { return gone(); }
+    let deadline = Date.now() + 2_000;
+    while (!gone() && Date.now() < deadline) await Bun.sleep(50);
+    if (gone()) return true;
+    try { process.kill(pid, "SIGKILL"); } catch { return gone(); }
+    deadline = Date.now() + 2_000;
+    while (!gone() && Date.now() < deadline) await Bun.sleep(50);
+    return gone();
+  }
+
   async deliver(envs: Envelope[], deliveryId?: string): Promise<void> {
     if (this.state !== "idle" || this.stopping) {
       if (deliveryId) this.delivery({ id: deliveryId, state: "failed_safe", reason: `${this.id} is not ready` });

package/src/cli/init.ts

@@ -1,4 +1,4 @@
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { existsSync, lstatSync, mkdirSync, readFileSync, statSync, unlinkSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 
 const TEMPLATES = join(import.meta.dir, "..", "..", "templates");
@@ -14,6 +14,15 @@ export function upsertBlock(existing: string, block: string): string {
   return `${existing.trimEnd()}${existing.trim() ? "\n\n" : ""}${managed}\n`;
 }
 
+/** Drop the managed block and the blank lines around it. Text without a complete block is returned as is. */
+export function removeBlock(existing: string): string {
+  const start = existing.indexOf("<!-- AGENT_HUB:BEGIN");
+  const end = existing.indexOf(END, Math.max(start, 0));
+  if (start === -1 || end <= start) return existing;
+  const rest = [existing.slice(0, start).trimEnd(), existing.slice(end + END.length).trim()].filter(Boolean).join("\n\n");
+  return rest && `${rest}\n`;
+}
+
 /** Returns the paths it changed. */
 export function init(cwd: string): string[] {
   const changed: string[] = [];
@@ -30,10 +39,23 @@ export function init(cwd: string): string[] {
   const routing = join(cwd, ".agenthub", "routing.toml");
   if (!existsSync(routing)) write(routing, readFileSync(join(TEMPLATES, "routing.toml"), "utf8"));
 
-  for (const [file, template] of [["CLAUDE.md", "CLAUDE.block.md"], ["AGENTS.md", "AGENTS.block.md"]] as const) {
-    const path = join(cwd, file);
-    const existing = existsSync(path) ? readFileSync(path, "utf8") : "";
-    write(path, upsertBlock(existing, readFileSync(join(TEMPLATES, template), "utf8")));
+  const agents = join(cwd, "AGENTS.md");
+  write(agents, upsertBlock(existsSync(agents) ? readFileSync(agents, "utf8") : "", readFileSync(join(TEMPLATES, "AGENTS.block.md"), "utf8")));
+
+  // Any CLAUDE.md, even an empty one, stops Claude Code from loading AGENTS.md: take back the block older versions wrote there.
+  // Only a regular file of its own: a symlink may lead out of the project, and a link to AGENTS.md
+  // (hard, or AGENTS.md -> CLAUDE.md) holds the block just written.
+  const claude = join(cwd, "CLAUDE.md");
+  const own = lstatSync(claude, { throwIfNoEntry: false });
+  const target = statSync(agents);
+  const legacy = own?.isFile() && !(own.dev === target.dev && own.ino === target.ino) ? readFileSync(claude, "utf8") : "";
+  const rest = removeBlock(legacy);
+  if (rest !== legacy) {
+    if (rest) write(claude, rest);
+    else {
+      unlinkSync(claude);
+      changed.push(claude);
+    }
   }
 
   const ignore = join(cwd, ".gitignore");