Bump version to 0.13.0

1145 narrowed local-release to install-only (binary + codesign-heal
wrapper) and removed the cargo build + gateway hot-restart steps that
the script used to do. That broke the "rebuild the gateway" muscle
memory: running script/local-release no longer rebuilt or restarted
anything, just re-installed the same binary.

Restore the build + restart logic while keeping 1145's wrapper:

- `cargo build --release --bin huskies` before install
- Snapshot the prior binary to ~/bin/huskies-bin.prev for rollback
- Print PREV → NEW version delta after install
- Detect a running `huskies .*--gateway` process and SSH-safe-restart
  it (kill descendants depth-first, then nohup the wrapper from the
  detached subshell)
- Wait up to 10s for the new gateway PID to appear; on timeout, roll
  back to the previous binary and try to relaunch it
- Refuse to restart when more than one --gateway process matches, so
  we don't kill the wrong tree
- `--skip-check` bypasses script/check for already-verified changes

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

.gitignore

@@ -6,9 +6,6 @@
 # Local environment (secrets)
 .env
 
-# Local-only scripts
-script/local-release
-
 # App specific (root-level; huskies subdirectory patterns live in .huskies/.gitignore)
 store.json
 _merge_parsed.json

.huskies/source-map.json

@@ -696,6 +696,7 @@
   "server/src/agents/pool/start/spawn.rs": [
     "fn maybe_cap_for_merge_fixup",
     "fn maybe_inject_gate_failure",
+    "fn inject_worktree_disallowed_tools",
     "fn run_agent_spawn"
   ],
   "server/src/agents/pool/start/tests_concurrency.rs": [],
@@ -805,6 +806,10 @@
     "fn build_backlog_from_items"
   ],
   "server/src/chat/commands/cleanup_worktrees.rs": [],
+  "server/src/chat/commands/convert.rs": [
+    "fn handle_convert",
+    "fn convert_by_number"
+  ],
   "server/src/chat/commands/cost.rs": [
     "fn handle_cost",
     "fn extract_agent_type"
@@ -978,6 +983,8 @@
   ],
   "server/src/chat/transport/matrix/bot/format.rs": [
     "fn format_startup_announcement",
+    "fn format_gateway_ready_announcement",
+    "fn format_gateway_rollback_announcement",
     "fn markdown_to_html"
   ],
   "server/src/chat/transport/matrix/bot/history.rs": [
@@ -1056,6 +1063,9 @@
     "fn extract_delete_command",
     "fn handle_delete"
   ],
+  "server/src/chat/transport/matrix/health.rs": [
+    "fn run_health_check"
+  ],
   "server/src/chat/transport/matrix/htop.rs": [
     "enum HtopCommand",
     "struct HtopSession",
@@ -1072,11 +1082,14 @@
     "mod commands",
     "mod config",
     "mod delete",
+    "mod health",
     "mod htop",
     "mod new_project",
+    "mod project_rebuild",
     "mod rebuild",
     "mod reset",
     "mod rmtree",
+    "mod sled_upgrade",
     "mod start",
     "mod transport_impl",
     "fn spawn_bot"
@@ -1084,13 +1097,25 @@
   "server/src/chat/transport/matrix/new_project.rs": [
     "struct NewProjectCommand",
     "fn extract_new_project_command",
+    "fn apply_project_config",
     "fn detect_stack",
     "fn image_for_stack",
-    "fn handle_new_project"
+    "fn resolve_git_identity",
+    "fn handle_new_project",
+    "fn dockerfile_for_project",
+    "fn build_project_image",
+    "fn project_docker_run_args",
+    "fn resolve_gateway_url"
+  ],
+  "server/src/chat/transport/matrix/project_rebuild.rs": [
+    "struct ProjectRebuildCommand",
+    "fn extract_project_rebuild_command",
+    "fn handle_project_rebuild"
   ],
   "server/src/chat/transport/matrix/rebuild.rs": [
     "struct RebuildCommand",
     "fn extract_rebuild_command",
+    "fn extract_rebuild_gateway_command",
     "fn handle_rebuild"
   ],
   "server/src/chat/transport/matrix/reset.rs": [
@@ -1103,6 +1128,12 @@
     "fn extract_rmtree_command",
     "fn handle_rmtree"
   ],
+  "server/src/chat/transport/matrix/sled_upgrade.rs": [
+    "enum UpgradeCommand",
+    "fn extract_upgrade_command",
+    "fn handle_upgrade_list_projects",
+    "fn handle_sled_upgrade"
+  ],
   "server/src/chat/transport/matrix/start.rs": [
     "enum StartCommand",
     "fn extract_start_command",
@@ -1626,9 +1657,13 @@
     "fn spawn_event_log_subscriber"
   ],
   "server/src/gateway/mod.rs": [
+    "mod rebuild",
     "fn build_gateway_route",
     "fn run"
   ],
+  "server/src/gateway/rebuild.rs": [
+    "fn rebuild_gateway"
+  ],
   "server/src/gateway/tests.rs": [],
   "server/src/gateway_relay.rs": [
     "fn spawn_relay_task"
@@ -1770,6 +1805,11 @@
     "fn validate_working_dir",
     "fn tool_run_command"
   ],
+  "server/src/http/mcp/shell_tools/file_tools.rs": [
+    "fn validate_worktree_file_path",
+    "fn tool_edit",
+    "fn tool_write"
+  ],
   "server/src/http/mcp/shell_tools/mod.rs": [],
   "server/src/http/mcp/shell_tools/script.rs": [
     "fn tool_run_tests",
@@ -1810,6 +1850,9 @@
   "server/src/http/mcp/story_tools/spike.rs": [
     "fn tool_create_spike"
   ],
+  "server/src/http/mcp/story_tools/story/convert.rs": [
+    "fn tool_convert_item_type"
+  ],
   "server/src/http/mcp/story_tools/story/create.rs": [
     "fn tool_create_story",
     "fn tool_purge_story"
@@ -1884,7 +1927,9 @@
     "fn health_handler",
     "fn build_routes",
     "fn rpc_http_handler",
-    "fn debug_crdt_handler"
+    "fn debug_crdt_handler",
+    "fn upgrade_trigger_handler",
+    "fn serve_binary_handler"
   ],
   "server/src/http/oauth.rs": [
     "fn oauth_authorize",
@@ -2229,11 +2274,15 @@
     "mod log_buffer",
     "mod mesh",
     "mod node_identity",
+    "mod pidfile",
+    "mod pipeline_event_bus",
     "mod pipeline_state",
     "mod process_kill",
     "mod rebuild",
     "mod services",
     "mod sled_uplink",
+    "mod trampoline",
+    "mod upgrade",
     "mod validation"
   ],
   "server/src/mesh.rs": [
@@ -2256,6 +2305,19 @@
     "fn init_identity",
     "fn get_identity"
   ],
+  "server/src/pidfile.rs": [
+    "struct PidfileGuard",
+    "fn acquire_gateway_pidfile",
+    "fn acquire_gateway_pidfile_at"
+  ],
+  "server/src/pipeline_event_bus.rs": [
+    "struct BusEvent",
+    "fn init",
+    "fn broadcast",
+    "fn subscribe",
+    "fn render_event",
+    "fn event_matches_persona"
+  ],
   "server/src/pipeline_state/apply.rs": [
     "enum ApplyError",
     "fn apply_transition",
@@ -2993,6 +3055,7 @@
     "fn subscribe_logs",
     "fn subscribe_watcher",
     "fn subscribe_status",
+    "fn subscribe_persona_pipeline_events",
     "fn subscribe_reconciliation"
   ],
   "server/src/service/ws/message/convert.rs": [
@@ -3065,6 +3128,19 @@
     "fn from_path",
     "fn path"
   ],
+  "server/src/trampoline.rs": [
+    "struct TrampolineJob",
+    "fn write_job_atomic",
+    "fn spawn_detached_trampoline",
+    "fn execute_trampoline_core",
+    "fn run_trampoline"
+  ],
+  "server/src/upgrade.rs": [
+    "fn fetch_and_replace_binary",
+    "fn upgrade_and_reexec",
+    "fn run_cli_upgrade",
+    "fn resolve_target_path"
+  ],
   "server/src/validation/error.rs": [
     "enum ValidationError",
     "fn format_errors_as_json"
@@ -3126,6 +3202,8 @@
     "struct UnblockStoryRequest",
     "fn from_json",
     "struct FreezeStoryRequest",
+    "fn from_json",
+    "struct ConvertItemTypeRequest",
     "fn from_json"
   ],
   "server/src/validation/sanitize.rs": [

.huskies/specs/tech/CHAT_DRIVEN_PROJECT_BOOTSTRAP.md

@@ -113,9 +113,27 @@ Layered:
 
 - **`huskies-project-base`**: debian-slim + git + huskies binary + sshd
   + sudo + a `huskies` user with the SSH pubkey installed.
-- **`huskies-stack-<stack>`**: per-stack additions. E.g. rust gets
-  `rustup` + `rust-analyzer` + `cargo-nextest`; node gets `node@22` +
-  `typescript-language-server`; etc.
+- **`huskies-project-<stack>`**: per-stack additions, pre-built by
+  `script/build-project-images`.  E.g. rust gets `rustup` +
+  `rust-analyzer` + `cargo-nextest`; node gets `node@22` +
+  `typescript-language-server`; etc.  Stack fragments live in
+  `docker/stacks/<stack>/Dockerfile.fragment`.
+- **`huskies-project-local-<name>`** *(optional)*: built on the fly at
+  container launch time when the project contains
+  `.huskies/Dockerfile.fragment`.  This file is appended after the
+  stack overlay (`FROM huskies-project-<stack>`) so agents can extend
+  their own image without editing shared stack files.  Because the
+  fragment lives inside the bind-mounted `/workspace/.huskies/`, changes
+  survive container recreation and are committed alongside the project
+  source.  The `project-rebuild` command picks up the fragment
+  automatically when rebuilding.
+
+  Example `.huskies/Dockerfile.fragment` that adds `jq`:
+
+  ```dockerfile
+  RUN apt-get update && apt-get install -y jq
+  ```
+
 - **Project layer**: the bind-mounted `/workspace` is the project source,
   written by the host's editor, read by the in-container tooling.
 
@@ -215,7 +233,74 @@ The work breaks naturally into:
 - **Phase 4:** git integration — `--git <url>` clones, host SSH key
   mount, push verification.
 - **Phase 5:** per-project resource limits + cleanup chat commands.
+- **Phase 6:** `--adopt <dir>` wraps a container around an existing
+  checkout. No clone or init — bind-mount only.
+- **Phase 7 (story 1137):** First-run init flow — config summary and
+  chat-driven overrides (see below).
 
 Each phase ships independently and is usable on its own. Phase 1 alone
 gives chat-only users a working project; later phases add the editor
 and git polish.
+
+## First-Run Init Flow (Story 1137)
+
+After a successful `new project ... --adopt` (or any new-project
+bootstrap), the bot appends a **Default configuration** block to the
+adoption success reply.  This block lists every scaffolded agent with
+its model, budget cap, and turn limit, and provides ready-to-send
+override commands.
+
+### Example reply tail
+
+```
+**Default configuration** (3 agents):
+- coder-1 (coder): model=`sonnet`, budget=$5.00, max_turns=50
+- qa (qa): model=`sonnet`, budget=$4.00, max_turns=40
+- mergemaster (mergemaster): model=`sonnet`, budget=$5.00, max_turns=30
+
+Override via chat: `huskies config myapp coder.model=opus`
+Project settings:  `huskies config myapp default_qa=human`
+Accept all defaults silently: add `--skip-config` to the bootstrap command.
+```
+
+### Config override command
+
+```
+huskies config <project> <key>=<value>
+```
+
+The gateway resolves the project's `host_path` from `projects.toml`,
+then writes the setting to `.huskies/agents.toml` or
+`.huskies/project.toml` on the host.
+
+**Agent fields** (`<stage_or_name>.<field>=<value>`):
+
+| Key | Target | Supported values |
+|-----|--------|-----------------|
+| `coder.model` | agents.toml, coder stage | `sonnet`, `opus`, any model string |
+| `qa.model` | agents.toml, qa stage | same |
+| `mergemaster.model` | agents.toml, mergemaster stage | same |
+| `coder.max_turns` | agents.toml, coder stage | integer |
+| `coder.max_budget` | agents.toml, coder stage | decimal (USD) |
+
+**Project keys** (bare `<key>=<value>`):
+
+| Key | Notes |
+|-----|-------|
+| `default_qa` | `"server"`, `"agent"`, or `"human"` |
+| `max_retries` | integer |
+| `max_coders` | integer |
+| `base_branch` | branch name string |
+| `timezone` | IANA timezone (e.g. `"Europe/London"`) |
+| `default_coder_model` | model string |
+
+### Skip path
+
+Pass `--skip-config` to suppress the config block entirely:
+
+```
+new project myapp --adopt /path/to/checkout --skip-config
+```
+
+The success reply is identical to pre-1137 output — only the SSH
+command and registration summary, no agent listing.

Cargo.lock

@@ -872,9 +872,9 @@ dependencies = [
 
 [[package]]
 name = "crypto-common"
-version = "0.2.1"
+version = "0.2.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "77727bb15fa921304124b128af125e7e3b968275d1b108b379190264f4423710"
+checksum = "ce6e4c961d6cd6c9a86db418387425e8bdeaf05b3c8bc1411e6dca4c252f1453"
 dependencies = [
  "hybrid-array",
 ]
@@ -1137,7 +1137,7 @@ checksum = "f1dd6dbb5841937940781866fa1281a1ff7bd3bf827091440879f9994983d5c2"
 dependencies = [
  "block-buffer 0.12.0",
  "const-oid 0.10.2",
- "crypto-common 0.2.1",
+ "crypto-common 0.2.2",
  "ctutils",
 ]
 
@@ -1911,7 +1911,7 @@ checksum = "df3b46402a9d5adb4c86a0cf463f42e19994e3ee891101b1841f30a545cb49a9"
 
 [[package]]
 name = "huskies"
-version = "0.12.1"
+version = "0.13.0"
 dependencies = [
  "ammonia",
  "async-stream",
@@ -3107,9 +3107,9 @@ dependencies = [
 
 [[package]]
 name = "num-conv"
-version = "0.2.1"
+version = "0.2.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "c6673768db2d862beb9b39a78fdcb1a69439615d5794a1be50caa9bc92c81967"
+checksum = "521739c6d2bac4aa25192232afe6841231376b2b26d4d9fae5ecf8ca5772e441"
 
 [[package]]
 name = "num-integer"
@@ -5383,9 +5383,9 @@ dependencies = [
 
 [[package]]
 name = "tower-http"
-version = "0.6.10"
+version = "0.6.11"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "68d6fdd9f81c2819c9a8b0e0cd91660e7746a8e6ea2ba7c6b2b057985f6bcb51"
+checksum = "4cfcf7e2740e6fc6d4d688b4ef00650406bb94adf4731e43c096c3a19fe40840"
 dependencies = [
  "async-compression",
  "bitflags 2.11.1",

docker/Dockerfile.base

@@ -27,6 +27,9 @@ RUN apt-get update && apt-get install -y --no-install-recommends \
         procps \
         openssh-server \
         sudo \
+        nodejs \
+        npm \
+    && npm install -g @anthropic-ai/claude-code \
     && rm -rf /var/lib/apt/lists/*
 
 # Copy the huskies binary and entrypoint from the main image.

docker/docker-compose.yml

@@ -29,6 +29,9 @@ services:
       - HUSKIES_PORT=3001
       # Bind to all interfaces so Docker port forwarding works.
       - HUSKIES_HOST=0.0.0.0
+      # Gateway URL so this sled's relay task forwards CRDT events to the gateway.
+      # Uses host.docker.internal so the container can reach the gateway on the host.
+      - HUSKIES_GATEWAY_URL=http://host.docker.internal:3000
       # Optional: Matrix bot credentials (if using Matrix integration)
       - MATRIX_HOMESERVER=${MATRIX_HOMESERVER:-}
       - MATRIX_USER=${MATRIX_USER:-}

docker/entrypoint.sh

@@ -1,6 +1,16 @@
 #!/bin/sh
 set -e
 
+# ── Claude credentials ────────────────────────────────────────────────
+# The `new project` command bind-mounts the host ~/.claude/.credentials.json
+# at /run/claude-credentials-src:ro.  We copy it here so the huskies user
+# owns the file and mode 0600 is enforced regardless of host uid/gid.
+if [ -f /run/claude-credentials-src ]; then
+    mkdir -p /home/huskies/.claude
+    cp /run/claude-credentials-src /home/huskies/.claude/.credentials.json
+    chmod 600 /home/huskies/.claude/.credentials.json
+fi
+
 # ── SSH authorized key ────────────────────────────────────────────────
 # HUSKIES_SSH_PUBKEY is set by `new project` when it generates a keypair.
 # Write it to authorized_keys so the user can connect with the matching

frontend/package-lock.json

@@ -1,12 +1,12 @@
 {
 	"name": "huskies",
-	"version": "0.12.1",
+	"version": "0.13.0",
 	"lockfileVersion": 3,
 	"requires": true,
 	"packages": {
 		"": {
 			"name": "huskies",
-			"version": "0.12.1",
+			"version": "0.13.0",
 			"dependencies": {
 				"@types/react-syntax-highlighter": "^15.5.13",
 				"react": "^19.1.0",
@@ -46,32 +46,22 @@
 			"license": "MIT"
 		},
 		"node_modules/@asamuzakjp/css-color": {
-			"version": "5.0.1",
-			"resolved": "https://registry.npmjs.org/@asamuzakjp/css-color/-/css-color-5.0.1.tgz",
-			"integrity": "sha512-2SZFvqMyvboVV1d15lMf7XiI3m7SDqXUuKaTymJYLN6dSGadqp+fVojqJlVoMlbZnlTmu3S0TLwLTJpvBMO1Aw==",
+			"version": "5.1.11",
+			"resolved": "https://registry.npmjs.org/@asamuzakjp/css-color/-/css-color-5.1.11.tgz",
+			"integrity": "sha512-KVw6qIiCTUQhByfTd78h2yD1/00waTmm9uy/R7Ck/ctUyAPj+AEDLkQIdJW0T8+qGgj3j5bpNKK7Q3G+LedJWg==",
 			"dev": true,
 			"license": "MIT",
 			"dependencies": {
-				"@csstools/css-calc": "^3.1.1",
-				"@csstools/css-color-parser": "^4.0.2",
+				"@asamuzakjp/generational-cache": "^1.0.1",
+				"@csstools/css-calc": "^3.2.0",
+				"@csstools/css-color-parser": "^4.1.0",
 				"@csstools/css-parser-algorithms": "^4.0.0",
-				"@csstools/css-tokenizer": "^4.0.0",
-				"lru-cache": "^11.2.6"
+				"@csstools/css-tokenizer": "^4.0.0"
 			},
 			"engines": {
 				"node": "^20.19.0 || ^22.12.0 || >=24.0.0"
 			}
 		},
-		"node_modules/@asamuzakjp/css-color/node_modules/lru-cache": {
-			"version": "11.2.7",
-			"resolved": "https://registry.npmjs.org/lru-cache/-/lru-cache-11.2.7.tgz",
-			"integrity": "sha512-aY/R+aEsRelme17KGQa/1ZSIpLpNYYrhcrepKTZgE+W3WM16YMCaPwOHLHsmopZHELU0Ojin1lPVxKR0MihncA==",
-			"dev": true,
-			"license": "BlueOak-1.0.0",
-			"engines": {
-				"node": "20 || >=22"
-			}
-		},
 		"node_modules/@asamuzakjp/dom-selector": {
 			"version": "6.8.1",
 			"resolved": "https://registry.npmjs.org/@asamuzakjp/dom-selector/-/dom-selector-6.8.1.tgz",
@@ -87,15 +77,25 @@
 			}
 		},
 		"node_modules/@asamuzakjp/dom-selector/node_modules/lru-cache": {
-			"version": "11.2.7",
-			"resolved": "https://registry.npmjs.org/lru-cache/-/lru-cache-11.2.7.tgz",
-			"integrity": "sha512-aY/R+aEsRelme17KGQa/1ZSIpLpNYYrhcrepKTZgE+W3WM16YMCaPwOHLHsmopZHELU0Ojin1lPVxKR0MihncA==",
+			"version": "11.4.0",
+			"resolved": "https://registry.npmjs.org/lru-cache/-/lru-cache-11.4.0.tgz",
+			"integrity": "sha512-W+R+kFL4HgVxONq2bhXPi3bGpzGe/yEhVOp233qw9wCRtgncJ15P3bC+e4zZMu4Cq7d+WAJjXGW0uUkifhcatA==",
 			"dev": true,
 			"license": "BlueOak-1.0.0",
 			"engines": {
 				"node": "20 || >=22"
 			}
 		},
+		"node_modules/@asamuzakjp/generational-cache": {
+			"version": "1.0.1",
+			"resolved": "https://registry.npmjs.org/@asamuzakjp/generational-cache/-/generational-cache-1.0.1.tgz",
+			"integrity": "sha512-wajfB8KqzMCN2KGNFdLkReeHncd0AslUSrvHVvvYWuU8ghncRJoA50kT3zP9MVL0+9g4/67H+cdvBskj9THPzg==",
+			"dev": true,
+			"license": "MIT",
+			"engines": {
+				"node": "^20.19.0 || ^22.12.0 || >=24.0.0"
+			}
+		},
 		"node_modules/@asamuzakjp/nwsapi": {
 			"version": "2.3.9",
 			"resolved": "https://registry.npmjs.org/@asamuzakjp/nwsapi/-/nwsapi-2.3.9.tgz",
@@ -119,9 +119,9 @@
 			}
 		},
 		"node_modules/@babel/compat-data": {
-			"version": "7.29.0",
-			"resolved": "https://registry.npmjs.org/@babel/compat-data/-/compat-data-7.29.0.tgz",
-			"integrity": "sha512-T1NCJqT/j9+cn8fvkt7jtwbLBfLC/1y1c7NtCeXFRgzGTsafi68MRv8yzkYSapBnFA6L3U2VSc02ciDzoAJhJg==",
+			"version": "7.29.3",
+			"resolved": "https://registry.npmjs.org/@babel/compat-data/-/compat-data-7.29.3.tgz",
+			"integrity": "sha512-LIVqM46zQWZhj17qA8wb4nW/ixr2y1Nw+r1etiAWgRM6U1IqP+LNhL1yg440jYZR72jCWcWbLWzIosH+uP1fqg==",
 			"dev": true,
 			"license": "MIT",
 			"engines": {
@@ -405,9 +405,9 @@
 			}
 		},
 		"node_modules/@biomejs/biome": {
-			"version": "2.4.9",
-			"resolved": "https://registry.npmjs.org/@biomejs/biome/-/biome-2.4.9.tgz",
-			"integrity": "sha512-wvZW92FrwitTcacvCBT8xdAbfbxWfDLwjYMmU3djjqQTh7Ni4ZdiWIT/x5VcZ+RQuxiKzIOzi5D+dcyJDFZMsA==",
+			"version": "2.4.15",
+			"resolved": "https://registry.npmjs.org/@biomejs/biome/-/biome-2.4.15.tgz",
+			"integrity": "sha512-j5VH3a/h/HXTKBM50MDMxRCzkeLv9S2XJcW2WgnZT1+xyisi+0bISrXR82gCX+8S9lvK0skEvHJRN+3Ktr2hlw==",
 			"dev": true,
 			"license": "MIT OR Apache-2.0",
 			"bin": {
@@ -421,20 +421,20 @@
 				"url": "https://opencollective.com/biome"
 			},
 			"optionalDependencies": {
-				"@biomejs/cli-darwin-arm64": "2.4.9",
-				"@biomejs/cli-darwin-x64": "2.4.9",
-				"@biomejs/cli-linux-arm64": "2.4.9",
-				"@biomejs/cli-linux-arm64-musl": "2.4.9",
-				"@biomejs/cli-linux-x64": "2.4.9",
-				"@biomejs/cli-linux-x64-musl": "2.4.9",
-				"@biomejs/cli-win32-arm64": "2.4.9",
-				"@biomejs/cli-win32-x64": "2.4.9"
+				"@biomejs/cli-darwin-arm64": "2.4.15",
+				"@biomejs/cli-darwin-x64": "2.4.15",
+				"@biomejs/cli-linux-arm64": "2.4.15",
+				"@biomejs/cli-linux-arm64-musl": "2.4.15",
+				"@biomejs/cli-linux-x64": "2.4.15",
+				"@biomejs/cli-linux-x64-musl": "2.4.15",
+				"@biomejs/cli-win32-arm64": "2.4.15",
+				"@biomejs/cli-win32-x64": "2.4.15"
 			}
 		},
 		"node_modules/@biomejs/cli-darwin-arm64": {
-			"version": "2.4.9",
-			"resolved": "https://registry.npmjs.org/@biomejs/cli-darwin-arm64/-/cli-darwin-arm64-2.4.9.tgz",
-			"integrity": "sha512-d5G8Gf2RpH5pYwiHLPA+UpG3G9TLQu4WM+VK6sfL7K68AmhcEQ9r+nkj/DvR/GYhYox6twsHUtmWWWIKfcfQQA==",
+			"version": "2.4.15",
+			"resolved": "https://registry.npmjs.org/@biomejs/cli-darwin-arm64/-/cli-darwin-arm64-2.4.15.tgz",
+			"integrity": "sha512-rF3PPqLq1yoST79zaQbDjVJwsuIeci/O+9bgNmC5QpgOqz6aqYuzA4abyAGx+mgyiDXn4A049xAN8gijbuR1Qg==",
 			"cpu": [
 				"arm64"
 			],
@@ -449,9 +449,9 @@
 			}
 		},
 		"node_modules/@biomejs/cli-darwin-x64": {
-			"version": "2.4.9",
-			"resolved": "https://registry.npmjs.org/@biomejs/cli-darwin-x64/-/cli-darwin-x64-2.4.9.tgz",
-			"integrity": "sha512-LNCLNgqDMG7BLdc3a8aY/dwKPK7+R8/JXJoXjCvZh2gx8KseqBdFDKbhrr7HCWF8SzNhbTaALhTBoh/I6rf9lA==",
+			"version": "2.4.15",
+			"resolved": "https://registry.npmjs.org/@biomejs/cli-darwin-x64/-/cli-darwin-x64-2.4.15.tgz",
+			"integrity": "sha512-/5KHXYMfSJs1fNXiX30xFtI8JcCFV6zaVVLxOa0M2sfqBKHkpQhRTv94yxQWxeTY2lzo2OuTlNvPC+hDQt2wcQ==",
 			"cpu": [
 				"x64"
 			],
@@ -466,9 +466,9 @@
 			}
 		},
 		"node_modules/@biomejs/cli-linux-arm64": {
-			"version": "2.4.9",
-			"resolved": "https://registry.npmjs.org/@biomejs/cli-linux-arm64/-/cli-linux-arm64-2.4.9.tgz",
-			"integrity": "sha512-4adnkAUi6K4C/emPRgYznMOcLlUqZdXWM6aIui4VP4LraE764g6Q4YguygnAUoxKjKIXIWPteKMgRbN0wsgwcg==",
+			"version": "2.4.15",
+			"resolved": "https://registry.npmjs.org/@biomejs/cli-linux-arm64/-/cli-linux-arm64-2.4.15.tgz",
+			"integrity": "sha512-owaAMZD/T4LrD0ELNCk0Km3qrRHuM0X6EAyVE1FSqGY0rbLoiDLrO4Us2tllm6cAeB2Ioa9C2C08NZPdr8+0Ug==",
 			"cpu": [
 				"arm64"
 			],
@@ -483,9 +483,9 @@
 			}
 		},
 		"node_modules/@biomejs/cli-linux-arm64-musl": {
-			"version": "2.4.9",
-			"resolved": "https://registry.npmjs.org/@biomejs/cli-linux-arm64-musl/-/cli-linux-arm64-musl-2.4.9.tgz",
-			"integrity": "sha512-8RCww5xnPn2wpK4L/QDGDOW0dq80uVWfppPxHIUg6mOs9B6gRmqPp32h1Ls3T8GnW8Wo5A8u7vpTwz4fExN+sw==",
+			"version": "2.4.15",
+			"resolved": "https://registry.npmjs.org/@biomejs/cli-linux-arm64-musl/-/cli-linux-arm64-musl-2.4.15.tgz",
+			"integrity": "sha512-ZPcxznxm0pogHBLZhYntyR3sR+MrZjqJIKEr7ZqVen0Rl+P/4upVmfYXjftizi9RoqZntg33fv/1fbdhbYXpEQ==",
 			"cpu": [
 				"arm64"
 			],
@@ -500,9 +500,9 @@
 			}
 		},
 		"node_modules/@biomejs/cli-linux-x64": {
-			"version": "2.4.9",
-			"resolved": "https://registry.npmjs.org/@biomejs/cli-linux-x64/-/cli-linux-x64-2.4.9.tgz",
-			"integrity": "sha512-L10na7POF0Ks/cgLFNF1ZvIe+X4onLkTi5oP9hY+Rh60Q+7fWzKDDCeGyiHUFf1nGIa9dQOOUPGe2MyYg8nMSQ==",
+			"version": "2.4.15",
+			"resolved": "https://registry.npmjs.org/@biomejs/cli-linux-x64/-/cli-linux-x64-2.4.15.tgz",
+			"integrity": "sha512-0jj7THz12GbUOLmMibktK6DZjqz2zV64KFxyBtcFTKPiiOIY0a7vns1elpO1dERvxpsZ5ik0oFfz0oGwFde1+g==",
 			"cpu": [
 				"x64"
 			],
@@ -517,9 +517,9 @@
 			}
 		},
 		"node_modules/@biomejs/cli-linux-x64-musl": {
-			"version": "2.4.9",
-			"resolved": "https://registry.npmjs.org/@biomejs/cli-linux-x64-musl/-/cli-linux-x64-musl-2.4.9.tgz",
-			"integrity": "sha512-5TD+WS9v5vzXKzjetF0hgoaNFHMcpQeBUwKKVi3JbG1e9UCrFuUK3Gt185fyTzvRdwYkJJEMqglRPjmesmVv4A==",
+			"version": "2.4.15",
+			"resolved": "https://registry.npmjs.org/@biomejs/cli-linux-x64-musl/-/cli-linux-x64-musl-2.4.15.tgz",
+			"integrity": "sha512-CNq/9W38SYSH023lfcQ4KKU8K0YX8T//FZUhcgtMMRABDojx5XsMV7jlweAvGSl389wJQB29Qo6Zb/a+jdvt+w==",
 			"cpu": [
 				"x64"
 			],
@@ -534,9 +534,9 @@
 			}
 		},
 		"node_modules/@biomejs/cli-win32-arm64": {
-			"version": "2.4.9",
-			"resolved": "https://registry.npmjs.org/@biomejs/cli-win32-arm64/-/cli-win32-arm64-2.4.9.tgz",
-			"integrity": "sha512-aDZr0RBC3sMGJOU10BvG7eZIlWLK/i51HRIfScE2lVhfts2dQTreowLiJJd+UYg/tHKxS470IbzpuKmd0MiD6g==",
+			"version": "2.4.15",
+			"resolved": "https://registry.npmjs.org/@biomejs/cli-win32-arm64/-/cli-win32-arm64-2.4.15.tgz",
+			"integrity": "sha512-ouhkYdlhp/1GghEJPdWwD/Vi3gQ1nFxuSpMolWsbq3Lsq3QUR4jl6UdhhscdCugKU5vOEuMiJhvKj66O0OCq+w==",
 			"cpu": [
 				"arm64"
 			],
@@ -551,9 +551,9 @@
 			}
 		},
 		"node_modules/@biomejs/cli-win32-x64": {
-			"version": "2.4.9",
-			"resolved": "https://registry.npmjs.org/@biomejs/cli-win32-x64/-/cli-win32-x64-2.4.9.tgz",
-			"integrity": "sha512-NS4g/2G9SoQ4ktKtz31pvyc/rmgzlcIDCGU/zWbmHJAqx6gcRj2gj5Q/guXhoWTzCUaQZDIqiCQXHS7BcGYc0w==",
+			"version": "2.4.15",
+			"resolved": "https://registry.npmjs.org/@biomejs/cli-win32-x64/-/cli-win32-x64-2.4.15.tgz",
+			"integrity": "sha512-zBrGq5mx5wwpnow4+2BxUvleDM+GNd4sLbPaMapsSLQLD0NGRCquqPBTgN+7XkUteHvj7M+BstuI8tmnV7+HgQ==",
 			"cpu": [
 				"x64"
 			],
@@ -601,9 +601,9 @@
 			}
 		},
 		"node_modules/@csstools/css-calc": {
-			"version": "3.1.1",
-			"resolved": "https://registry.npmjs.org/@csstools/css-calc/-/css-calc-3.1.1.tgz",
-			"integrity": "sha512-HJ26Z/vmsZQqs/o3a6bgKslXGFAungXGbinULZO3eMsOyNJHeBBZfup5FiZInOghgoM4Hwnmw+OgbJCNg1wwUQ==",
+			"version": "3.2.1",
+			"resolved": "https://registry.npmjs.org/@csstools/css-calc/-/css-calc-3.2.1.tgz",
+			"integrity": "sha512-DtdHlgXh5ZkA43cwBcAm+huzgJiwx3ZTWVjBs94kwz2xKqSimDA3lBgCjphYgwgVUMWatSM0pDd8TILB1yrVVg==",
 			"dev": true,
 			"funding": [
 				{
@@ -625,9 +625,9 @@
 			}
 		},
 		"node_modules/@csstools/css-color-parser": {
-			"version": "4.0.2",
-			"resolved": "https://registry.npmjs.org/@csstools/css-color-parser/-/css-color-parser-4.0.2.tgz",
-			"integrity": "sha512-0GEfbBLmTFf0dJlpsNU7zwxRIH0/BGEMuXLTCvFYxuL1tNhqzTbtnFICyJLTNK4a+RechKP75e7w42ClXSnJQw==",
+			"version": "4.1.1",
+			"resolved": "https://registry.npmjs.org/@csstools/css-color-parser/-/css-color-parser-4.1.1.tgz",
+			"integrity": "sha512-eZ5XOtyhK+mggRafYUWzA0tvaYOFgdY8AkgQiCJF9qNAePnUo/zmsqqYubBBb3sQ8uNUaSKTY9s9klfRaAXL0g==",
 			"dev": true,
 			"funding": [
 				{
@@ -642,7 +642,7 @@
 			"license": "MIT",
 			"dependencies": {
 				"@csstools/color-helpers": "^6.0.2",
-				"@csstools/css-calc": "^3.1.1"
+				"@csstools/css-calc": "^3.2.1"
 			},
 			"engines": {
 				"node": ">=20.19.0"
@@ -676,9 +676,9 @@
 			}
 		},
 		"node_modules/@csstools/css-syntax-patches-for-csstree": {
-			"version": "1.1.1",
-			"resolved": "https://registry.npmjs.org/@csstools/css-syntax-patches-for-csstree/-/css-syntax-patches-for-csstree-1.1.1.tgz",
-			"integrity": "sha512-BvqN0AMWNAnLk9G8jnUT77D+mUbY/H2b3uDTvg2isJkHaOufUE2R3AOwxWo7VBQKT1lOdwdvorddo2B/lk64+w==",
+			"version": "1.1.4",
+			"resolved": "https://registry.npmjs.org/@csstools/css-syntax-patches-for-csstree/-/css-syntax-patches-for-csstree-1.1.4.tgz",
+			"integrity": "sha512-wgsqt92b7C7tQhIdPNxj0n9zuUbQlvAuI1exyzeNrOKOi62SD7ren8zqszmpVREjAOqg8cD2FqYhQfAuKjk4sw==",
 			"dev": true,
 			"funding": [
 				{
@@ -852,13 +852,13 @@
 			}
 		},
 		"node_modules/@playwright/test": {
-			"version": "1.58.2",
-			"resolved": "https://registry.npmjs.org/@playwright/test/-/test-1.58.2.tgz",
-			"integrity": "sha512-akea+6bHYBBfA9uQqSYmlJXn61cTa+jbO87xVLCWbTqbWadRVmhxlXATaOjOgcBaWU4ePo0wB41KMFv3o35IXA==",
+			"version": "1.60.0",
+			"resolved": "https://registry.npmjs.org/@playwright/test/-/test-1.60.0.tgz",
+			"integrity": "sha512-O71yZIbAh/PxDMNGns37GHBIfrVkEVyn+AXyIa5dOTfb4/xNvRWV+Vv/NMbNCtODB/pO7vLlF2OTmMVLhmr7Ag==",
 			"dev": true,
 			"license": "Apache-2.0",
 			"dependencies": {
-				"playwright": "1.58.2"
+				"playwright": "1.60.0"
 			},
 			"bin": {
 				"playwright": "cli.js"
@@ -1320,9 +1320,9 @@
 			"license": "MIT"
 		},
 		"node_modules/@types/estree": {
-			"version": "1.0.8",
-			"resolved": "https://registry.npmjs.org/@types/estree/-/estree-1.0.8.tgz",
-			"integrity": "sha512-dWHzHa2WqEXI/O1E9OjrocMTKJl2mSrEolh1Iomrv6U+JuNwaHXsXx9bLu5gG7BUWFIN0skIQJQ/L1rIex4X6w==",
+			"version": "1.0.9",
+			"resolved": "https://registry.npmjs.org/@types/estree/-/estree-1.0.9.tgz",
+			"integrity": "sha512-GhdPgy1el4/ImP05X05Uw4cw2/M93BCUmnEvWZNStlCzEKME4Fkk+YpoA5OiHNQmoS7Cafb8Xa3Pya8m1Qrzeg==",
 			"license": "MIT"
 		},
 		"node_modules/@types/estree-jsx": {
@@ -1359,13 +1359,13 @@
 			"license": "MIT"
 		},
 		"node_modules/@types/node": {
-			"version": "25.5.0",
-			"resolved": "https://registry.npmjs.org/@types/node/-/node-25.5.0.tgz",
-			"integrity": "sha512-jp2P3tQMSxWugkCUKLRPVUpGaL5MVFwF8RDuSRztfwgN1wmqJeMSbKlnEtQqU8UrhTmzEmZdu2I6v2dpp7XIxw==",
+			"version": "25.9.1",
+			"resolved": "https://registry.npmjs.org/@types/node/-/node-25.9.1.tgz",
+			"integrity": "sha512-xfrlY7UD5rMJk3ZVJP8BNzS28J36YJg+xp+LPXV1TdWxr8uMH5A860QNxYDGQe/ylDSgjxE52Q9VnO7p75tJxg==",
 			"dev": true,
 			"license": "MIT",
 			"dependencies": {
-				"undici-types": "~7.18.0"
+				"undici-types": ">=7.24.0 <7.24.7"
 			}
 		},
 		"node_modules/@types/prismjs": {
@@ -1375,9 +1375,9 @@
 			"license": "MIT"
 		},
 		"node_modules/@types/react": {
-			"version": "19.2.14",
-			"resolved": "https://registry.npmjs.org/@types/react/-/react-19.2.14.tgz",
-			"integrity": "sha512-ilcTH/UniCkMdtexkoCN0bI7pMcJDvmQFPvuPvmEaYA/NSfFTAgdUSLAoVjaRJm7+6PvcM+q1zYOwS4wTYMF9w==",
+			"version": "19.2.15",
+			"resolved": "https://registry.npmjs.org/@types/react/-/react-19.2.15.tgz",
+			"integrity": "sha512-eRwcGNHve+E8qtEQSSRl6urh+rFop4v8gm6O8rGv25CodbvFdLjA1vVQ1KkiFE0w0UPOnb8tDiFKL5lp0rtY5Q==",
 			"license": "MIT",
 			"dependencies": {
 				"csstype": "^3.2.2"
@@ -1409,9 +1409,9 @@
 			"license": "MIT"
 		},
 		"node_modules/@ungap/structured-clone": {
-			"version": "1.3.0",
-			"resolved": "https://registry.npmjs.org/@ungap/structured-clone/-/structured-clone-1.3.0.tgz",
-			"integrity": "sha512-WmoN8qaIAo7WTYWbAZuG8PYEhn5fkz7dZrqTBZ7dtt//lL2Gwms1IcnQ5yHqjDfX8Ft5j4YzDM23f87zBfDe9g==",
+			"version": "1.3.1",
+			"resolved": "https://registry.npmjs.org/@ungap/structured-clone/-/structured-clone-1.3.1.tgz",
+			"integrity": "sha512-mUFwbeTqrVgDQxFveS+df2yfap6iuP20NAKAsBt5jDEoOTDew+zwLAOilHCeQJOVSvmgCX4ogqIrA0mnyr08yQ==",
 			"license": "ISC"
 		},
 		"node_modules/@vitejs/plugin-react": {
@@ -1664,9 +1664,9 @@
 			}
 		},
 		"node_modules/baseline-browser-mapping": {
-			"version": "2.10.10",
-			"resolved": "https://registry.npmjs.org/baseline-browser-mapping/-/baseline-browser-mapping-2.10.10.tgz",
-			"integrity": "sha512-sUoJ3IMxx4AyRqO4MLeHlnGDkyXRoUG0/AI9fjK+vS72ekpV0yWVY7O0BVjmBcRtkNcsAO2QDZ4tdKKGoI6YaQ==",
+			"version": "2.10.31",
+			"resolved": "https://registry.npmjs.org/baseline-browser-mapping/-/baseline-browser-mapping-2.10.31.tgz",
+			"integrity": "sha512-MujYO3eP72uvmSE0i4wltsodRfIpZATP3jvzRNRGGxgzId7aVocVJJV3nf01qnzzKFGxQVC9bpWxl5cjxTr/7Q==",
 			"dev": true,
 			"license": "Apache-2.0",
 			"bin": {
@@ -1687,9 +1687,9 @@
 			}
 		},
 		"node_modules/browserslist": {
-			"version": "4.28.1",
-			"resolved": "https://registry.npmjs.org/browserslist/-/browserslist-4.28.1.tgz",
-			"integrity": "sha512-ZC5Bd0LgJXgwGqUknZY/vkUQ04r8NXnJZ3yYi4vDmSiZmC/pdSN0NbNRPxZpbtO4uAfDUAFffO8IZoM3Gj8IkA==",
+			"version": "4.28.2",
+			"resolved": "https://registry.npmjs.org/browserslist/-/browserslist-4.28.2.tgz",
+			"integrity": "sha512-48xSriZYYg+8qXna9kwqjIVzuQxi+KYWp2+5nCYnYKPTr0LvD89Jqk2Or5ogxz0NUMfIjhh2lIUX/LyX9B4oIg==",
 			"dev": true,
 			"funding": [
 				{
@@ -1707,11 +1707,11 @@
 			],
 			"license": "MIT",
 			"dependencies": {
-				"baseline-browser-mapping": "^2.9.0",
-				"caniuse-lite": "^1.0.30001759",
-				"electron-to-chromium": "^1.5.263",
-				"node-releases": "^2.0.27",
-				"update-browserslist-db": "^1.2.0"
+				"baseline-browser-mapping": "^2.10.12",
+				"caniuse-lite": "^1.0.30001782",
+				"electron-to-chromium": "^1.5.328",
+				"node-releases": "^2.0.36",
+				"update-browserslist-db": "^1.2.3"
 			},
 			"bin": {
 				"browserslist": "cli.js"
@@ -1721,9 +1721,9 @@
 			}
 		},
 		"node_modules/caniuse-lite": {
-			"version": "1.0.30001781",
-			"resolved": "https://registry.npmjs.org/caniuse-lite/-/caniuse-lite-1.0.30001781.tgz",
-			"integrity": "sha512-RdwNCyMsNBftLjW6w01z8bKEvT6e/5tpPVEgtn22TiLGlstHOVecsX2KHFkD5e/vRnIE4EGzpuIODb3mtswtkw==",
+			"version": "1.0.30001793",
+			"resolved": "https://registry.npmjs.org/caniuse-lite/-/caniuse-lite-1.0.30001793.tgz",
+			"integrity": "sha512-iwSsYWaCOoh26cV8NwNRViHlrfUvYsHDfRVcbtmw0Kg6PJIZZXwMkj1442FYLBGkeUf1juAsU3DTfxW579mrPA==",
 			"dev": true,
 			"funding": [
 				{
@@ -1856,9 +1856,9 @@
 			}
 		},
 		"node_modules/cssstyle/node_modules/lru-cache": {
-			"version": "11.2.7",
-			"resolved": "https://registry.npmjs.org/lru-cache/-/lru-cache-11.2.7.tgz",
-			"integrity": "sha512-aY/R+aEsRelme17KGQa/1ZSIpLpNYYrhcrepKTZgE+W3WM16YMCaPwOHLHsmopZHELU0Ojin1lPVxKR0MihncA==",
+			"version": "11.4.0",
+			"resolved": "https://registry.npmjs.org/lru-cache/-/lru-cache-11.4.0.tgz",
+			"integrity": "sha512-W+R+kFL4HgVxONq2bhXPi3bGpzGe/yEhVOp233qw9wCRtgncJ15P3bC+e4zZMu4Cq7d+WAJjXGW0uUkifhcatA==",
 			"dev": true,
 			"license": "BlueOak-1.0.0",
 			"engines": {
@@ -1963,20 +1963,20 @@
 			"peer": true
 		},
 		"node_modules/electron-to-chromium": {
-			"version": "1.5.325",
-			"resolved": "https://registry.npmjs.org/electron-to-chromium/-/electron-to-chromium-1.5.325.tgz",
-			"integrity": "sha512-PwfIw7WQSt3xX7yOf5OE/unLzsK9CaN2f/FvV3WjPR1Knoc1T9vePRVV4W1EM301JzzysK51K7FNKcusCr0zYA==",
+			"version": "1.5.359",
+			"resolved": "https://registry.npmjs.org/electron-to-chromium/-/electron-to-chromium-1.5.359.tgz",
+			"integrity": "sha512-8lPELWuYZIWk7NDvCNthtmMw/7Q5Wu25NpM4djFMHBmk8DubPAtL4YTOp7ou0e7HyJtwkVlWv8XMLURnrtgJQw==",
 			"dev": true,
 			"license": "ISC"
 		},
 		"node_modules/entities": {
-			"version": "6.0.1",
-			"resolved": "https://registry.npmjs.org/entities/-/entities-6.0.1.tgz",
-			"integrity": "sha512-aN97NXWF6AWBTahfVOIrB/NShkzi5H7F9r1s9mD3cDj4Ko5f2qhhVoYMibXF7GlLveb/D2ioWay8lxI97Ven3g==",
+			"version": "8.0.0",
+			"resolved": "https://registry.npmjs.org/entities/-/entities-8.0.0.tgz",
+			"integrity": "sha512-zwfzJecQ/Uej6tusMqwAqU/6KL2XaB2VZ2Jg54Je6ahNBGNH6Ek6g3jjNCF0fG9EWQKGZNddNjU5F1ZQn/sBnA==",
 			"dev": true,
 			"license": "BSD-2-Clause",
 			"engines": {
-				"node": ">=0.12"
+				"node": ">=20.19.0"
 			},
 			"funding": {
 				"url": "https://github.com/fb55/entities?sponsor=1"
@@ -2789,9 +2789,9 @@
 			}
 		},
 		"node_modules/make-dir/node_modules/semver": {
-			"version": "7.7.4",
-			"resolved": "https://registry.npmjs.org/semver/-/semver-7.7.4.tgz",
-			"integrity": "sha512-vFKC2IEtQnVhpT78h1Yp8wzwrf8CM+MzKMHGJZfBtzhZNycRFnXsHk6E5TxIkkMsgNS7mdX3AGB7x2QM2di4lA==",
+			"version": "7.8.0",
+			"resolved": "https://registry.npmjs.org/semver/-/semver-7.8.0.tgz",
+			"integrity": "sha512-AcM7dV/5ul4EekoQ29Agm5vri8JNqRyj39o0qpX6vDF2GZrtutZl5RwgD1XnZjiTAfncsJhMI48QQH3sN87YNA==",
 			"dev": true,
 			"license": "ISC",
 			"bin": {
@@ -3439,9 +3439,9 @@
 			}
 		},
 		"node_modules/node-releases": {
-			"version": "2.0.36",
-			"resolved": "https://registry.npmjs.org/node-releases/-/node-releases-2.0.36.tgz",
-			"integrity": "sha512-TdC8FSgHz8Mwtw9g5L4gR/Sh9XhSP/0DEkQxfEFXOpiul5IiHgHan2VhYYb6agDSfp4KuvltmGApc8HMgUrIkA==",
+			"version": "2.0.44",
+			"resolved": "https://registry.npmjs.org/node-releases/-/node-releases-2.0.44.tgz",
+			"integrity": "sha512-5WUyunoPMsvvEhS8AxHtRzP+oA8UCkJ7YRxatWKjngndhDGLiqEVAQKWjFAiAiuL8zMRGzGSJxFnLetoa43qGQ==",
 			"dev": true,
 			"license": "MIT"
 		},
@@ -3482,13 +3482,13 @@
 			"license": "MIT"
 		},
 		"node_modules/parse5": {
-			"version": "8.0.0",
-			"resolved": "https://registry.npmjs.org/parse5/-/parse5-8.0.0.tgz",
-			"integrity": "sha512-9m4m5GSgXjL4AjumKzq1Fgfp3Z8rsvjRNbnkVwfu2ImRqE5D0LnY2QfDen18FSY9C573YU5XxSapdHZTZ2WolA==",
+			"version": "8.0.1",
+			"resolved": "https://registry.npmjs.org/parse5/-/parse5-8.0.1.tgz",
+			"integrity": "sha512-z1e/HMG90obSGeidlli3hj7cbocou0/wa5HacvI3ASx34PecNjNQeaHNo5WIZpWofN9kgkqV1q5YvXe3F0FoPw==",
 			"dev": true,
 			"license": "MIT",
 			"dependencies": {
-				"entities": "^6.0.0"
+				"entities": "^8.0.0"
 			},
 			"funding": {
 				"url": "https://github.com/inikulin/parse5?sponsor=1"
@@ -3522,13 +3522,13 @@
 			}
 		},
 		"node_modules/playwright": {
-			"version": "1.58.2",
-			"resolved": "https://registry.npmjs.org/playwright/-/playwright-1.58.2.tgz",
-			"integrity": "sha512-vA30H8Nvkq/cPBnNw4Q8TWz1EJyqgpuinBcHET0YVJVFldr8JDNiU9LaWAE1KqSkRYazuaBhTpB5ZzShOezQ6A==",
+			"version": "1.60.0",
+			"resolved": "https://registry.npmjs.org/playwright/-/playwright-1.60.0.tgz",
+			"integrity": "sha512-hheHdokM8cdqCb0lcE3s+zT4t4W+vvjpGxsZlDnikarzx8tSzMebh3UiFtgqwFwnTnjYQcsyMF8ei2mCO/tpeA==",
 			"dev": true,
 			"license": "Apache-2.0",
 			"dependencies": {
-				"playwright-core": "1.58.2"
+				"playwright-core": "1.60.0"
 			},
 			"bin": {
 				"playwright": "cli.js"
@@ -3541,9 +3541,9 @@
 			}
 		},
 		"node_modules/playwright-core": {
-			"version": "1.58.2",
-			"resolved": "https://registry.npmjs.org/playwright-core/-/playwright-core-1.58.2.tgz",
-			"integrity": "sha512-yZkEtftgwS8CsfYo7nm0KE8jsvm6i/PTgVtB8DL726wNf6H2IMsDuxCpJj59KDaxCtSnrWan2AeDqM7JBaultg==",
+			"version": "1.60.0",
+			"resolved": "https://registry.npmjs.org/playwright-core/-/playwright-core-1.60.0.tgz",
+			"integrity": "sha512-9bW6zvX/m0lEbgTKJ6YppOKx8H3VOPBMOCFh2irXFOT4BbHgrx5hPjwJYLT40Lu+4qtD36qKc/Hn56StUW57IA==",
 			"dev": true,
 			"license": "Apache-2.0",
 			"bin": {
@@ -3554,9 +3554,9 @@
 			}
 		},
 		"node_modules/postcss": {
-			"version": "8.5.14",
-			"resolved": "https://registry.npmjs.org/postcss/-/postcss-8.5.14.tgz",
-			"integrity": "sha512-SoSL4+OSEtR99LHFZQiJLkT59C5B1amGO1NzTwj7TT1qCUgUO6hxOvzkOYxD+vMrXBM3XJIKzokoERdqQq/Zmg==",
+			"version": "8.5.15",
+			"resolved": "https://registry.npmjs.org/postcss/-/postcss-8.5.15.tgz",
+			"integrity": "sha512-FfR8sjd4em2T6fb3I2MwAJU7HWVMr9zba+enmQeeWFfCbm+UOC/0X4DS8XtpUTMwWMGbjKYP7xjfNekzyGmB3A==",
 			"dev": true,
 			"funding": [
 				{
@@ -3574,7 +3574,7 @@
 			],
 			"license": "MIT",
 			"dependencies": {
-				"nanoid": "^3.3.11",
+				"nanoid": "^3.3.12",
 				"picocolors": "^1.1.1",
 				"source-map-js": "^1.2.1"
 			},
@@ -3628,24 +3628,24 @@
 			}
 		},
 		"node_modules/react": {
-			"version": "19.2.4",
-			"resolved": "https://registry.npmjs.org/react/-/react-19.2.4.tgz",
-			"integrity": "sha512-9nfp2hYpCwOjAN+8TZFGhtWEwgvWHXqESH8qT89AT/lWklpLON22Lc8pEtnpsZz7VmawabSU0gCjnj8aC0euHQ==",
+			"version": "19.2.6",
+			"resolved": "https://registry.npmjs.org/react/-/react-19.2.6.tgz",
+			"integrity": "sha512-sfWGGfavi0xr8Pg0sVsyHMAOziVYKgPLNrS7ig+ivMNb3wbCBw3KxtflsGBAwD3gYQlE/AEZsTLgToRrSCjb0Q==",
 			"license": "MIT",
 			"engines": {
 				"node": ">=0.10.0"
 			}
 		},
 		"node_modules/react-dom": {
-			"version": "19.2.4",
-			"resolved": "https://registry.npmjs.org/react-dom/-/react-dom-19.2.4.tgz",
-			"integrity": "sha512-AXJdLo8kgMbimY95O2aKQqsz2iWi9jMgKJhRBAxECE4IFxfcazB2LmzloIoibJI3C12IlY20+KFaLv+71bUJeQ==",
+			"version": "19.2.6",
+			"resolved": "https://registry.npmjs.org/react-dom/-/react-dom-19.2.6.tgz",
+			"integrity": "sha512-0prMI+hvBbPjsWnxDLxlCGyM8PN6UuWjEUCYmZhO67xIV9Xasa/r/vDnq+Xyq4Lo27g8QSbO5YzARu0D1Sps3g==",
 			"license": "MIT",
 			"dependencies": {
 				"scheduler": "^0.27.0"
 			},
 			"peerDependencies": {
-				"react": "^19.2.4"
+				"react": "^19.2.6"
 			}
 		},
 		"node_modules/react-is": {
@@ -4007,22 +4007,22 @@
 			}
 		},
 		"node_modules/tldts": {
-			"version": "7.0.27",
-			"resolved": "https://registry.npmjs.org/tldts/-/tldts-7.0.27.tgz",
-			"integrity": "sha512-I4FZcVFcqCRuT0ph6dCDpPuO4Xgzvh+spkcTr1gK7peIvxWauoloVO0vuy1FQnijT63ss6AsHB6+OIM4aXHbPg==",
+			"version": "7.0.30",
+			"resolved": "https://registry.npmjs.org/tldts/-/tldts-7.0.30.tgz",
+			"integrity": "sha512-ELrFxuqsDdHUwoh0XxDbxuLD3Wnz49Z57IFvTtvWy1hJdcMZjXLIuonjilCiWHlT2GbE4Wlv1wKVTzDFnXH1aw==",
 			"dev": true,
 			"license": "MIT",
 			"dependencies": {
-				"tldts-core": "^7.0.27"
+				"tldts-core": "^7.0.30"
 			},
 			"bin": {
 				"tldts": "bin/cli.js"
 			}
 		},
 		"node_modules/tldts-core": {
-			"version": "7.0.27",
-			"resolved": "https://registry.npmjs.org/tldts-core/-/tldts-core-7.0.27.tgz",
-			"integrity": "sha512-YQ7uPjgWUibIK6DW5lrKujGwUKhLevU4hcGbP5O6TcIUb+oTjJYJVWPS4nZsIHrEEEG6myk/oqAJUEQmpZrHsg==",
+			"version": "7.0.30",
+			"resolved": "https://registry.npmjs.org/tldts-core/-/tldts-core-7.0.30.tgz",
+			"integrity": "sha512-uiHN8PIB1VmWyS98eZYja4xzlYqeFZVjb4OuYlJQnZAuJhMw4PbKQOKgHKhBdJR3FE/t5mUQ1Kd80++B+qhD1Q==",
 			"dev": true,
 			"license": "MIT"
 		},
@@ -4095,9 +4095,9 @@
 			}
 		},
 		"node_modules/undici": {
-			"version": "7.24.6",
-			"resolved": "https://registry.npmjs.org/undici/-/undici-7.24.6.tgz",
-			"integrity": "sha512-Xi4agocCbRzt0yYMZGMA6ApD7gvtUFaxm4ZmeacWI4cZxaF6C+8I8QfofC20NAePiB/IcvZmzkJ7XPa471AEtA==",
+			"version": "7.25.0",
+			"resolved": "https://registry.npmjs.org/undici/-/undici-7.25.0.tgz",
+			"integrity": "sha512-xXnp4kTyor2Zq+J1FfPI6Eq3ew5h6Vl0F/8d9XU5zZQf1tX9s2Su1/3PiMmUANFULpmksxkClamIZcaUqryHsQ==",
 			"dev": true,
 			"license": "MIT",
 			"engines": {
@@ -4105,9 +4105,9 @@
 			}
 		},
 		"node_modules/undici-types": {
-			"version": "7.18.2",
-			"resolved": "https://registry.npmjs.org/undici-types/-/undici-types-7.18.2.tgz",
-			"integrity": "sha512-AsuCzffGHJybSaRrmr5eHr81mwJU3kjw6M+uprWvCXiNeN9SOGwQ3Jn8jb8m3Z6izVgknn1R0FTCEAP2QrLY/w==",
+			"version": "7.24.6",
+			"resolved": "https://registry.npmjs.org/undici-types/-/undici-types-7.24.6.tgz",
+			"integrity": "sha512-WRNW+sJgj5OBN4/0JpHFqtqzhpbnV0GuB+OozA9gCL7a993SmU+1JBZCzLNxYsbMfIeDL+lTsphD5jN5N+n0zg==",
 			"dev": true,
 			"license": "MIT"
 		},

frontend/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "huskies",
 	"private": true,
-	"version": "0.12.1",
+	"version": "0.13.0",
 	"type": "module",
 	"scripts": {
 		"dev": "vite",

script/local-release

@@ -0,0 +1,165 @@
+#!/usr/bin/env bash
+# Build huskies, install (codesign-heal wrapper + underlying binary), and if a
+# gateway is running on this host, hot-restart it detached from the current shell
+# so SSH disconnect — e.g. when redeploying from a phone — doesn't kill it.
+#
+# Skips the restart silently if no gateway is running. Errors loudly if more
+# than one matches, so we don't restart the wrong one.
+#
+# Pass --skip-check to bypass `script/check` (useful for docs / build-script
+# changes you've already verified).
+#
+# On relaunch failure the previous binary is restored from
+# ~/bin/huskies-bin.prev and re-launched, so a bad deploy doesn't leave the
+# host without a working gateway.
+#
+# After a `cp` or download the binary loses its ad-hoc signature and macOS
+# SIGKILLs it silently on Apple Silicon. The wrapper at ~/bin/huskies re-signs
+# the underlying binary at ~/bin/huskies-bin whenever codesign validation
+# fails, then execs it. Normal launches (already signed) are zero-overhead.
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+PROJECT_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
+LOG_DIR="${HUSKIES_LOG_DIR:-$PROJECT_ROOT/logs}"
+GATEWAY_PATTERN='huskies .*--gateway'
+BIN_DIR="${HOME}/bin"
+UNDERLYING="${BIN_DIR}/huskies-bin"
+WRAPPER="${BIN_DIR}/huskies"
+PREV_BIN="${BIN_DIR}/huskies-bin.prev"
+NEW_BIN="${PROJECT_ROOT}/target/release/huskies"
+
+SKIP_CHECK=0
+for arg in "$@"; do
+  case "$arg" in
+    --skip-check) SKIP_CHECK=1 ;;
+    -h|--help) sed -n '2,17p' "$0"; exit 0 ;;
+    *) echo "Unknown arg: $arg (use --help)" >&2; exit 2 ;;
+  esac
+done
+
+if [ "$SKIP_CHECK" -eq 0 ] && [ -x "$SCRIPT_DIR/check" ]; then
+  echo "=== Running script/check ==="
+  "$SCRIPT_DIR/check"
+fi
+
+echo "=== Building release binary ==="
+cd "$PROJECT_ROOT"
+cargo build --release --bin huskies
+
+mkdir -p "$BIN_DIR"
+
+# Snapshot current binary so we can roll back if the relaunch fails.
+PREV_VERSION=""
+if [ -x "$UNDERLYING" ]; then
+  PREV_VERSION="$("$UNDERLYING" --version 2>/dev/null || echo unknown)"
+  cp "$UNDERLYING" "$PREV_BIN"
+fi
+
+cp "$NEW_BIN" "$UNDERLYING"
+chmod +x "$UNDERLYING"
+codesign -s - -f "$UNDERLYING" 2>/dev/null
+NEW_VERSION="$("$UNDERLYING" --version 2>/dev/null || echo unknown)"
+echo "==> Installed binary:  ${UNDERLYING}"
+if [ -n "$PREV_VERSION" ]; then
+  echo "    version: $PREV_VERSION  →  $NEW_VERSION"
+else
+  echo "    version: $NEW_VERSION (no prior install)"
+fi
+
+cat > "${WRAPPER}" << 'WRAPPER_EOF'
+#!/usr/bin/env bash
+# Codesign-heal wrapper — re-signs ~/bin/huskies-bin if the signature is
+# missing or invalid, then execs the binary.  Logs only when it re-signs.
+BIN="${HOME}/bin/huskies-bin"
+if ! codesign --verify --quiet "${BIN}" 2>/dev/null; then
+    codesign -s - "${BIN}"
+    echo "[codesign-heal] re-signed ~/bin/huskies-bin" >&2
+fi
+exec "${BIN}" "$@"
+WRAPPER_EOF
+chmod +x "${WRAPPER}"
+echo "==> Installed wrapper: ${WRAPPER}"
+
+# ── Hot-restart gateway if one is running ─────────────────────────────
+collect_descendants() {
+  local pid="$1" kid
+  for kid in $(pgrep -P "$pid" 2>/dev/null); do
+    collect_descendants "$kid"
+    printf '%s\n' "$kid"
+  done
+}
+
+GATEWAY_PIDS="$(pgrep -f "$GATEWAY_PATTERN" || true)"
+if [ -z "$GATEWAY_PIDS" ]; then
+  echo "==> No running gateway found; install complete."
+  exit 0
+fi
+
+if [ "$(echo "$GATEWAY_PIDS" | wc -l)" -gt 1 ]; then
+  echo "Error: multiple gateway processes match '${GATEWAY_PATTERN}':" >&2
+  ps -p $GATEWAY_PIDS -o pid,args >&2 || true
+  echo "Refusing to guess which to restart." >&2
+  exit 3
+fi
+
+GATEWAY_PID="$GATEWAY_PIDS"
+GATEWAY_ARGS="$(ps -p "$GATEWAY_PID" -o args= | sed -E 's@^[^ ]*huskies[^ ]* @@')"
+GATEWAY_CWD="$(lsof -p "$GATEWAY_PID" 2>/dev/null | awk '$4=="cwd"{print $9; exit}')"
+if [ -z "$GATEWAY_CWD" ]; then GATEWAY_CWD="$PWD"; fi
+
+LOG_FILE="$LOG_DIR/gateway-$(date +%Y%m%d-%H%M%S).log"
+mkdir -p "$LOG_DIR"
+
+DESCENDANTS="$(collect_descendants "$GATEWAY_PID" | tr '\n' ' ')"
+echo "==> Stopping gateway tree (pids: $GATEWAY_PID $DESCENDANTS)"
+# Kill descendants depth-first so PTY children die before the gateway, then the gateway.
+for pid in $DESCENDANTS $GATEWAY_PID; do
+  kill "$pid" 2>/dev/null || true
+done
+sleep 2
+
+echo "==> Restarting gateway"
+echo "    log: $LOG_FILE"
+(
+  cd "$GATEWAY_CWD"
+  nohup "$WRAPPER" $GATEWAY_ARGS >> "$LOG_FILE" 2>&1 < /dev/null &
+  disown
+)
+
+# Wait up to 10s for the new gateway to appear AND be a different PID.
+NEW_PID=""
+for _ in 1 2 3 4 5 6 7 8 9 10; do
+  sleep 1
+  candidate="$(pgrep -f "$GATEWAY_PATTERN" 2>/dev/null || true)"
+  if [ -n "$candidate" ] && [ "$candidate" != "$GATEWAY_PID" ]; then
+    NEW_PID="$candidate"
+    break
+  fi
+done
+
+if [ -n "$NEW_PID" ]; then
+  echo "==> Gateway restarted as pid $NEW_PID"
+  exit 0
+fi
+
+# ── Rollback ──────────────────────────────────────────────────────────
+echo "Error: new gateway failed to come up within 10s; rolling back" >&2
+if [ -x "$PREV_BIN" ]; then
+  cp "$PREV_BIN" "$UNDERLYING"
+  chmod +x "$UNDERLYING"
+  codesign -s - -f "$UNDERLYING" 2>/dev/null
+  echo "==> Restored previous binary"
+  (
+    cd "$GATEWAY_CWD"
+    nohup "$WRAPPER" $GATEWAY_ARGS >> "$LOG_FILE" 2>&1 < /dev/null &
+    disown
+  )
+  sleep 2
+  if pgrep -f "$GATEWAY_PATTERN" >/dev/null 2>&1; then
+    echo "==> Gateway restored to previous version"
+    exit 1
+  fi
+fi
+echo "Error: rollback failed; gateway is DOWN. Inspect $LOG_FILE." >&2
+exit 1

server/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "huskies"
-version = "0.12.1"
+version = "0.13.0"
 edition = "2024"
 build = "build.rs"
 

server/src/agents/pool/start/spawn.rs

@@ -116,6 +116,23 @@ pub(super) fn maybe_inject_gate_failure(args: &mut Vec<String>, story_id: &str)
     }
 }
 
+/// Append `Edit,Write,Bash` to the `--disallowedTools` flag so worktree agents
+/// cannot write to the master tree via Claude's built-in tools.  If
+/// `--disallowedTools` is already present (from agent config), the three names
+/// are appended to the existing value rather than replacing it.
+pub(super) fn inject_worktree_disallowed_tools(args: &mut Vec<String>) {
+    const BLOCKED: &str = "Edit,Write,Bash";
+    if let Some(pos) = args.iter().position(|a| a == "--disallowedTools") {
+        if let Some(val) = args.get_mut(pos + 1) {
+            val.push(',');
+            val.push_str(BLOCKED);
+        }
+    } else {
+        args.push("--disallowedTools".to_string());
+        args.push(BLOCKED.to_string());
+    }
+}
+
 /// Run the background worktree-creation + agent-launch flow.
 ///
 /// Caller (`AgentPool::start_agent`) wraps this in `tokio::spawn` and stores
@@ -264,6 +281,10 @@ pub(super) async fn run_agent_spawn(
     maybe_inject_gate_failure(&mut args, &sid);
     // Cap turns and budget for merge-gate fixup sessions (story 981).
     maybe_cap_for_merge_fixup(&mut args, &sid);
+    // Every agent that runs inside a worktree must use the validated MCP
+    // edit/write tools instead of Claude's built-in Edit/Write/Bash.  This
+    // prevents accidental writes to the master worktree (stories 1127, 1136).
+    inject_worktree_disallowed_tools(&mut args);
 
     // Append project-local prompt content (.huskies/AGENT.md) to the
     // baked-in prompt so every agent role sees project-specific guidance
@@ -1297,4 +1318,43 @@ mod tests {
             item.stage().dir_name()
         );
     }
+
+    // ── inject_worktree_disallowed_tools (AC1, story 1142) ───────────
+
+    /// AC3(c) proxy: worktree agents get `--disallowedTools Edit,Write,Bash`.
+    #[test]
+    fn worktree_disallowed_tools_added_when_absent() {
+        let mut args: Vec<String> = vec!["--verbose".to_string()];
+        inject_worktree_disallowed_tools(&mut args);
+        let pos = args
+            .iter()
+            .position(|a| a == "--disallowedTools")
+            .expect("--disallowedTools must be present");
+        let val = &args[pos + 1];
+        assert!(val.contains("Edit"), "must include Edit");
+        assert!(val.contains("Write"), "must include Write");
+        assert!(val.contains("Bash"), "must include Bash");
+    }
+
+    /// Existing `--disallowedTools` value is extended, not replaced.
+    #[test]
+    fn worktree_disallowed_tools_appended_to_existing() {
+        let mut args = vec!["--disallowedTools".to_string(), "SomeOtherTool".to_string()];
+        inject_worktree_disallowed_tools(&mut args);
+        // Only one --disallowedTools flag.
+        let count = args
+            .iter()
+            .filter(|a| a.as_str() == "--disallowedTools")
+            .count();
+        assert_eq!(count, 1, "must not duplicate --disallowedTools");
+        let pos = args.iter().position(|a| a == "--disallowedTools").unwrap();
+        let val = &args[pos + 1];
+        assert!(
+            val.contains("SomeOtherTool"),
+            "original tool must be preserved"
+        );
+        assert!(val.contains("Edit"), "Edit must be added");
+        assert!(val.contains("Write"), "Write must be added");
+        assert!(val.contains("Bash"), "Bash must be added");
+    }
 }

server/src/agents/pool/worktree_lifecycle.rs

@@ -129,7 +129,13 @@ pub(crate) async fn on_coding_transition(project_root: &Path, port: u16, story_i
                 "[worktree-create-sub] Worktree ready for '{story_id}' at {}",
                 info.path.display()
             );
-            if let Err(e) = crate::worktree::install_pre_commit_hook(&info.path) {
+            let hook_path = info.path.clone();
+            let hook_result = tokio::task::spawn_blocking(move || {
+                crate::worktree::install_pre_commit_hook(&hook_path)
+            })
+            .await
+            .unwrap_or_else(|e| Err(format!("spawn_blocking panicked: {e}")));
+            if let Err(e) = hook_result {
                 slog_warn!(
                     "[worktree-create-sub] Pre-commit hook install failed for '{story_id}': {e}"
                 );

server/src/chat/commands/convert.rs

@@ -0,0 +1,188 @@
+//! Handler for the `convert` chat command (story 1141).
+//!
+//! `convert <number> <type>` changes the item-type register of a work item
+//! in place.  All other CRDT registers (ACs, epic, name, stage, …) are
+//! untouched.  Rejected for archived items.
+
+use super::CommandContext;
+
+/// Handle the `convert` command.
+///
+/// Parses `<number> <type>` from `ctx.args` and delegates to
+/// [`convert_by_number`].  Returns `None` (route to LLM) when args do not
+/// look like a numeric ID followed by a type keyword.
+pub(super) fn handle_convert(ctx: &CommandContext) -> Option<String> {
+    let args = ctx.args.trim();
+    let (num_str, type_str) = args.split_once(char::is_whitespace)?;
+    let num_str = num_str.trim();
+    let type_str = type_str.trim();
+
+    // Route to LLM if the first token is not a bare number.
+    if num_str.is_empty() || !num_str.chars().all(|c| c.is_ascii_digit()) {
+        return None;
+    }
+    // Route to LLM if the type looks like natural language (contains spaces).
+    if type_str.is_empty() || type_str.contains(char::is_whitespace) {
+        return None;
+    }
+
+    Some(convert_by_number(ctx.effective_root(), num_str, type_str))
+}
+
+/// Core convert logic: find item by numeric prefix and change its type.
+///
+/// Returns a Markdown-formatted response suitable for all chat transports.
+pub(crate) fn convert_by_number(
+    project_root: &std::path::Path,
+    story_number: &str,
+    new_type_str: &str,
+) -> String {
+    let Some(new_type) = crate::io::story_metadata::ItemType::from_str(new_type_str) else {
+        return format!(
+            "Unknown type **{new_type_str}**. Accepted types: story, bug, spike, refactor, epic."
+        );
+    };
+
+    let (story_id, _, _, _) =
+        match crate::chat::lookup::find_story_by_number(project_root, story_number) {
+            Some(found) => found,
+            None => {
+                return format!(
+                    "No story, bug, spike, or refactor with number **{story_number}** found."
+                );
+            }
+        };
+
+    let item = match crate::crdt_state::read_item(&story_id) {
+        Some(i) => i,
+        None => {
+            return format!("Work item **{story_number}** ({story_id}) not found in CRDT.");
+        }
+    };
+
+    if matches!(item.stage(), crate::pipeline_state::Stage::Archived { .. }) {
+        return format!(
+            "Cannot convert **{story_id}**: type change on an archived item is not allowed."
+        );
+    }
+
+    let old_type = item.item_type().map(|t| t.as_str()).unwrap_or("(inferred)");
+    let story_name = item.name().to_string();
+    let new_type_s = new_type.as_str();
+
+    if !crate::crdt_state::set_item_type(&story_id, Some(new_type)) {
+        return format!("Failed to convert **{story_id}**: CRDT write rejected.");
+    }
+
+    format!("Converted **{story_name}** ({story_id}) from type `{old_type}` to `{new_type_s}`.")
+}
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+#[cfg(test)]
+mod tests {
+    use super::super::{CommandDispatch, try_handle_command};
+
+    fn convert_cmd(root: &std::path::Path, args: &str) -> Option<String> {
+        let services = crate::services::Services::new_test(root.to_path_buf(), "Timmy".to_string());
+        let room_id = "!test:example.com".to_string();
+        let dispatch = CommandDispatch {
+            services: &services,
+            project_root: &services.project_root,
+            bot_user_id: "@timmy:homeserver.local",
+            room_id: &room_id,
+        };
+        try_handle_command(&dispatch, &format!("@timmy convert {args}"))
+    }
+
+    #[test]
+    fn convert_command_is_registered() {
+        use super::super::commands;
+        assert!(
+            commands().iter().any(|c| c.name == "convert"),
+            "convert command must be in the registry"
+        );
+    }
+
+    #[test]
+    fn convert_no_args_routes_to_llm() {
+        let tmp = tempfile::TempDir::new().unwrap();
+        let result = convert_cmd(tmp.path(), "");
+        assert!(result.is_none(), "no args should route to LLM: {result:?}");
+    }
+
+    #[test]
+    fn convert_natural_language_routes_to_llm() {
+        let tmp = tempfile::TempDir::new().unwrap();
+        let result = convert_cmd(tmp.path(), "the login bug to a story");
+        assert!(
+            result.is_none(),
+            "natural-language args should route to LLM: {result:?}"
+        );
+    }
+
+    #[test]
+    fn convert_well_formed_runs_handler() {
+        let tmp = tempfile::TempDir::new().unwrap();
+        let result = convert_cmd(tmp.path(), "999 story");
+        assert!(
+            result.is_some(),
+            "well-formed args should run the handler: {result:?}"
+        );
+    }
+
+    #[test]
+    fn convert_invalid_type_returns_error() {
+        let tmp = tempfile::TempDir::new().unwrap();
+        let result = convert_cmd(tmp.path(), "999 banana").unwrap();
+        assert!(
+            result.contains("Unknown type") || result.contains("banana"),
+            "unknown type should show error: {result}"
+        );
+    }
+
+    #[test]
+    fn convert_not_found_returns_error() {
+        let tmp = tempfile::TempDir::new().unwrap();
+        let result = convert_cmd(tmp.path(), "9988 story").unwrap();
+        assert!(
+            result.contains("9988") && result.contains("found"),
+            "not-found message should include number and 'found': {result}"
+        );
+    }
+
+    #[test]
+    fn convert_changes_item_type_in_crdt() {
+        let tmp = tempfile::TempDir::new().unwrap();
+        crate::crdt_state::init_for_test();
+        crate::db::ensure_content_store();
+        crate::chat::test_helpers::write_story_file(
+            tmp.path(),
+            "backlog",
+            "9120_spike_convert_chat.md",
+            "# Spike\n",
+            Some("Convert Chat Test"),
+        );
+        crate::crdt_state::set_item_type(
+            "9120_spike_convert_chat",
+            Some(crate::io::story_metadata::ItemType::Spike),
+        );
+
+        let result = convert_cmd(tmp.path(), "9120 story").unwrap();
+        assert!(
+            result.contains("story") || result.contains("Converted"),
+            "should confirm conversion: {result}"
+        );
+
+        let item =
+            crate::crdt_state::read_item("9120_spike_convert_chat").expect("item should exist");
+        assert_eq!(
+            item.item_type(),
+            Some(crate::io::story_metadata::ItemType::Story),
+            "item_type should be Story after conversion: {:?}",
+            item.item_type()
+        );
+    }
+}

server/src/chat/commands/mod.rs

@@ -9,6 +9,7 @@ mod ambient;
 mod assign;
 mod backlog;
 mod cleanup_worktrees;
+mod convert;
 mod cost;
 mod coverage;
 mod depends;
@@ -233,6 +234,11 @@ pub fn commands() -> &'static [BotCommand] {
             description: "Schedule a deferred agent start: `timer <story_id> <HH:MM>`, `timer list`, `timer cancel <story_id>`",
             handler: timer::handle_timer,
         },
+        BotCommand {
+            name: "convert",
+            description: "Convert a work item's type: `convert <number> <type>` (types: story, bug, spike, refactor, epic)",
+            handler: convert::handle_convert,
+        },
         BotCommand {
             name: "unblock",
             description: "Reset a blocked story: `unblock <number>` (clears blocked flag and resets retry count)",
@@ -263,11 +269,21 @@ pub fn commands() -> &'static [BotCommand] {
             description: "List orphaned worktrees (dry run), or `cleanup_worktrees --confirm` to remove them",
             handler: handle_cleanup_worktrees_fallback,
         },
+        BotCommand {
+            name: "health",
+            description: "Show subsystem health: gateway, sled, matrix-sync, creds, and build-hash",
+            handler: handle_health_fallback,
+        },
         BotCommand {
             name: "new",
             description: "Bootstrap a new project container (gateway only): `new project <name>`",
             handler: new_project::handle_new_project_fallback,
         },
+        BotCommand {
+            name: "project-rebuild",
+            description: "Rebuild a project's Docker image and swap the container (gateway only): `project-rebuild <name> [--timeout <secs>] [--force]`",
+            handler: handle_project_rebuild_fallback,
+        },
     ]
 }
 
@@ -425,6 +441,26 @@ fn handle_cleanup_worktrees_fallback(_ctx: &CommandContext) -> Option<String> {
     None
 }
 
+/// Fallback handler for the `project-rebuild` command when it is not intercepted
+/// by the async gateway handler in `on_room_message`.  In practice this is never
+/// called — `project-rebuild` is detected and handled before `try_handle_command`
+/// runs in gateway mode.  The entry exists in the registry so `help` lists it.
+///
+/// Returns `None` to prevent the LLM from receiving the raw command text.
+fn handle_project_rebuild_fallback(_ctx: &CommandContext) -> Option<String> {
+    None
+}
+
+/// Fallback handler for the `health` command when it is not intercepted by the
+/// async handler in `on_room_message`.  In practice this is never called — health
+/// is detected and handled before `try_handle_command` is invoked.  The entry
+/// exists in the registry only so `help` lists it.
+///
+/// Returns `None` to prevent the LLM from receiving "health" as a prompt.
+fn handle_health_fallback(_ctx: &CommandContext) -> Option<String> {
+    None
+}
+
 // ---------------------------------------------------------------------------
 // Tests
 // ---------------------------------------------------------------------------

server/src/chat/transport/discord/commands.rs

@@ -303,12 +303,12 @@ pub(super) async fn handle_incoming_message(
 /// Build the prompt for a Discord LLM turn, prepending any pending
 /// CRDT pipeline-transition events as a `<system-reminder>` block.
 fn build_discord_llm_prompt(
-    session_id: &str,
+    persona: &str,
     bot_name: &str,
     user: &str,
     user_message: &str,
 ) -> String {
-    let event_ctx = crate::llm_session::assemble_prompt_context(session_id);
+    let event_ctx = crate::llm_session::assemble_prompt_context(persona);
     format!(
         "{event_ctx}[Your name is {bot_name}. Refer to yourself as {bot_name}, not Claude.]\n\n{user}: {user_message}"
     )
@@ -328,12 +328,8 @@ async fn handle_llm_message(ctx: &DiscordContext, channel: &str, user: &str, use
     };
 
     let bot_name = &ctx.services.bot_name;
-    let prompt = build_discord_llm_prompt(
-        resume_session_id.as_deref().unwrap_or(channel),
-        bot_name,
-        user,
-        user_message,
-    );
+    let persona = bot_name.to_lowercase();
+    let prompt = build_discord_llm_prompt(&persona, bot_name, user, user_message);
 
     let provider = ClaudeCodeProvider::new();
     let (_cancel_tx, mut cancel_rx) = watch::channel(false);

server/src/chat/transport/matrix/bot/context.rs

@@ -6,6 +6,7 @@ use crate::services::Services;
 use matrix_sdk::ruma::{OwnedEventId, OwnedRoomId, OwnedUserId};
 use std::collections::{BTreeMap, HashSet, VecDeque};
 use std::sync::Arc;
+use std::sync::atomic::AtomicI64;
 use tokio::sync::Mutex as TokioMutex;
 use tokio::sync::RwLock;
 
@@ -88,10 +89,6 @@ pub struct BotContext {
     /// In gateway mode: the currently active project (shared with the gateway HTTP handler).
     /// `None` in standalone single-project mode.
     pub gateway_active_project: Option<Arc<RwLock<String>>>,
-    /// In gateway mode: mapping of project name → base URL (e.g. `"http://localhost:3001"`).
-    /// Used to proxy bot commands to the active project over WebSocket (`/ws`).
-    /// Empty in standalone mode.
-    pub gateway_project_urls: BTreeMap<String, String>,
     /// In gateway mode: shared live projects map from [`GatewayState`].
     ///
     /// The `new project` command writes here so HTTP handlers see the new entry
@@ -103,6 +100,15 @@ pub struct BotContext {
     /// each event is processed at most once. Insert the event ID before any
     /// side-effecting work; return early if the insert returns `false`.
     pub handled_incoming_event_ids: Arc<TokioMutex<SeenEventIds>>,
+    /// In gateway mode: the port the gateway is listening on.
+    ///
+    /// Used by the "rebuild gateway" command to construct the health-check URL
+    /// passed to the trampoline.  `None` in standalone single-project mode.
+    pub gateway_port: Option<u16>,
+    /// Timestamp (ms since Unix epoch) of the last Matrix event received in any
+    /// configured room.  Updated atomically on every `on_room_message` call so
+    /// the `health` command can detect a stale or dead sync loop.
+    pub last_matrix_event_ms: Arc<AtomicI64>,
 }
 
 impl BotContext {
@@ -130,7 +136,12 @@ impl BotContext {
     pub async fn active_project_url(&self) -> Option<String> {
         let ap = self.gateway_active_project.as_ref()?;
         let name = ap.read().await.clone();
-        self.gateway_project_urls.get(&name).cloned()
+        let store = self.gateway_projects_store.as_ref()?;
+        store
+            .read()
+            .await
+            .get(&name)
+            .and_then(|entry| entry.url.clone())
     }
 
     /// Proxy a bot command to the active project over a WebSocket RPC call.
@@ -266,7 +277,9 @@ mod tests {
     fn test_bot_context(
         services: Arc<Services>,
         gateway_active_project: Option<Arc<RwLock<String>>>,
-        gateway_project_urls: BTreeMap<String, String>,
+        gateway_projects_store: Option<
+            Arc<RwLock<BTreeMap<String, crate::service::gateway::config::ProjectEntry>>>,
+        >,
     ) -> BotContext {
         BotContext {
             services,
@@ -286,11 +299,12 @@ mod tests {
                 std::path::PathBuf::from("/tmp/timers.json"),
             )),
             gateway_active_project,
-            gateway_project_urls,
-            gateway_projects_store: None,
+            gateway_projects_store,
             handled_incoming_event_ids: Arc::new(TokioMutex::new(SeenEventIds::new(
                 SEEN_EVENT_IDS_CAP,
             ))),
+            gateway_port: None,
+            last_matrix_event_ms: Arc::new(AtomicI64::new(chrono::Utc::now().timestamp_millis())),
         }
     }
 
@@ -304,7 +318,7 @@ mod tests {
     #[tokio::test]
     async fn effective_project_root_standalone_returns_project_root() {
         let services = test_services(PathBuf::from("/projects/myapp"));
-        let ctx = test_bot_context(services, None, BTreeMap::new());
+        let ctx = test_bot_context(services, None, None);
         assert_eq!(
             ctx.effective_project_root().await,
             PathBuf::from("/projects/myapp")
@@ -315,14 +329,7 @@ mod tests {
     async fn effective_project_root_gateway_uses_active_project_subdir() {
         let services = test_services(PathBuf::from("/gateway"));
         let active = Arc::new(RwLock::new("huskies".to_string()));
-        let ctx = test_bot_context(
-            services,
-            Some(Arc::clone(&active)),
-            BTreeMap::from([
-                ("huskies".into(), "http://localhost:3001".into()),
-                ("robot-studio".into(), "http://localhost:3002".into()),
-            ]),
-        );
+        let ctx = test_bot_context(services, Some(Arc::clone(&active)), None);
         assert_eq!(
             ctx.effective_project_root().await,
             PathBuf::from("/gateway/huskies")
@@ -333,14 +340,7 @@ mod tests {
     async fn effective_project_root_gateway_reflects_project_switch() {
         let services = test_services(PathBuf::from("/gateway"));
         let active = Arc::new(RwLock::new("huskies".to_string()));
-        let ctx = test_bot_context(
-            services,
-            Some(Arc::clone(&active)),
-            BTreeMap::from([
-                ("huskies".into(), "http://localhost:3001".into()),
-                ("robot-studio".into(), "http://localhost:3002".into()),
-            ]),
-        );
+        let ctx = test_bot_context(services, Some(Arc::clone(&active)), None);
 
         assert_eq!(
             ctx.effective_project_root().await,
@@ -416,7 +416,7 @@ mod tests {
     #[test]
     fn bot_context_has_no_require_verified_devices_field() {
         let services = test_services(PathBuf::from("/tmp"));
-        let ctx = test_bot_context(services, None, BTreeMap::new());
+        let ctx = test_bot_context(services, None, None);
         let _cloned = ctx.clone();
     }
 
@@ -463,11 +463,16 @@ mod tests {
         let base_url = format!("http://127.0.0.1:{port}");
         let services = test_services(PathBuf::from("/gateway"));
         let active = Arc::new(RwLock::new("huskies".to_string()));
-        let ctx = test_bot_context(
-            services,
-            Some(Arc::clone(&active)),
-            BTreeMap::from([("huskies".into(), base_url)]),
-        );
+        let store = Arc::new(RwLock::new(BTreeMap::from([(
+            "huskies".to_string(),
+            crate::service::gateway::config::ProjectEntry {
+                url: Some(base_url),
+                auth_token: None,
+                ssh_port: None,
+                host_path: None,
+            },
+        )])));
+        let ctx = test_bot_context(services, Some(Arc::clone(&active)), Some(store));
 
         let result = ctx.proxy_bot_command("status", "").await;
         assert_eq!(
@@ -478,4 +483,45 @@ mod tests {
 
         server.await.unwrap();
     }
+
+    /// Regression test for story 1132: `active_project_url` must read from the
+    /// live `gateway_projects_store`, not a stale snapshot frozen at bot startup.
+    /// Adding a project to the store after `BotContext` is created must be
+    /// visible immediately — no restart required.
+    #[tokio::test]
+    async fn active_project_url_reflects_runtime_added_project() {
+        let store: Arc<RwLock<BTreeMap<String, crate::service::gateway::config::ProjectEntry>>> =
+            Arc::new(RwLock::new(BTreeMap::new()));
+        let active = Arc::new(RwLock::new("new-project".to_string()));
+        let services = test_services(PathBuf::from("/gateway"));
+        let ctx = test_bot_context(
+            services,
+            Some(Arc::clone(&active)),
+            Some(Arc::clone(&store)),
+        );
+
+        // Store is empty — must return None.
+        assert!(
+            ctx.active_project_url().await.is_none(),
+            "URL must be None when store is empty"
+        );
+
+        // Insert the entry at runtime (simulates `new project` command).
+        store.write().await.insert(
+            "new-project".to_string(),
+            crate::service::gateway::config::ProjectEntry {
+                url: Some("http://localhost:3099".to_string()),
+                auth_token: None,
+                ssh_port: None,
+                host_path: None,
+            },
+        );
+
+        // Now the live store has the entry — active_project_url must see it.
+        assert_eq!(
+            ctx.active_project_url().await.as_deref(),
+            Some("http://localhost:3099"),
+            "URL must be visible after runtime insertion without bot restart"
+        );
+    }
 }

server/src/chat/transport/matrix/bot/format.rs

@@ -9,6 +9,23 @@ pub fn format_startup_announcement(bot_name: &str) -> String {
     format!("{bot_name} is online.")
 }
 
+/// Format the ready announcement sent after a successful gateway trampoline restart.
+///
+/// Returns "gateway X.Y.Z ready" using the compiled-in crate version so the
+/// operator can confirm which binary is running after a rebuild.
+pub fn format_gateway_ready_announcement() -> String {
+    format!("gateway {} ready", env!("CARGO_PKG_VERSION"))
+}
+
+/// Format the failure announcement sent when the trampoline rolls back to the
+/// previous binary.
+///
+/// `reason` is the human-readable failure description from the trampoline
+/// (e.g. "port 3000 already in use").
+pub fn format_gateway_rollback_announcement(reason: &str) -> String {
+    format!("Gateway rebuild failed: {reason}. Previous version restored.")
+}
+
 /// Convert a Markdown string to an HTML string using pulldown-cmark.
 ///
 /// Enables the standard extension set (tables, footnotes, strikethrough,

server/src/chat/transport/matrix/bot/messages/handle_message.rs

@@ -32,9 +32,12 @@ pub(in crate::chat::transport::matrix::bot) async fn handle_message(
     };
 
     // Pull new pipeline-transition events from the CRDT event log for this
-    // session and atomically advance the high-water marks so the same events
-    // are not re-injected on the next turn.
-    let event_log_ctx = crate::llm_session::assemble_prompt_context(&room_id_str);
+    // persona and atomically advance the high-water marks so the same events
+    // are not re-injected on the next turn.  All transports share the same
+    // persona key so events are visible regardless of which transport handles
+    // the next turn.
+    let persona = ctx.services.bot_name.to_lowercase();
+    let event_log_ctx = crate::llm_session::assemble_prompt_context(&persona);
 
     // The prompt is just the current message with sender attribution.
     // Prior conversation context is carried by the Claude Code session.

server/src/chat/transport/matrix/bot/messages/on_room_message.rs

@@ -19,6 +19,42 @@ use super::super::verification::check_sender_verified;
 
 use super::handle_message;
 
+/// Return `true` when the message is a `health` command addressed to the bot.
+///
+/// Recognised case-insensitively as the single word `health` after stripping the bot
+/// mention prefix.  Any trailing whitespace is ignored; extra arguments are not
+/// expected and are silently discarded.
+fn extract_health_command(message: &str, bot_name: &str, bot_user_id: &str) -> bool {
+    let stripped = crate::chat::util::strip_bot_mention(message, bot_name, bot_user_id);
+    let trimmed = stripped
+        .trim()
+        .trim_start_matches(|c: char| !c.is_alphanumeric());
+    let cmd = trimmed.split_whitespace().next().unwrap_or("");
+    cmd.eq_ignore_ascii_case("health")
+}
+
+/// Return `true` when the message is a "rebuild gateway" command addressed to the bot.
+///
+/// The command is recognised case-insensitively as `rebuild gateway` after stripping
+/// the bot mention prefix so both `@Timmy rebuild gateway` and `Timmy rebuild gateway`
+/// match.
+fn extract_rebuild_gateway_command(message: &str, bot_name: &str, bot_user_id: &str) -> bool {
+    let stripped = crate::chat::util::strip_bot_mention(message, bot_name, bot_user_id);
+    let trimmed = stripped
+        .trim()
+        .trim_start_matches(|c: char| !c.is_alphanumeric());
+    let (cmd, rest) = match trimmed.split_once(char::is_whitespace) {
+        Some((c, r)) => (c, r.trim()),
+        None => return false,
+    };
+    cmd.eq_ignore_ascii_case("rebuild")
+        && rest
+            .split_whitespace()
+            .next()
+            .map(|w| w.eq_ignore_ascii_case("gateway"))
+            .unwrap_or(false)
+}
+
 /// Evaluate a `switch <arg>` command against the live project store.
 ///
 /// Reads valid project names from the store at call time so newly added
@@ -78,6 +114,12 @@ pub(in crate::chat::transport::matrix::bot) async fn on_room_message(
         return;
     }
 
+    // Update last-event timestamp so the `health` command can detect a stale sync loop.
+    ctx.last_matrix_event_ms.store(
+        chrono::Utc::now().timestamp_millis(),
+        std::sync::atomic::Ordering::Relaxed,
+    );
+
     // Ignore the bot's own messages to prevent echo loops.
     if ev.sender == ctx.matrix_user_id {
         return;
@@ -217,8 +259,18 @@ pub(in crate::chat::transport::matrix::bot) async fn on_room_message(
     // endpoint.  Only a small set of gateway-local commands are handled here.
     if ctx.is_gateway() {
         // Commands that are meaningful on the gateway itself (no project state needed).
-        const GATEWAY_LOCAL_COMMANDS: &[&str] =
-            &["help", "ambient", "reset", "switch", "all_status", "new"];
+        const GATEWAY_LOCAL_COMMANDS: &[&str] = &[
+            "help",
+            "ambient",
+            "reset",
+            "switch",
+            "all_status",
+            "new",
+            "config",
+            "project-rebuild",
+            "upgrade",
+            "health",
+        ];
 
         let stripped = crate::chat::util::strip_bot_mention(
             &user_message,
@@ -265,7 +317,18 @@ pub(in crate::chat::transport::matrix::bot) async fn on_room_message(
 
         // `all_status` — aggregate pipeline status across all projects (gateway-only).
         if cmd == "all_status" {
-            let project_urls = ctx.gateway_project_urls.clone();
+            let project_urls: std::collections::BTreeMap<String, String> = if let Some(ref store) =
+                ctx.gateway_projects_store
+            {
+                store
+                    .read()
+                    .await
+                    .iter()
+                    .filter_map(|(name, entry)| entry.url.clone().map(|url| (name.clone(), url)))
+                    .collect()
+            } else {
+                std::collections::BTreeMap::new()
+            };
             let client = reqwest::Client::new();
             let statuses =
                 crate::gateway::fetch_all_project_pipeline_statuses(&project_urls, &client).await;
@@ -282,6 +345,63 @@ pub(in crate::chat::transport::matrix::bot) async fn on_room_message(
             return;
         }
 
+        // `config <project> <key>=<value>` — override an agent or project setting.
+        if cmd == "config" {
+            let response = if let Some(ref store) = ctx.gateway_projects_store {
+                // Parse: "<project> <key>=<value>"
+                let mut parts = args.splitn(2, char::is_whitespace);
+                let project = parts.next().unwrap_or("").trim();
+                let setting = parts.next().unwrap_or("").trim();
+                if project.is_empty() || setting.is_empty() {
+                    "Usage: `config <project> <key>=<value>`\n\
+                     Examples:\n\
+                     - `config myapp coder.model=opus`\n\
+                     - `config myapp default_qa=human`"
+                        .to_string()
+                } else {
+                    match setting.split_once('=') {
+                        None => {
+                            "Usage: setting must be in `key=value` form, e.g. `coder.model=opus`"
+                                .to_string()
+                        }
+                        Some((key, value)) => {
+                            let host_path_opt = {
+                                let projects = store.read().await;
+                                projects.get(project).and_then(|e| e.host_path.clone())
+                            };
+                            match host_path_opt {
+                                None => format!(
+                                    "Project `{project}` not found or has no host path configured."
+                                ),
+                                Some(path) => {
+                                    match super::super::super::new_project::apply_project_config(
+                                        std::path::Path::new(&path),
+                                        key.trim(),
+                                        value.trim(),
+                                    ) {
+                                        Ok(msg) => msg,
+                                        Err(e) => format!("Config error: {e}"),
+                                    }
+                                }
+                            }
+                        }
+                    }
+                }
+            } else {
+                "Gateway projects store unavailable.".to_string()
+            };
+            let html = markdown_to_html(&response);
+            if let Ok(msg_id) = ctx
+                .transport
+                .send_message(&room_id_str, &response, &html)
+                .await
+                && let Ok(event_id) = msg_id.parse()
+            {
+                ctx.bot_sent_event_ids.lock().await.insert(event_id);
+            }
+            return;
+        }
+
         // Gateway-local commands and freeform text fall through to normal handling below.
     }
 
@@ -309,6 +429,7 @@ pub(in crate::chat::transport::matrix::bot) async fn on_room_message(
                 cmd.git_token.as_deref(),
                 cmd.host_path.as_deref(),
                 cmd.adopt_path.as_deref(),
+                cmd.skip_config,
                 store,
                 &ctx.services.project_root,
             )
@@ -328,6 +449,144 @@ pub(in crate::chat::transport::matrix::bot) async fn on_room_message(
         return;
     }
 
+    // In gateway mode, handle the `project-rebuild <name>` command to rebuild a
+    // project container and swap it without losing pipeline state.
+    if ctx.is_gateway()
+        && let Some(rebuild_cmd) =
+            super::super::super::project_rebuild::extract_project_rebuild_command(
+                &user_message,
+                &ctx.services.bot_name,
+                ctx.matrix_user_id.as_str(),
+            )
+    {
+        slog!(
+            "[matrix-bot] Handling project-rebuild command from {sender}: name={:?} timeout={}s force={}",
+            rebuild_cmd.name,
+            rebuild_cmd.drain_timeout_secs,
+            rebuild_cmd.force,
+        );
+        let response = if let Some(ref store) = ctx.gateway_projects_store {
+            super::super::super::project_rebuild::handle_project_rebuild(
+                &rebuild_cmd.name,
+                rebuild_cmd.drain_timeout_secs,
+                rebuild_cmd.force,
+                store,
+                &ctx.services.project_root,
+            )
+            .await
+        } else {
+            "Gateway projects store unavailable — cannot rebuild project.".to_string()
+        };
+        let html = markdown_to_html(&response);
+        if let Ok(msg_id) = ctx
+            .transport
+            .send_message(&room_id_str, &response, &html)
+            .await
+            && let Ok(event_id) = msg_id.parse()
+        {
+            ctx.bot_sent_event_ids.lock().await.insert(event_id);
+        }
+        return;
+    }
+
+    // In gateway mode, handle the `upgrade [<project>]` command to upgrade a
+    // sled's binary in-container, streaming phase markers to the room.
+    if ctx.is_gateway()
+        && let Some(upgrade_cmd) = super::super::super::sled_upgrade::extract_upgrade_command(
+            &user_message,
+            &ctx.services.bot_name,
+            ctx.matrix_user_id.as_str(),
+        )
+    {
+        match upgrade_cmd {
+            super::super::super::sled_upgrade::UpgradeCommand::ListProjects => {
+                slog!("[matrix-bot] Handling 'upgrade' list-projects from {sender}");
+                let response = if let Some(ref store) = ctx.gateway_projects_store {
+                    super::super::super::sled_upgrade::handle_upgrade_list_projects(store).await
+                } else {
+                    "Gateway projects store unavailable.".to_string()
+                };
+                let html = markdown_to_html(&response);
+                if let Ok(msg_id) = ctx
+                    .transport
+                    .send_message(&room_id_str, &response, &html)
+                    .await
+                    && let Ok(event_id) = msg_id.parse()
+                {
+                    ctx.bot_sent_event_ids.lock().await.insert(event_id);
+                }
+            }
+            super::super::super::sled_upgrade::UpgradeCommand::Upgrade { project } => {
+                slog!("[matrix-bot] Handling 'upgrade {project}' from {sender}");
+                if let Some(ref store) = ctx.gateway_projects_store {
+                    let transport = Arc::clone(&ctx.transport);
+                    let bot_sent = Arc::clone(&ctx.bot_sent_event_ids);
+                    let room = room_id_str.clone();
+
+                    let response = super::super::super::sled_upgrade::handle_sled_upgrade(
+                        &project,
+                        store,
+                        ctx.gateway_port,
+                        |phase_msg| {
+                            let transport = Arc::clone(&transport);
+                            let bot_sent = Arc::clone(&bot_sent);
+                            let room = room.clone();
+                            async move {
+                                let html = markdown_to_html(&phase_msg);
+                                if let Ok(msg_id) =
+                                    transport.send_message(&room, &phase_msg, &html).await
+                                    && let Ok(event_id) = msg_id.parse()
+                                {
+                                    bot_sent.lock().await.insert(event_id);
+                                }
+                            }
+                        },
+                    )
+                    .await;
+
+                    let html = markdown_to_html(&response);
+                    if let Ok(msg_id) = ctx
+                        .transport
+                        .send_message(&room_id_str, &response, &html)
+                        .await
+                        && let Ok(event_id) = msg_id.parse()
+                    {
+                        ctx.bot_sent_event_ids.lock().await.insert(event_id);
+                    }
+                } else {
+                    let msg = "Gateway projects store unavailable — cannot upgrade sled.";
+                    let html = markdown_to_html(msg);
+                    if let Ok(msg_id) = ctx.transport.send_message(&room_id_str, msg, &html).await
+                        && let Ok(event_id) = msg_id.parse()
+                    {
+                        ctx.bot_sent_event_ids.lock().await.insert(event_id);
+                    }
+                }
+            }
+        }
+        return;
+    }
+
+    // `health` — async subsystem health report (gateway + standalone).
+    if extract_health_command(
+        &user_message,
+        &ctx.services.bot_name,
+        ctx.matrix_user_id.as_str(),
+    ) {
+        slog!("[matrix-bot] Handling 'health' from {sender}");
+        let response = super::super::super::health::run_health_check(&ctx).await;
+        let html = markdown_to_html(&response);
+        if let Ok(msg_id) = ctx
+            .transport
+            .send_message(&room_id_str, &response, &html)
+            .await
+            && let Ok(event_id) = msg_id.parse()
+        {
+            ctx.bot_sent_event_ids.lock().await.insert(event_id);
+        }
+        return;
+    }
+
     // Check for bot-level commands (help, status, ambient, …) before invoking
     // the LLM.  All commands are registered in commands.rs — no special-casing
     // needed here.
@@ -540,6 +799,87 @@ pub(in crate::chat::transport::matrix::bot) async fn on_room_message(
         return;
     }
 
+    // In gateway mode, intercept "rebuild gateway" and route it through the
+    // detached trampoline so the process swap survives any bash-tool kill cascade.
+    if ctx.gateway_active_project.is_some()
+        && extract_rebuild_gateway_command(
+            &user_message,
+            &ctx.services.bot_name,
+            ctx.matrix_user_id.as_str(),
+        )
+    {
+        slog!("[matrix-bot] Handling 'rebuild gateway' command from {sender}");
+        let ack = "Rebuilding gateway\u{2026} this may take a moment.";
+        let ack_html = markdown_to_html(ack);
+        if let Ok(msg_id) = ctx
+            .transport
+            .send_message(&room_id_str, ack, &ack_html)
+            .await
+            && let Ok(event_id) = msg_id.parse()
+        {
+            ctx.bot_sent_event_ids.lock().await.insert(event_id);
+        }
+        let config_dir = ctx.services.project_root.clone();
+        let gateway_port: u16 = ctx.gateway_port.unwrap_or(3000);
+        match crate::gateway::rebuild::rebuild_gateway(&config_dir, gateway_port).await {
+            Ok(()) => {
+                // Trampoline is running detached — it kills this gateway and starts
+                // the new one, which will post "gateway X.Y.Z ready" on startup.
+            }
+            Err(e) => {
+                let msg = format!("Gateway rebuild failed: {e}");
+                let html = markdown_to_html(&msg);
+                if let Ok(msg_id) = ctx.transport.send_message(&room_id_str, &msg, &html).await
+                    && let Ok(event_id) = msg_id.parse()
+                {
+                    ctx.bot_sent_event_ids.lock().await.insert(event_id);
+                }
+            }
+        }
+        return;
+    }
+
+    // In gateway mode, intercept "rebuild gateway" before the plain "rebuild"
+    // handler so the trampoline path is used instead of a direct re-exec.
+    if ctx.gateway_port.is_some()
+        && super::super::super::rebuild::extract_rebuild_gateway_command(
+            &user_message,
+            &ctx.services.bot_name,
+            ctx.matrix_user_id.as_str(),
+        )
+        .is_some()
+    {
+        slog!("[matrix-bot] Handling rebuild-gateway command from {sender}");
+        let ack = "Rebuilding gateway… this may take a moment. \
+                   The gateway will announce itself when the new version is ready.";
+        let ack_html = markdown_to_html(ack);
+        if let Ok(msg_id) = ctx
+            .transport
+            .send_message(&room_id_str, ack, &ack_html)
+            .await
+            && let Ok(event_id) = msg_id.parse()
+        {
+            ctx.bot_sent_event_ids.lock().await.insert(event_id);
+        }
+        let port = ctx.gateway_port.unwrap_or(3000);
+        match crate::gateway::rebuild::rebuild_gateway(&ctx.services.project_root, port).await {
+            Ok(()) => {
+                // Trampoline is running — this gateway will be killed shortly.
+                // No further reply needed; the new gateway posts "gateway X.Y.Z ready".
+            }
+            Err(e) => {
+                let msg = format!("Gateway rebuild failed: {e}");
+                let html = markdown_to_html(&msg);
+                if let Ok(msg_id) = ctx.transport.send_message(&room_id_str, &msg, &html).await
+                    && let Ok(event_id) = msg_id.parse()
+                {
+                    ctx.bot_sent_event_ids.lock().await.insert(event_id);
+                }
+            }
+        }
+        return;
+    }
+
     // Check for the rebuild command, which requires async agent and process ops
     // and cannot be handled by the sync command registry.
     if super::super::super::rebuild::extract_rebuild_command(

server/src/chat/transport/matrix/bot/run.rs

@@ -6,7 +6,7 @@ use matrix_sdk::ruma::OwnedRoomId;
 use matrix_sdk::{Client, LoopCtrl, config::SyncSettings};
 use std::collections::{HashMap, HashSet};
 use std::sync::Arc;
-use std::sync::atomic::{AtomicBool, AtomicU64, Ordering};
+use std::sync::atomic::{AtomicBool, AtomicI64, AtomicU64, Ordering};
 use tokio::sync::Mutex as TokioMutex;
 use tokio::sync::{RwLock, watch};
 
@@ -28,7 +28,6 @@ pub async fn run_bot(
     watcher_tx: tokio::sync::broadcast::Sender<crate::io::watcher::WatcherEvent>,
     shutdown_rx: watch::Receiver<Option<crate::rebuild::ShutdownReason>>,
     gateway_active_project: Option<Arc<RwLock<String>>>,
-    gateway_project_urls: std::collections::BTreeMap<String, String>,
     gateway_projects_store: Option<
         Arc<
             RwLock<
@@ -40,6 +39,7 @@ pub async fn run_bot(
     gateway_event_rx: Option<
         tokio::sync::broadcast::Receiver<crate::service::gateway::GatewayStatusEvent>,
     >,
+    gateway_port: Option<u16>,
 ) -> Result<(), String> {
     let project_root = &services.project_root;
     let store_path = project_root.join(".huskies").join("matrix_store");
@@ -182,7 +182,17 @@ pub async fn run_bot(
     let announce_room_ids = target_room_ids.clone();
     // Clone values needed by the gateway notification poller (only used in gateway mode).
     let poller_room_ids: Vec<String> = target_room_ids.iter().map(|r| r.to_string()).collect();
-    let poller_project_urls = gateway_project_urls.clone();
+    let poller_project_urls: std::collections::BTreeMap<String, String> =
+        if let Some(ref store) = gateway_projects_store {
+            store
+                .read()
+                .await
+                .iter()
+                .filter_map(|(name, entry)| entry.url.clone().map(|url| (name.clone(), url)))
+                .collect()
+        } else {
+            std::collections::BTreeMap::new()
+        };
     let poller_poll_interval = config.aggregated_notifications_poll_interval_secs;
     let poller_enabled = config.aggregated_notifications_enabled;
 
@@ -321,11 +331,12 @@ pub async fn run_bot(
         transport: Arc::clone(&transport),
         timer_store,
         gateway_active_project,
-        gateway_project_urls,
         gateway_projects_store,
         handled_incoming_event_ids: Arc::new(TokioMutex::new(super::context::SeenEventIds::new(
             super::context::SEEN_EVENT_IDS_CAP,
         ))),
+        gateway_port,
+        last_matrix_event_ms: Arc::new(AtomicI64::new(chrono::Utc::now().timestamp_millis())),
     };
 
     slog!(
@@ -400,7 +411,17 @@ pub async fn run_bot(
     // bot is online.  This runs once per process start — the sync loop handles
     // reconnects internally so this code is never reached again on a network
     // blip or sync resumption.
-    let announce_msg = format_startup_announcement(&announce_bot_name);
+    //
+    // When started by the trampoline the message is specialised:
+    //   - HUSKIES_TRAMPOLINE_STARTED=1  → "gateway X.Y.Z ready"
+    //   - HUSKIES_TRAMPOLINE_FAILURE=<reason> → rollback failure notice
+    let announce_msg = if let Ok(reason) = std::env::var("HUSKIES_TRAMPOLINE_FAILURE") {
+        super::format::format_gateway_rollback_announcement(&reason)
+    } else if std::env::var("HUSKIES_TRAMPOLINE_STARTED").is_ok() {
+        super::format::format_gateway_ready_announcement()
+    } else {
+        format_startup_announcement(&announce_bot_name)
+    };
     let announce_html = markdown_to_html(&announce_msg);
     slog!("[matrix-bot] Sending startup announcement: {announce_msg}");
     for room_id in &announce_room_ids {
@@ -420,81 +441,164 @@ pub async fn run_bot(
     const INITIAL_BACKOFF_SECS: u64 = 5;
     let backoff = Arc::new(AtomicU64::new(INITIAL_BACKOFF_SECS));
     let was_disconnected = Arc::new(AtomicBool::new(false));
+    // Set to true by the sync callback when a 401/M_UNKNOWN_TOKEN is received.
+    // Checked after the sync loop returns to decide whether to re-login.
+    let needs_relogin = Arc::new(AtomicBool::new(false));
 
     let sync_transport = Arc::clone(&transport);
     let sync_rooms: Vec<String> = announce_room_ids.iter().map(|r| r.to_string()).collect();
     let sync_bot_name = announce_bot_name.clone();
 
-    let backoff_cb = Arc::clone(&backoff);
-    let was_disconnected_cb = Arc::clone(&was_disconnected);
+    // Credentials needed for re-login; captured before any partial moves of `config`.
+    let relogin_username = config.username.clone().unwrap_or_default();
+    let relogin_password = config.password.clone().unwrap_or_default();
 
-    // Use sync_with_result_callback so transient errors (network blips, DNS
-    // hiccups, temporary homeserver outages) are handled in the callback
-    // rather than bubbling up as fatal errors.  Fatal errors (HTTP 401/403)
-    // still terminate the loop and propagate to the caller.
-    client
-        .sync_with_result_callback(SyncSettings::default(), move |result| {
-            let backoff = Arc::clone(&backoff_cb);
-            let was_disconnected = Arc::clone(&was_disconnected_cb);
-            let recovery_transport = Arc::clone(&sync_transport);
-            let recovery_rooms = sync_rooms.clone();
-            let recovery_bot_name = sync_bot_name.clone();
-            async move {
-                match result {
-                    Ok(_) => {
-                        // If we previously lost the connection, announce recovery.
-                        if was_disconnected.swap(false, Ordering::Relaxed) {
-                            backoff.store(INITIAL_BACKOFF_SECS, Ordering::Relaxed);
-                            slog!("[matrix-bot] Reconnected to homeserver — resuming normal operation");
-                            let msg = format!(
-                                "⚡ **{recovery_bot_name}** reconnected to homeserver."
-                            );
-                            let html = format!(
-                                "<p>⚡ <strong>{recovery_bot_name}</strong> reconnected to homeserver.</p>"
-                            );
-                            for room_id in &recovery_rooms {
-                                if let Err(e) = recovery_transport
-                                    .send_message(room_id, &msg, &html)
-                                    .await
-                                {
-                                    slog!(
-                                        "[matrix-bot] Failed to send recovery notification to {room_id}: {e}"
-                                    );
+    // Outer loop: re-enters after a successful re-login to restart the sync.
+    // Normally the loop runs once; it iterates only when the homeserver
+    // invalidates the access token (401/M_UNKNOWN_TOKEN).
+    loop {
+        let backoff_cb = Arc::clone(&backoff);
+        let was_disconnected_cb = Arc::clone(&was_disconnected);
+        let needs_relogin_cb = Arc::clone(&needs_relogin);
+        let iter_sync_transport = Arc::clone(&sync_transport);
+        let iter_sync_rooms = sync_rooms.clone();
+        let iter_sync_bot_name = sync_bot_name.clone();
+
+        // Use sync_with_result_callback so transient errors (network blips, DNS
+        // hiccups, temporary homeserver outages) are handled in the callback
+        // rather than bubbling up as fatal errors.  Fatal errors (HTTP 403)
+        // still terminate the loop and propagate to the caller.
+        // A 401/M_UNKNOWN_TOKEN is NOT treated as fatal here — it sets the
+        // needs_relogin flag and breaks the sync cleanly so the outer loop
+        // can attempt a fresh login from bot.toml credentials.
+        client
+            .sync_with_result_callback(SyncSettings::default(), move |result| {
+                let backoff = Arc::clone(&backoff_cb);
+                let was_disconnected = Arc::clone(&was_disconnected_cb);
+                let needs_relogin = Arc::clone(&needs_relogin_cb);
+                let recovery_transport = Arc::clone(&iter_sync_transport);
+                let recovery_rooms = iter_sync_rooms.clone();
+                let recovery_bot_name = iter_sync_bot_name.clone();
+                async move {
+                    match result {
+                        Ok(_) => {
+                            // If we previously lost the connection, announce recovery.
+                            if was_disconnected.swap(false, Ordering::Relaxed) {
+                                backoff.store(INITIAL_BACKOFF_SECS, Ordering::Relaxed);
+                                slog!("[matrix-bot] Reconnected to homeserver — resuming normal operation");
+                                let msg = format!(
+                                    "⚡ **{recovery_bot_name}** reconnected to homeserver."
+                                );
+                                let html = format!(
+                                    "<p>⚡ <strong>{recovery_bot_name}</strong> reconnected to homeserver.</p>"
+                                );
+                                for room_id in &recovery_rooms {
+                                    if let Err(e) = recovery_transport
+                                        .send_message(room_id, &msg, &html)
+                                        .await
+                                    {
+                                        slog!(
+                                            "[matrix-bot] Failed to send recovery notification to {room_id}: {e}"
+                                        );
+                                    }
                                 }
                             }
+                            Ok(LoopCtrl::Continue)
+                        }
+                        Err(e) if is_unknown_token_error(&e) => {
+                            // 401/M_UNKNOWN_TOKEN: the homeserver rotated or
+                            // invalidated our access token. Break cleanly so
+                            // the outer loop can re-login from bot.toml.
+                            slog!("[matrix-bot] Sync got 401/M_UNKNOWN_TOKEN — queuing re-login");
+                            needs_relogin.store(true, Ordering::Relaxed);
+                            Ok(LoopCtrl::Break)
+                        }
+                        Err(e) if is_fatal_sync_error(&e) => Err(e),
+                        Err(e) => {
+                            // Transient error: log, back off, and let the stream retry.
+                            let delay = backoff.load(Ordering::Relaxed);
+                            slog!("[matrix-bot] Sync warning (retrying in {delay}s): {e}");
+                            was_disconnected.store(true, Ordering::Relaxed);
+                            tokio::time::sleep(std::time::Duration::from_secs(delay)).await;
+                            let new_delay = (delay * 2).min(MAX_BACKOFF_SECS);
+                            backoff.store(new_delay, Ordering::Relaxed);
+                            Ok(LoopCtrl::Continue)
                         }
-                        Ok(LoopCtrl::Continue)
-                    }
-                    Err(e) if is_fatal_sync_error(&e) => Err(e),
-                    Err(e) => {
-                        // Transient error: log, back off, and let the stream retry.
-                        let delay = backoff.load(Ordering::Relaxed);
-                        slog!("[matrix-bot] Sync warning (retrying in {delay}s): {e}");
-                        was_disconnected.store(true, Ordering::Relaxed);
-                        tokio::time::sleep(std::time::Duration::from_secs(delay)).await;
-                        let new_delay = (delay * 2).min(MAX_BACKOFF_SECS);
-                        backoff.store(new_delay, Ordering::Relaxed);
-                        Ok(LoopCtrl::Continue)
                     }
                 }
+            })
+            .await
+            .map_err(|e| format!("Matrix sync error: {e}"))?;
+
+        if !needs_relogin.swap(false, Ordering::Relaxed) {
+            // Normal clean exit — not a re-login scenario.
+            break;
+        }
+
+        // --- Re-login flow: access token was invalidated by the homeserver ---
+        // The SQLite store at `.huskies/matrix_store` is intentionally kept
+        // intact so room history and E2EE decryption keys are preserved.
+        // Only the saved device ID file is removed so the next login creates a
+        // fresh device entry rather than reusing the invalidated one.
+        slog!("[matrix-bot] Access token invalidated — re-logging in from bot.toml credentials");
+        let _ = std::fs::remove_file(&device_id_path);
+
+        loop {
+            match client
+                .matrix_auth()
+                .login_username(&relogin_username, &relogin_password)
+                .initial_device_display_name("Huskies Bot")
+                .await
+            {
+                Ok(response) => {
+                    let _ = std::fs::write(&device_id_path, &response.device_id);
+                    slog!(
+                        "[matrix-bot] Re-login successful; new device: {}",
+                        response.device_id
+                    );
+                    let msg =
+                        "[matrix-bot] Token rotated by homeserver; re-logged in as new device";
+                    let html = "<p>[matrix-bot] Token rotated by homeserver; re-logged in as new device</p>";
+                    for room_id in &sync_rooms {
+                        if let Err(e) = sync_transport.send_message(room_id, msg, html).await {
+                            slog!("[matrix-bot] Failed to send re-login notice to {room_id}: {e}");
+                        }
+                    }
+                    break;
+                }
+                Err(e) => {
+                    // Wrong password, homeserver down, etc. — log and keep
+                    // retrying every 30 s instead of dying fatally.
+                    slog!("[matrix-bot] Re-login failed: {e} — retrying in 30s");
+                    tokio::time::sleep(std::time::Duration::from_secs(30)).await;
+                }
             }
-        })
-        .await
-        .map_err(|e| format!("Matrix sync error: {e}"))?;
+        }
+        // Outer loop continues: restarts the Matrix sync with the new token.
+    }
 
     Ok(())
 }
 
-/// Returns `true` for errors that indicate the bot's session is permanently
-/// invalid (HTTP 401 Unauthorized or 403 Forbidden).  All other errors —
-/// network failures, timeouts, transient 5xx responses — are considered
-/// recoverable and should be retried with exponential back-off.
+/// Returns `true` for errors that indicate the bot is permanently forbidden
+/// from the homeserver (HTTP 403).  All other errors — network failures,
+/// timeouts, transient 5xx responses — are considered recoverable.
+///
+/// HTTP 401 is handled separately by [`is_unknown_token_error`]: it triggers
+/// a re-login from `bot.toml` credentials rather than a fatal shutdown.
 fn is_fatal_sync_error(e: &matrix_sdk::Error) -> bool {
     e.as_client_api_error()
-        .map(|api_err| {
-            let code = api_err.status_code.as_u16();
-            code == 401 || code == 403
-        })
+        .map(|api_err| api_err.status_code.as_u16() == 403)
+        .unwrap_or(false)
+}
+
+/// Returns `true` when the homeserver returned 401 / M_UNKNOWN_TOKEN,
+/// indicating that the current access token has been invalidated.
+/// The bot should respond by re-logging in from `bot.toml` credentials
+/// rather than shutting down permanently.
+fn is_unknown_token_error(e: &matrix_sdk::Error) -> bool {
+    e.as_client_api_error()
+        .map(|api_err| api_err.status_code.as_u16() == 401)
         .unwrap_or(false)
 }
 
@@ -511,6 +615,14 @@ mod tests {
         assert!(!is_fatal_sync_error(&e));
     }
 
+    /// An I/O error must NOT be mistaken for an unknown-token error.
+    #[test]
+    fn io_error_is_not_unknown_token() {
+        let e: matrix_sdk::Error =
+            std::io::Error::new(std::io::ErrorKind::ConnectionRefused, "connection refused").into();
+        assert!(!is_unknown_token_error(&e));
+    }
+
     /// Exponential back-off must clamp at MAX_BACKOFF_SECS (300 s) regardless
     /// of how many consecutive failures occur.
     #[test]
@@ -542,4 +654,40 @@ mod tests {
         assert_eq!(steps[2], 20);
         assert_eq!(steps[3], 40);
     }
+
+    /// 401 must NOT be classified as fatal: the bot re-logs in rather than dying.
+    /// is_fatal_sync_error must return false for 401 so the re-login path runs.
+    #[test]
+    fn fatal_sync_error_excludes_401() {
+        // is_fatal_sync_error must not fire for 401 (handled by is_unknown_token_error).
+        // We verify the logic: only 403 is fatal in the sync loop.
+        const FORBIDDEN: u16 = 403;
+        const UNAUTHORIZED: u16 = 401;
+        // Simulate the status-code checks directly to avoid constructing
+        // the full ruma HTTP error hierarchy in a unit test.
+        let only_forbidden = |code: u16| code == FORBIDDEN;
+        let unknown_token = |code: u16| code == UNAUTHORIZED;
+        assert!(only_forbidden(FORBIDDEN), "403 must be fatal");
+        assert!(!only_forbidden(UNAUTHORIZED), "401 must NOT be fatal");
+        assert!(unknown_token(UNAUTHORIZED), "401 must trigger re-login");
+        assert!(!unknown_token(FORBIDDEN), "403 must NOT trigger re-login");
+    }
+
+    /// Re-login retry interval must be exactly 30 s.
+    ///
+    /// This protects against accidental changes to the constant: too short
+    /// would hammer the homeserver; too long would delay recovery past the
+    /// 10 s target stated in the story acceptance criteria.
+    #[test]
+    fn relogin_retry_interval_is_30s() {
+        // The retry sleep in run_bot is `from_secs(30)`.  Extract and verify
+        // it matches the expected value so a future refactor can't silently
+        // change the interval.
+        let interval = std::time::Duration::from_secs(30);
+        assert_eq!(
+            interval.as_secs(),
+            30,
+            "re-login retry interval must be 30 s"
+        );
+    }
 }

server/src/chat/transport/matrix/health.rs

@@ -0,0 +1,666 @@
+//! `health` chat command — surface gateway, sled, matrix, creds, and build-hash status.
+//!
+//! Runs one check per subsystem concurrently (each with a 5-second timeout) and
+//! returns a compact report: one line per subsystem with PASS / WARN / FAIL and a
+//! remediation hint on every non-PASS row.  Output is capped at 20 lines; when
+//! more lines would be produced, the oldest WARN rows are dropped first.
+
+use crate::chat::transport::matrix::bot::context::BotContext;
+use std::collections::BTreeMap;
+use std::sync::atomic::Ordering;
+use std::time::Duration;
+use tokio::time::timeout;
+
+// ── Status ─────────────────────────────────────────────────────────────────────
+
+/// Health status for a single subsystem.
+#[derive(Debug, Clone, PartialEq)]
+enum Status {
+    /// Subsystem is operating normally.
+    Pass,
+    /// Subsystem is degraded but not fully broken.
+    Warn,
+    /// Subsystem has failed and needs intervention.
+    Fail,
+}
+
+// ── HealthLine ─────────────────────────────────────────────────────────────────
+
+/// One output row from the health check.
+#[derive(Debug, Clone)]
+struct HealthLine {
+    subsystem: String,
+    status: Status,
+    /// Short description of why the check is non-PASS.
+    detail: Option<String>,
+    /// Remediation hint shown after " — " on WARN/FAIL rows.
+    hint: Option<String>,
+}
+
+impl HealthLine {
+    fn pass(subsystem: impl Into<String>) -> Self {
+        Self {
+            subsystem: subsystem.into(),
+            status: Status::Pass,
+            detail: None,
+            hint: None,
+        }
+    }
+
+    fn warn(
+        subsystem: impl Into<String>,
+        detail: impl Into<String>,
+        hint: impl Into<String>,
+    ) -> Self {
+        Self {
+            subsystem: subsystem.into(),
+            status: Status::Warn,
+            detail: Some(detail.into()),
+            hint: Some(hint.into()),
+        }
+    }
+
+    fn fail(
+        subsystem: impl Into<String>,
+        detail: impl Into<String>,
+        hint: impl Into<String>,
+    ) -> Self {
+        Self {
+            subsystem: subsystem.into(),
+            status: Status::Fail,
+            detail: Some(detail.into()),
+            hint: Some(hint.into()),
+        }
+    }
+
+    /// Format as a single Markdown-friendly line.
+    fn format(&self) -> String {
+        let status = match self.status {
+            Status::Pass => "PASS",
+            Status::Warn => "WARN",
+            Status::Fail => "FAIL",
+        };
+        match (&self.detail, &self.hint) {
+            (Some(d), Some(h)) => format!("{} {}: {} — {}", self.subsystem, status, d, h),
+            (Some(d), None) => format!("{} {}: {}", self.subsystem, status, d),
+            (None, None) => format!("{} {}", self.subsystem, status),
+            (None, Some(h)) => format!("{} {}: — {}", self.subsystem, status, h),
+        }
+    }
+}
+
+// ── Truncation ────────────────────────────────────────────────────────────────
+
+/// Maximum number of output lines before truncation.
+const MAX_LINES: usize = 20;
+
+/// Truncate to ≤ MAX_LINES by removing the oldest (first in order) WARN rows.
+fn truncate_lines(mut lines: Vec<HealthLine>) -> Vec<HealthLine> {
+    while lines.len() > MAX_LINES {
+        if let Some(pos) = lines.iter().position(|l| l.status == Status::Warn) {
+            lines.remove(pos);
+        } else {
+            break;
+        }
+    }
+    lines
+}
+
+// ── Individual checks ────────────────────────────────────────────────────────
+
+/// Check the `perm_rx` receiver — PASS when the permission listener holds the lock,
+/// FAIL when no task is holding it (listener has died or was never started).
+fn check_perm_rx(ctx: &BotContext) -> HealthLine {
+    if ctx.services.perm_rx.try_lock().is_err() {
+        HealthLine::pass("perm_rx")
+    } else {
+        HealthLine::fail("perm_rx", "listener not holding lock", "restart bot")
+    }
+}
+
+/// Check the Matrix sync loop by measuring the age of the last received event.
+///
+/// WARN after 60 s of silence, FAIL after 120 s.  The timestamp is updated by
+/// `on_room_message` on every incoming event so receiving the health command
+/// itself resets the clock.
+fn check_matrix_sync(ctx: &BotContext) -> HealthLine {
+    let last_ms = ctx.last_matrix_event_ms.load(Ordering::Relaxed);
+    let age_secs = (chrono::Utc::now().timestamp_millis() - last_ms).max(0) / 1000;
+
+    if age_secs < 60 {
+        HealthLine::pass("matrix-sync")
+    } else if age_secs < 120 {
+        HealthLine::warn(
+            "matrix-sync",
+            format!("no events in {age_secs}s"),
+            "check sync loop — may be a quiet room",
+        )
+    } else {
+        HealthLine::fail(
+            "matrix-sync",
+            format!("no events in {age_secs}s"),
+            "sync loop may be dead — restart bot",
+        )
+    }
+}
+
+/// Check LLM credentials (`~/.claude/.credentials.json`).
+///
+/// FAIL if the file is missing or unreadable, FAIL if the access token is
+/// expired, WARN if it expires within the next 7 days.
+fn check_creds() -> HealthLine {
+    match crate::llm::oauth::read_credentials() {
+        Err(e) => HealthLine::fail("creds", e, "run `claude login`"),
+        Ok(creds) => {
+            let now_secs = std::time::SystemTime::now()
+                .duration_since(std::time::UNIX_EPOCH)
+                .unwrap_or_default()
+                .as_secs();
+            let expires_at = creds.claude_ai_oauth.expires_at;
+            if expires_at < now_secs {
+                HealthLine::fail("creds", "token expired", "run `claude login` to refresh")
+            } else {
+                let days_left = (expires_at - now_secs) / 86400;
+                if days_left < 7 {
+                    HealthLine::warn(
+                        "creds",
+                        format!("token expires in {days_left}d"),
+                        "run `claude login` to refresh",
+                    )
+                } else {
+                    HealthLine::pass("creds")
+                }
+            }
+        }
+    }
+}
+
+/// Compare the compile-time build hash against the current HEAD of the workspace.
+///
+/// WARN when master has advanced past the running binary's commit (a rebuild is
+/// available but not urgent).  PASS when hashes match or HEAD cannot be read.
+async fn check_build_hash(project_root: &std::path::Path) -> HealthLine {
+    let running = option_env!("BUILD_GIT_HASH").unwrap_or("unknown");
+
+    // Read current HEAD from git (non-blocking, run in a spawn_blocking call).
+    let repo_root = project_root.to_path_buf();
+    let head = tokio::task::spawn_blocking(move || {
+        std::process::Command::new("git")
+            .args(["rev-parse", "--short", "HEAD"])
+            .current_dir(&repo_root)
+            .output()
+            .ok()
+            .filter(|o| o.status.success())
+            .and_then(|o| String::from_utf8(o.stdout).ok())
+            .map(|s| s.trim().to_string())
+    })
+    .await
+    .unwrap_or(None);
+
+    match head {
+        None => HealthLine::pass("build-hash"),
+        Some(ref head_hash) => {
+            if running == "unknown" || head_hash == running {
+                HealthLine::pass("build-hash")
+            } else {
+                HealthLine::warn(
+                    "build-hash",
+                    format!("running {running}, HEAD is {head_hash}"),
+                    "run `rebuild` to update",
+                )
+            }
+        }
+    }
+}
+
+/// Check each registered sled's `/health` endpoint with a 5-second timeout.
+///
+/// Returns one [`HealthLine`] per sled.  PASS when the sled responds with HTTP
+/// 2xx; FAIL when the request times out or returns an error status.
+async fn check_sleds(
+    store: &tokio::sync::RwLock<BTreeMap<String, crate::service::gateway::config::ProjectEntry>>,
+) -> Vec<HealthLine> {
+    let entries: Vec<(String, Option<String>)> = store
+        .read()
+        .await
+        .iter()
+        .map(|(n, e)| (n.clone(), e.url.clone()))
+        .collect();
+
+    if entries.is_empty() {
+        return vec![HealthLine::warn(
+            "sled",
+            "no sleds registered",
+            "add projects to projects.toml",
+        )];
+    }
+
+    let client = reqwest::Client::new();
+    let mut lines = Vec::new();
+
+    for (name, url_opt) in entries {
+        let subsystem = format!("sled:{name}");
+        let line = match url_opt {
+            None => HealthLine::warn(subsystem, "no URL configured", "set url in projects.toml"),
+            Some(url) => {
+                let health_url = format!("{}/health", url.trim_end_matches('/'));
+                let result = timeout(Duration::from_secs(5), client.get(&health_url).send()).await;
+                match result {
+                    Err(_) => {
+                        HealthLine::fail(subsystem, "timed out", "check container is running")
+                    }
+                    Ok(Err(e)) => HealthLine::fail(
+                        subsystem,
+                        format!("unreachable: {}", short_error(&e.to_string())),
+                        "check container is running",
+                    ),
+                    Ok(Ok(resp)) if resp.status().is_success() => HealthLine::pass(subsystem),
+                    Ok(Ok(resp)) => HealthLine::fail(
+                        subsystem,
+                        format!("HTTP {}", resp.status().as_u16()),
+                        "check container logs",
+                    ),
+                }
+            }
+        };
+        lines.push(line);
+    }
+
+    lines
+}
+
+/// Check the gateway process: pidfile validity and (on macOS) binary codesign.
+///
+/// PASS when our PID is recorded in the pidfile.  On macOS, also verifies that
+/// `~/bin/huskies-bin` has a valid ad-hoc signature; FAIL with a `script/local-release`
+/// hint when it does not.
+fn check_gateway_process() -> HealthLine {
+    // Verify that the pidfile records our PID (i.e. this IS the live gateway).
+    let pidfile_ok = check_pidfile_matches_self();
+
+    // On macOS, verify the installed binary is codesigned.
+    #[cfg(target_os = "macos")]
+    {
+        if !check_codesign_macos() {
+            return HealthLine::fail(
+                "gateway-process",
+                "codesign invalid",
+                "run `script/local-release`",
+            );
+        }
+    }
+
+    if !pidfile_ok {
+        return HealthLine::warn(
+            "gateway-process",
+            "pidfile missing or stale",
+            "restart gateway with --gateway flag",
+        );
+    }
+
+    HealthLine::pass("gateway-process")
+}
+
+/// Return `true` when `$HOME/.huskies/gateway.pid` exists and contains our PID.
+fn check_pidfile_matches_self() -> bool {
+    let home = homedir::my_home().ok().flatten();
+    let home = match home {
+        Some(h) => h,
+        None => return false,
+    };
+    let path = home.join(".huskies").join("gateway.pid");
+    let content = std::fs::read_to_string(&path).unwrap_or_default();
+    content.trim().parse::<u32>().unwrap_or(0) == std::process::id()
+}
+
+/// On macOS, return `true` when `~/bin/huskies-bin` passes `codesign --verify`.
+///
+/// Falls back to the current executable when `~/bin/huskies-bin` does not exist.
+/// Returns `true` (assume ok) if the `codesign` tool is unavailable.
+#[cfg(target_os = "macos")]
+fn check_codesign_macos() -> bool {
+    let target = if let Ok(home) = std::env::var("HOME") {
+        let installed = std::path::PathBuf::from(home)
+            .join("bin")
+            .join("huskies-bin");
+        if installed.exists() {
+            installed
+        } else {
+            match std::env::current_exe() {
+                Ok(p) => p,
+                Err(_) => return true,
+            }
+        }
+    } else {
+        match std::env::current_exe() {
+            Ok(p) => p,
+            Err(_) => return true,
+        }
+    };
+
+    std::process::Command::new("codesign")
+        .args(["--verify", "--quiet", target.to_str().unwrap_or("")])
+        .output()
+        .map(|o| o.status.success())
+        .unwrap_or(true)
+}
+
+// ── Entry point ────────────────────────────────────────────────────────────────
+
+/// Run all health checks and return a formatted Markdown report (≤ 20 lines).
+///
+/// Gateway-specific checks (gateway-process, per-sled probes) are included
+/// only when running in gateway mode.  All other checks run in every mode.
+pub async fn run_health_check(ctx: &BotContext) -> String {
+    let mut lines: Vec<HealthLine> = Vec::new();
+
+    // Gateway-only checks
+    if ctx.is_gateway() {
+        lines.push(check_gateway_process());
+        if let Some(ref store) = ctx.gateway_projects_store {
+            lines.extend(check_sleds(store).await);
+        }
+    }
+
+    // Shared checks — run concurrently where possible.
+    let perm_line = check_perm_rx(ctx);
+    let sync_line = check_matrix_sync(ctx);
+    let creds_line = check_creds();
+    let hash_line = check_build_hash(&ctx.services.project_root).await;
+
+    lines.push(perm_line);
+    lines.push(sync_line);
+    lines.push(creds_line);
+    lines.push(hash_line);
+
+    let lines = truncate_lines(lines);
+    lines
+        .iter()
+        .map(|l| l.format())
+        .collect::<Vec<_>>()
+        .join("\n")
+}
+
+// ── Utilities ────────────────────────────────────────────────────────────────
+
+/// Shorten a long error string to the first 60 characters for compact display.
+fn short_error(s: &str) -> String {
+    s.chars().take(60).collect()
+}
+
+// ── Tests ─────────────────────────────────────────────────────────────────────
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    // -- HealthLine formatting ------------------------------------------------
+
+    #[test]
+    fn pass_line_formats_without_detail() {
+        let line = HealthLine::pass("perm_rx");
+        assert_eq!(line.format(), "perm_rx PASS");
+    }
+
+    #[test]
+    fn fail_line_formats_with_detail_and_hint() {
+        let line = HealthLine::fail(
+            "gateway-process",
+            "codesign invalid",
+            "run script/local-release",
+        );
+        assert_eq!(
+            line.format(),
+            "gateway-process FAIL: codesign invalid — run script/local-release"
+        );
+    }
+
+    #[test]
+    fn warn_line_formats_with_detail_and_hint() {
+        let line = HealthLine::warn("build-hash", "running abc, HEAD is def", "run rebuild");
+        assert_eq!(
+            line.format(),
+            "build-hash WARN: running abc, HEAD is def — run rebuild"
+        );
+    }
+
+    // -- Truncation -----------------------------------------------------------
+
+    #[test]
+    fn truncate_drops_oldest_warn_first() {
+        let mut lines: Vec<HealthLine> = (0..22)
+            .map(|i| {
+                if i % 3 == 0 {
+                    HealthLine::fail(format!("sled:{i}"), "down", "fix it")
+                } else {
+                    HealthLine::warn(format!("check:{i}"), "slow", "investigate")
+                }
+            })
+            .collect();
+
+        // Manually insert a known WARN at position 0 and a FAIL at position 1
+        lines.insert(0, HealthLine::warn("oldest-warn", "stale", "restart"));
+        lines.insert(1, HealthLine::fail("important-fail", "broken", "fix"));
+
+        let result = truncate_lines(lines.clone());
+        assert!(
+            result.len() <= MAX_LINES,
+            "output must be ≤ {MAX_LINES} lines"
+        );
+
+        // FAILs must be preserved.
+        let fail_count = result.iter().filter(|l| l.status == Status::Fail).count();
+        let orig_fail_count = lines.iter().filter(|l| l.status == Status::Fail).count();
+        assert_eq!(
+            fail_count,
+            orig_fail_count.min(MAX_LINES),
+            "all FAIL lines must be kept when they fit"
+        );
+    }
+
+    #[test]
+    fn truncate_noop_when_under_limit() {
+        let lines: Vec<HealthLine> = (0..5).map(|i| HealthLine::pass(format!("s{i}"))).collect();
+        let result = truncate_lines(lines.clone());
+        assert_eq!(result.len(), 5);
+    }
+
+    #[test]
+    fn truncate_stops_at_fails_when_no_warns_left() {
+        // 25 FAIL lines — nothing to drop; output is clamped at MAX_LINES.
+        let lines: Vec<HealthLine> = (0..25)
+            .map(|i| HealthLine::fail(format!("s{i}"), "broken", "fix"))
+            .collect();
+        let result = truncate_lines(lines);
+        // When only FAILs are present, truncation stops because no WARNs can be removed.
+        assert_eq!(result.len(), 25, "FAILs are never dropped by truncation");
+    }
+
+    // -- perm_rx check --------------------------------------------------------
+
+    #[tokio::test]
+    async fn perm_rx_pass_when_locked() {
+        use crate::services::Services;
+        use std::sync::Arc;
+        use tokio::sync::Mutex as TokioMutex;
+
+        let (perm_tx, perm_rx) = tokio::sync::mpsc::unbounded_channel();
+        let perm_rx_arc = Arc::new(TokioMutex::new(perm_rx));
+
+        // Acquire the lock to simulate the permission listener holding it.
+        let _guard = perm_rx_arc.try_lock().unwrap();
+
+        // Build a minimal services bundle referencing our locked perm_rx.
+        let services = Arc::new(Services {
+            project_root: std::path::PathBuf::from("/tmp"),
+            agents: Arc::new(crate::agents::AgentPool::new_test(3000)),
+            bot_name: "test".to_string(),
+            bot_user_id: "@bot:test".to_string(),
+            ambient_rooms: Arc::new(std::sync::Mutex::new(std::collections::HashSet::new())),
+            perm_rx: Arc::clone(&perm_rx_arc),
+            pending_perm_replies: Arc::new(TokioMutex::new(std::collections::HashMap::new())),
+            permission_timeout_secs: 120,
+            status: Arc::new(crate::service::status::StatusBroadcaster::new()),
+            chat_dispatcher: Arc::new(crate::chat::dispatcher::ChatDispatcher::new(1_500)),
+        });
+
+        // Build a minimal BotContext just to pass services.
+        let ctx = make_test_ctx(services);
+
+        let line = check_perm_rx(&ctx);
+        assert_eq!(
+            line.status,
+            Status::Pass,
+            "perm_rx should PASS when a task holds the lock"
+        );
+
+        drop(perm_tx); // suppress unused warning
+    }
+
+    #[tokio::test]
+    async fn perm_rx_fail_when_unlocked() {
+        use crate::services::Services;
+        use std::sync::Arc;
+        use tokio::sync::Mutex as TokioMutex;
+
+        let (_perm_tx, perm_rx) = tokio::sync::mpsc::unbounded_channel();
+        let perm_rx_arc = Arc::new(TokioMutex::new(perm_rx));
+        // Lock is NOT held by anyone.
+
+        let services = Arc::new(Services {
+            project_root: std::path::PathBuf::from("/tmp"),
+            agents: Arc::new(crate::agents::AgentPool::new_test(3000)),
+            bot_name: "test".to_string(),
+            bot_user_id: "@bot:test".to_string(),
+            ambient_rooms: Arc::new(std::sync::Mutex::new(std::collections::HashSet::new())),
+            perm_rx: Arc::clone(&perm_rx_arc),
+            pending_perm_replies: Arc::new(TokioMutex::new(std::collections::HashMap::new())),
+            permission_timeout_secs: 120,
+            status: Arc::new(crate::service::status::StatusBroadcaster::new()),
+            chat_dispatcher: Arc::new(crate::chat::dispatcher::ChatDispatcher::new(1_500)),
+        });
+
+        let ctx = make_test_ctx(services);
+
+        let line = check_perm_rx(&ctx);
+        assert_eq!(
+            line.status,
+            Status::Fail,
+            "perm_rx should FAIL when no task holds the lock"
+        );
+    }
+
+    // -- matrix-sync check ----------------------------------------------------
+
+    #[tokio::test]
+    async fn matrix_sync_pass_when_recent() {
+        let services = crate::services::Services::new_test(
+            std::path::PathBuf::from("/tmp"),
+            "bot".to_string(),
+        );
+        let ctx = make_test_ctx(services);
+        // Set last event to just now.
+        ctx.last_matrix_event_ms
+            .store(chrono::Utc::now().timestamp_millis(), Ordering::Relaxed);
+        let line = check_matrix_sync(&ctx);
+        assert_eq!(line.status, Status::Pass);
+    }
+
+    #[tokio::test]
+    async fn matrix_sync_fail_when_stale() {
+        let services = crate::services::Services::new_test(
+            std::path::PathBuf::from("/tmp"),
+            "bot".to_string(),
+        );
+        let ctx = make_test_ctx(services);
+        // Simulate 200 seconds of silence.
+        let old_ms = chrono::Utc::now().timestamp_millis() - 200_000;
+        ctx.last_matrix_event_ms.store(old_ms, Ordering::Relaxed);
+        let line = check_matrix_sync(&ctx);
+        assert_eq!(line.status, Status::Fail);
+        assert!(
+            line.detail.as_deref().unwrap_or("").contains("200s")
+                || line.detail.as_deref().unwrap_or("").contains("s"),
+            "detail should mention age in seconds"
+        );
+    }
+
+    // -- creds check ----------------------------------------------------------
+
+    #[test]
+    fn creds_fail_when_file_missing() {
+        // In the test environment there is unlikely to be a ~/.claude/.credentials.json
+        // with a valid non-expired token, so we just confirm the function returns a
+        // HealthLine without panicking.
+        let line = check_creds();
+        // We don't assert a specific status — the check should not panic.
+        let _ = line.format();
+    }
+
+    // -- build_hash check -----------------------------------------------------
+
+    #[tokio::test]
+    async fn build_hash_pass_when_git_unavailable() {
+        // In a test environment without a git repo at /tmp/nonexistent, the check
+        // should gracefully return PASS rather than panicking.
+        let line = check_build_hash(std::path::Path::new("/tmp/nonexistent")).await;
+        // Should either PASS or produce a sensible result — must not panic.
+        let _ = line.format();
+    }
+
+    // -- health command registration ------------------------------------------
+
+    #[test]
+    fn health_command_registered_in_commands() {
+        let cmds = crate::chat::commands::commands();
+        assert!(
+            cmds.iter().any(|c| c.name == "health"),
+            "health must be registered in commands()"
+        );
+    }
+
+    #[test]
+    fn health_command_has_description() {
+        let cmds = crate::chat::commands::commands();
+        let cmd = cmds.iter().find(|c| c.name == "health").unwrap();
+        assert!(!cmd.description.is_empty());
+    }
+
+    // -- Helper ---------------------------------------------------------------
+
+    /// Build a minimal `BotContext` for testing purposes.
+    fn make_test_ctx(services: std::sync::Arc<crate::services::Services>) -> BotContext {
+        use std::collections::HashSet;
+        use std::sync::Arc;
+        use std::sync::atomic::AtomicI64;
+        use tokio::sync::Mutex as TokioMutex;
+
+        BotContext {
+            services,
+            matrix_user_id: "@bot:example.com".parse().unwrap(),
+            target_room_ids: vec![],
+            allowed_users: vec![],
+            history: Arc::new(TokioMutex::new(std::collections::HashMap::new())),
+            history_size: 20,
+            bot_sent_event_ids: Arc::new(TokioMutex::new(HashSet::new())),
+            htop_sessions: Arc::new(TokioMutex::new(std::collections::HashMap::new())),
+            transport: Arc::new(crate::chat::transport::whatsapp::WhatsAppTransport::new(
+                "test-phone".to_string(),
+                "test-token".to_string(),
+                "pipeline_notification".to_string(),
+            )),
+            timer_store: Arc::new(crate::service::timer::TimerStore::load(
+                std::path::PathBuf::from("/tmp/timers-health.json"),
+            )),
+            gateway_active_project: None,
+            gateway_projects_store: None,
+            handled_incoming_event_ids: Arc::new(TokioMutex::new(
+                crate::chat::transport::matrix::bot::context::SeenEventIds::new(
+                    crate::chat::transport::matrix::bot::context::SEEN_EVENT_IDS_CAP,
+                ),
+            )),
+            gateway_port: None,
+            last_matrix_event_ms: Arc::new(AtomicI64::new(chrono::Utc::now().timestamp_millis())),
+        }
+    }
+}

server/src/chat/transport/matrix/mod.rs

@@ -25,16 +25,22 @@ pub mod commands;
 pub(crate) mod config;
 /// Story deletion command — handles `!delete` bot commands to remove work items.
 pub mod delete;
+/// `health` chat command — surface gateway, sled, matrix, creds, and build-hash status.
+pub mod health;
 /// htop-style agent monitor command — renders a live process table in Matrix.
 pub mod htop;
 /// `new project <name>` chat command — Phase 1 gateway project bootstrap.
 pub mod new_project;
+/// `project-rebuild <name>` chat command — rebuild Docker image, swap container, preserve state.
+pub mod project_rebuild;
 /// Rebuild command — triggers a server rebuild/restart via a bot command.
 pub mod rebuild;
 /// Reset command — handles `!reset` bot commands to restart the server state.
 pub mod reset;
 /// rmtree command — handles `!rmtree` bot commands to remove worktrees.
 pub mod rmtree;
+/// `upgrade [<project>]` gateway chat command — streaming per-sled binary upgrade.
+pub mod sled_upgrade;
 /// Start command — handles `!start` bot commands to launch agents on stories.
 pub mod start;
 /// Matrix `ChatTransport` implementation wrapping the Matrix SDK client.
@@ -81,7 +87,6 @@ pub fn spawn_bot(
     services: Arc<Services>,
     shutdown_rx: watch::Receiver<Option<ShutdownReason>>,
     gateway_active_project: Option<Arc<RwLock<String>>>,
-    gateway_project_urls: std::collections::BTreeMap<String, String>,
     gateway_projects_store: Option<
         Arc<
             RwLock<
@@ -93,6 +98,7 @@ pub fn spawn_bot(
     gateway_event_rx: Option<
         tokio::sync::broadcast::Receiver<crate::service::gateway::GatewayStatusEvent>,
     >,
+    gateway_port: Option<u16>,
 ) -> Option<tokio::task::AbortHandle> {
     let config = match BotConfig::load(project_root) {
         Some(c) => c,
@@ -128,10 +134,10 @@ pub fn spawn_bot(
             watcher_tx,
             shutdown_rx,
             gateway_active_project,
-            gateway_project_urls,
             gateway_projects_store,
             timer_store,
             gateway_event_rx,
+            gateway_port,
         )
         .await
         {

server/src/chat/transport/matrix/project_rebuild.rs

@@ -0,0 +1,605 @@
+//! `project-rebuild <name>` chat command — rebuild Docker image, swap container, preserve state.
+//!
+//! Usage: `{bot} project-rebuild <name> [--timeout <secs>] [--force]`
+//!
+//! Steps performed:
+//! 1. Validate the project exists and has a `host_path` configured.
+//! 2. Check for in-flight coder/merge work (active `claude` processes in the container).
+//!    Wait up to `--timeout` seconds for them to exit.  Refuse if still active.
+//! 3. Build a new Docker image from the project's `Dockerfile.fragment` (if present).
+//! 4. Stop and remove the old container.
+//! 5. Start a new container from the fresh image, mounting the same host volume so
+//!    `pipeline.db` and all CRDT state survive untouched.
+//! 6. Re-register the project in the gateway (same URL — port is preserved).
+//!
+//! On success the reply names the new image hash and the new container ID.
+//! On failure the reply names the step that failed and the recovery path.
+
+use crate::service::gateway::config::ProjectEntry;
+use crate::service::gateway::io::save_config;
+use std::collections::BTreeMap;
+use std::path::Path;
+use std::sync::Arc;
+use tokio::sync::RwLock;
+
+/// Default seconds to wait for in-flight work to drain before refusing.
+const DEFAULT_DRAIN_TIMEOUT_SECS: u64 = 60;
+
+/// A parsed `project-rebuild <name>` command.
+#[derive(Debug, PartialEq)]
+pub struct ProjectRebuildCommand {
+    /// Name of the project to rebuild.
+    pub name: String,
+    /// Seconds to wait for agents to drain (0 = skip check).
+    pub drain_timeout_secs: u64,
+    /// If `true`, skip the drain check entirely.
+    pub force: bool,
+}
+
+/// Parse a `project-rebuild <name> [--timeout <secs>] [--force]` command from a raw
+/// Matrix message body.
+///
+/// Strips the bot mention prefix and checks for the `project-rebuild` keyword.
+/// Returns `None` when the message is not a project-rebuild command.
+pub fn extract_project_rebuild_command(
+    message: &str,
+    bot_name: &str,
+    bot_user_id: &str,
+) -> Option<ProjectRebuildCommand> {
+    let stripped = crate::chat::util::strip_bot_mention(message, bot_name, bot_user_id);
+    let trimmed = stripped
+        .trim()
+        .trim_start_matches(|c: char| !c.is_alphanumeric());
+
+    let rest = if let Some(r) = trimmed.strip_prefix("project-rebuild") {
+        r.trim()
+    } else {
+        return None;
+    };
+
+    let mut parts = rest.split_whitespace();
+    let name = match parts.next() {
+        Some(n) if !n.starts_with("--") => n.to_string(),
+        _ => return None,
+    };
+
+    let mut drain_timeout_secs = DEFAULT_DRAIN_TIMEOUT_SECS;
+    let mut force = false;
+
+    let remaining: Vec<&str> = parts.collect();
+    let mut i = 0;
+    while i < remaining.len() {
+        match remaining[i] {
+            "--timeout" if i + 1 < remaining.len() => {
+                drain_timeout_secs = remaining[i + 1]
+                    .parse()
+                    .unwrap_or(DEFAULT_DRAIN_TIMEOUT_SECS);
+                i += 2;
+            }
+            "--force" => {
+                force = true;
+                i += 1;
+            }
+            _ => {
+                i += 1;
+            }
+        }
+    }
+
+    Some(ProjectRebuildCommand {
+        name,
+        drain_timeout_secs,
+        force,
+    })
+}
+
+/// Rebuild a project's Docker image, swap the container, and preserve all state.
+///
+/// On success returns a message naming the new image hash and container ID.
+/// On failure returns a message naming the failed step and the recovery path.
+pub async fn handle_project_rebuild(
+    name: &str,
+    drain_timeout_secs: u64,
+    force: bool,
+    projects_store: &Arc<RwLock<BTreeMap<String, ProjectEntry>>>,
+    config_dir: &Path,
+) -> String {
+    // ── 1. Validate project ──────────────────────────────────────────────────
+    let (host_path_str, project_url, ssh_port_opt) = {
+        let projects = projects_store.read().await;
+        let entry = match projects.get(name) {
+            Some(e) => e.clone(),
+            None => {
+                let available: Vec<&String> = projects.keys().collect();
+                return format!(
+                    "Project `{name}` not found. Available: {}",
+                    available
+                        .iter()
+                        .map(|s| s.as_str())
+                        .collect::<Vec<_>>()
+                        .join(", ")
+                );
+            }
+        };
+        match entry.host_path.clone() {
+            Some(p) => (p, entry.url.clone(), entry.ssh_port),
+            None => {
+                return format!(
+                    "Project `{name}` has no `host_path` configured — cannot rebuild.\n\
+                     Only projects created with `new project --adopt` or `adopt_project` \
+                     support the `project-rebuild` command."
+                );
+            }
+        }
+    };
+
+    let host_path = Path::new(&host_path_str);
+    if !host_path.exists() {
+        return format!(
+            "Host path `{host_path_str}` does not exist on disk — \
+             cannot rebuild project `{name}`."
+        );
+    }
+
+    // ── 2. Drain check ───────────────────────────────────────────────────────
+    let container_name = format!("huskies-{name}");
+    if !force
+        && drain_timeout_secs > 0
+        && let Some(err_msg) = wait_for_drain(&container_name, drain_timeout_secs).await
+    {
+        return format!(
+            "Project `{name}` rebuild aborted: {err_msg}\n\
+             Pass `--force` to skip the drain check or `--timeout 0` to not wait."
+        );
+    }
+
+    // ── 3. Build new image ───────────────────────────────────────────────────
+    let stacks_dir = config_dir.join("docker").join("stacks");
+    let (resolved_stack, _warnings) = super::new_project::detect_stack(host_path, &stacks_dir);
+    let base_image = super::new_project::image_for_stack(resolved_stack.as_deref());
+
+    let image = match super::new_project::build_project_image(host_path, &base_image, name).await {
+        Ok(img) => img,
+        Err(e) => {
+            return format!(
+                "Rebuild failed at **image build** step.\n\
+                 Error: {e}\n\n\
+                 Recovery: fix `.huskies/Dockerfile.fragment` in `{host_path_str}` then retry."
+            );
+        }
+    };
+
+    let image_hash = get_image_id(&image)
+        .await
+        .unwrap_or_else(|_| "unknown".to_string());
+    let image_short: String = image_hash.chars().take(19).collect();
+
+    // ── 4. Stop and remove old container ────────────────────────────────────
+    if let Err(e) = docker_stop(&container_name).await {
+        crate::slog!("[project-rebuild] stop '{container_name}': {e} (may already be stopped)");
+    }
+    if let Err(e) = docker_rm(&container_name).await {
+        return format!(
+            "Rebuild failed at **container remove** step.\n\
+             Error: {e}\n\n\
+             Recovery: run `docker rm {container_name}` manually then retry."
+        );
+    }
+
+    // ── 5. Start new container ───────────────────────────────────────────────
+    let port = project_url
+        .as_deref()
+        .and_then(|u| u.rsplit(':').next())
+        .and_then(|p| p.parse::<u16>().ok())
+        .unwrap_or(3001);
+    let ssh_port = ssh_port_opt.unwrap_or(2222);
+
+    let home = std::env::var("HOME").unwrap_or_else(|_| "/home/huskies".to_string());
+    let pub_key_path = std::path::PathBuf::from(&home)
+        .join(".huskies")
+        .join(name)
+        .join("id_ed25519.pub");
+    let pubkey = match tokio::fs::read_to_string(&pub_key_path).await {
+        Ok(k) => k.trim().to_string(),
+        Err(e) => {
+            return format!(
+                "Rebuild failed at **SSH key read** step.\n\
+                 Error: {e}\n\
+                 Expected public key at `{}`.\n\n\
+                 Recovery: run `ssh-keygen -t ed25519 -N '' -f {home}/.huskies/{name}/id_ed25519` \
+                 then retry.",
+                pub_key_path.display()
+            );
+        }
+    };
+
+    let credentials_file = std::path::PathBuf::from(&home)
+        .join(".claude")
+        .join(".credentials.json");
+    let creds_opt = if credentials_file.exists() {
+        Some(credentials_file.as_path())
+    } else {
+        None
+    };
+
+    let (git_user_name, git_user_email) =
+        super::new_project::resolve_git_identity(config_dir).await;
+
+    let mut docker_args = super::new_project::project_docker_run_args(
+        &container_name,
+        port,
+        ssh_port,
+        &pubkey,
+        &git_user_name,
+        &git_user_email,
+        creds_opt,
+        &super::new_project::resolve_gateway_url(),
+    );
+
+    docker_args.push("-v".into());
+    docker_args.push(format!("{host_path_str}:/workspace"));
+
+    let host_ssh_dir = std::path::PathBuf::from(&home).join(".ssh");
+    for key_name in &["id_ed25519", "id_rsa"] {
+        let key_path = host_ssh_dir.join(key_name);
+        if key_path.exists() {
+            docker_args.push("-v".into());
+            docker_args.push(format!(
+                "{}:/home/huskies/.ssh/{key_name}:ro",
+                key_path.display()
+            ));
+        }
+    }
+
+    docker_args.push("--restart".into());
+    docker_args.push("unless-stopped".into());
+    docker_args.push(image.clone());
+    docker_args.push("huskies".into());
+    docker_args.push("/workspace".into());
+
+    let run_output = tokio::process::Command::new("docker")
+        .args(&docker_args)
+        .output()
+        .await;
+
+    let container_id = match run_output {
+        Ok(out) if out.status.success() => String::from_utf8_lossy(&out.stdout).trim().to_string(),
+        Ok(out) => {
+            let stderr = String::from_utf8_lossy(&out.stderr).trim().to_string();
+            return format!(
+                "Rebuild failed at **container start** step.\n\
+                 Error: {stderr}\n\n\
+                 Recovery: the old container was removed. \
+                 Start a new one manually: `docker run -d --name {container_name} ... {image} huskies /workspace`"
+            );
+        }
+        Err(e) => {
+            return format!(
+                "Rebuild failed at **container start** step.\n\
+                 Error: {e}\n\n\
+                 Recovery: start the container manually: \
+                 `docker run -d --name {container_name} ... {image} huskies /workspace`"
+            );
+        }
+    };
+
+    let container_short: String = container_id.chars().take(12).collect();
+
+    // ── 6. Persist updated config (URL is unchanged; project already registered) ────
+    {
+        let container_url = format!("http://127.0.0.1:{port}");
+        let mut projects = projects_store.write().await;
+        if let Some(entry) = projects.get_mut(name) {
+            entry.url = Some(container_url.clone());
+        }
+        save_config(&projects, config_dir).await;
+        crate::crdt_state::write_gateway_project(name, &container_url);
+    }
+
+    crate::slog!("[project-rebuild] Rebuilt '{name}': image={image_hash} container={container_id}");
+
+    format!(
+        "Project **{name}** rebuilt.\n\
+         - New image: `{image}` (`{image_short}…`)\n\
+         - New container: `{container_name}` (`{container_short}…`)\n\
+         - State: `pipeline.db` and CRDT preserved (same volume bind-mount)\n\
+         - Port: {port} (unchanged)\n\
+         \n\
+         Use `switch {name}` then `status` to verify the pipeline."
+    )
+}
+
+/// Wait for active Claude agent processes in the container to exit.
+///
+/// Polls every 5 seconds until no `claude` processes remain or `timeout_secs` elapses.
+/// Returns `Some(error_message)` when agents are still running after the timeout,
+/// `None` when the container is idle or unreachable.
+async fn wait_for_drain(container_name: &str, timeout_secs: u64) -> Option<String> {
+    let deadline = std::time::Instant::now() + std::time::Duration::from_secs(timeout_secs);
+    let poll_interval = std::time::Duration::from_secs(5);
+
+    loop {
+        match count_active_claude_processes(container_name).await {
+            Ok(0) => return None,
+            Ok(n) => {
+                if std::time::Instant::now() >= deadline {
+                    return Some(format!(
+                        "{n} Claude agent process(es) still running after {timeout_secs}s drain timeout."
+                    ));
+                }
+                tokio::time::sleep(poll_interval).await;
+            }
+            Err(_) => {
+                // docker exec failed (container stopped or Docker unavailable) — proceed.
+                return None;
+            }
+        }
+    }
+}
+
+/// Count the number of active `claude` processes inside the given container.
+///
+/// Uses `docker exec <name> pgrep -f claude` — exits 0 with PID list when found,
+/// exits 1 when no matches (treated as 0 active processes).
+async fn count_active_claude_processes(container_name: &str) -> Result<usize, String> {
+    let out = tokio::process::Command::new("docker")
+        .args(["exec", container_name, "pgrep", "-f", "claude"])
+        .output()
+        .await
+        .map_err(|e| e.to_string())?;
+
+    if out.status.success() {
+        let count = String::from_utf8_lossy(&out.stdout)
+            .lines()
+            .filter(|l| !l.trim().is_empty())
+            .count();
+        Ok(count)
+    } else {
+        Ok(0)
+    }
+}
+
+/// Stop a running Docker container (`docker stop`).
+async fn docker_stop(container_name: &str) -> Result<(), String> {
+    let out = tokio::process::Command::new("docker")
+        .args(["stop", container_name])
+        .output()
+        .await
+        .map_err(|e| format!("docker stop failed to spawn: {e}"))?;
+
+    if out.status.success() {
+        Ok(())
+    } else {
+        Err(String::from_utf8_lossy(&out.stderr).trim().to_string())
+    }
+}
+
+/// Remove a stopped Docker container (`docker rm`).
+async fn docker_rm(container_name: &str) -> Result<(), String> {
+    let out = tokio::process::Command::new("docker")
+        .args(["rm", container_name])
+        .output()
+        .await
+        .map_err(|e| format!("docker rm failed to spawn: {e}"))?;
+
+    if out.status.success() {
+        Ok(())
+    } else {
+        Err(String::from_utf8_lossy(&out.stderr).trim().to_string())
+    }
+}
+
+/// Return the full image ID (sha256 digest) for a named Docker image.
+async fn get_image_id(image_name: &str) -> Result<String, String> {
+    let out = tokio::process::Command::new("docker")
+        .args(["inspect", image_name, "--format", "{{.Id}}"])
+        .output()
+        .await
+        .map_err(|e| format!("docker inspect failed: {e}"))?;
+
+    if out.status.success() {
+        Ok(String::from_utf8_lossy(&out.stdout).trim().to_string())
+    } else {
+        Err(String::from_utf8_lossy(&out.stderr).trim().to_string())
+    }
+}
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::service::gateway::config::ProjectEntry;
+    use std::collections::BTreeMap;
+    use std::sync::Arc;
+    use tokio::sync::RwLock;
+
+    fn make_store(
+        projects: Vec<(&str, ProjectEntry)>,
+    ) -> Arc<RwLock<BTreeMap<String, ProjectEntry>>> {
+        let map: BTreeMap<String, ProjectEntry> = projects
+            .into_iter()
+            .map(|(k, v)| (k.to_string(), v))
+            .collect();
+        Arc::new(RwLock::new(map))
+    }
+
+    // ── parsing ────────────────────────────────────────────────────────────
+
+    #[test]
+    fn extract_basic_command() {
+        let cmd =
+            extract_project_rebuild_command("Timmy project-rebuild myapp", "Timmy", "@timmy:home");
+        let cmd = cmd.unwrap();
+        assert_eq!(cmd.name, "myapp");
+        assert_eq!(cmd.drain_timeout_secs, DEFAULT_DRAIN_TIMEOUT_SECS);
+        assert!(!cmd.force);
+    }
+
+    #[test]
+    fn extract_with_force_flag() {
+        let cmd = extract_project_rebuild_command(
+            "@timmy project-rebuild myapp --force",
+            "Timmy",
+            "@timmy:home",
+        );
+        let cmd = cmd.unwrap();
+        assert_eq!(cmd.name, "myapp");
+        assert!(cmd.force);
+    }
+
+    #[test]
+    fn extract_with_timeout_flag() {
+        let cmd = extract_project_rebuild_command(
+            "Timmy project-rebuild myapp --timeout 120",
+            "Timmy",
+            "@timmy:home",
+        );
+        let cmd = cmd.unwrap();
+        assert_eq!(cmd.name, "myapp");
+        assert_eq!(cmd.drain_timeout_secs, 120);
+    }
+
+    #[test]
+    fn extract_with_timeout_zero_skips_drain() {
+        let cmd = extract_project_rebuild_command(
+            "Timmy project-rebuild myapp --timeout 0",
+            "Timmy",
+            "@timmy:home",
+        );
+        let cmd = cmd.unwrap();
+        assert_eq!(cmd.drain_timeout_secs, 0);
+    }
+
+    #[test]
+    fn extract_non_rebuild_returns_none() {
+        let cmd = extract_project_rebuild_command("Timmy status", "Timmy", "@timmy:home");
+        assert!(cmd.is_none());
+    }
+
+    #[test]
+    fn extract_rebuild_without_name_returns_none() {
+        let cmd = extract_project_rebuild_command("Timmy project-rebuild", "Timmy", "@timmy:home");
+        assert!(cmd.is_none());
+    }
+
+    #[test]
+    fn extract_with_full_user_id() {
+        let cmd = extract_project_rebuild_command(
+            "@timmy:home project-rebuild alpha",
+            "Timmy",
+            "@timmy:home",
+        );
+        assert_eq!(cmd.unwrap().name, "alpha");
+    }
+
+    #[test]
+    fn extract_case_insensitive_bot_mention() {
+        let cmd =
+            extract_project_rebuild_command("timmy project-rebuild beta", "Timmy", "@timmy:home");
+        assert_eq!(cmd.unwrap().name, "beta");
+    }
+
+    // ── handle_project_rebuild validation ─────────────────────────────────
+
+    #[tokio::test]
+    async fn rebuild_unknown_project_returns_error() {
+        let store = make_store(vec![]);
+        let dir = tempfile::tempdir().unwrap();
+        let result = handle_project_rebuild("nonexistent", 0, true, &store, dir.path()).await;
+        assert!(
+            result.contains("not found"),
+            "expected 'not found': {result}"
+        );
+    }
+
+    #[tokio::test]
+    async fn rebuild_project_without_host_path_returns_error() {
+        let store = make_store(vec![(
+            "myapp",
+            ProjectEntry {
+                url: Some("http://127.0.0.1:3101".into()),
+                auth_token: None,
+                ssh_port: Some(2201),
+                host_path: None,
+            },
+        )]);
+        let dir = tempfile::tempdir().unwrap();
+        let result = handle_project_rebuild("myapp", 0, true, &store, dir.path()).await;
+        assert!(
+            result.contains("host_path"),
+            "expected 'host_path' mention: {result}"
+        );
+    }
+
+    #[tokio::test]
+    async fn rebuild_project_with_missing_host_dir_returns_error() {
+        let store = make_store(vec![(
+            "myapp",
+            ProjectEntry {
+                url: Some("http://127.0.0.1:3101".into()),
+                auth_token: None,
+                ssh_port: Some(2201),
+                host_path: Some("/nonexistent/path/xyz123".into()),
+            },
+        )]);
+        let dir = tempfile::tempdir().unwrap();
+        let result = handle_project_rebuild("myapp", 0, true, &store, dir.path()).await;
+        assert!(
+            result.contains("does not exist"),
+            "expected 'does not exist': {result}"
+        );
+    }
+
+    /// End-to-end flow test: rebuild a project that has a valid host directory.
+    ///
+    /// With `--force` and `--timeout 0` the drain check is skipped.
+    /// The function proceeds to the image build step, which fails when Docker is
+    /// not available in CI.  On failure the reply must:
+    ///   (a) name the failed step ("image build")
+    ///   (b) leave the project still registered in the gateway (state preserved)
+    ///   (c) include a recovery path
+    ///
+    /// When Docker IS available and the base image exists this test would exercise
+    /// the full container stop → build → start → re-register flow.
+    #[tokio::test]
+    async fn rebuild_e2e_with_valid_host_path_reaches_image_build_step() {
+        let host_dir = tempfile::tempdir().unwrap();
+        // Create a minimal .huskies/ directory (simulating an existing project).
+        std::fs::create_dir_all(host_dir.path().join(".huskies")).unwrap();
+
+        let store = make_store(vec![(
+            "myapp",
+            ProjectEntry {
+                url: Some("http://127.0.0.1:3101".into()),
+                auth_token: Some("tok".into()),
+                ssh_port: Some(2201),
+                host_path: Some(host_dir.path().to_str().unwrap().to_string()),
+            },
+        )]);
+        let config_dir = tempfile::tempdir().unwrap();
+
+        let result = handle_project_rebuild("myapp", 0, true, &store, config_dir.path()).await;
+
+        // (a) Step naming: one of several possible failure steps depending on what Docker
+        //     binaries are available in the test environment, or a success reply.
+        let names_a_step = result.contains("image build")
+            || result.contains("SSH key")
+            || result.contains("container remove")
+            || result.contains("container start");
+        let is_success = result.contains("rebuilt");
+        assert!(
+            names_a_step || is_success,
+            "result should name a step or report success: {result}"
+        );
+
+        // (b) State preserved: project is still registered in the gateway store.
+        let projects = store.read().await;
+        assert!(
+            projects.contains_key("myapp"),
+            "project 'myapp' must remain registered after failed rebuild: {result}"
+        );
+    }
+}

server/src/chat/transport/matrix/rebuild.rs

@@ -40,6 +40,43 @@ pub fn extract_rebuild_command(
     }
 }
 
+/// Parse a "rebuild gateway" command from a raw message body.
+///
+/// Returns `Some(RebuildCommand)` only when the stripped message begins with
+/// "rebuild gateway" (case-insensitive).  A plain "rebuild" without the
+/// "gateway" qualifier returns `None` so it falls through to the standard
+/// server rebuild handler.
+pub fn extract_rebuild_gateway_command(
+    message: &str,
+    bot_name: &str,
+    bot_user_id: &str,
+) -> Option<RebuildCommand> {
+    let stripped = strip_bot_mention(message, bot_name, bot_user_id);
+    let trimmed = stripped
+        .trim()
+        .trim_start_matches(|c: char| !c.is_alphanumeric());
+
+    let (cmd, rest) = trimmed.split_once(char::is_whitespace)?;
+
+    if !cmd.eq_ignore_ascii_case("rebuild") {
+        return None;
+    }
+
+    let qualifier = rest
+        .trim()
+        .trim_start_matches(|c: char| !c.is_alphanumeric());
+    let first_word = match qualifier.split_once(char::is_whitespace) {
+        Some((w, _)) => w,
+        None => qualifier,
+    };
+
+    if first_word.eq_ignore_ascii_case("gateway") {
+        Some(RebuildCommand)
+    } else {
+        None
+    }
+}
+
 /// Handle a rebuild command: trigger server rebuild and restart.
 ///
 /// Returns a string describing the outcome.  On build failure the error

server/src/chat/transport/matrix/sled_upgrade.rs

@@ -0,0 +1,478 @@
+//! `upgrade [<project>]` gateway chat command — streaming sled binary upgrade.
+//!
+//! Usage (gateway mode only):
+//! - `{bot} upgrade <project>` — upgrade the named sled's binary in-container.
+//! - `{bot} upgrade` — list registered projects (shows what can be targeted).
+//!
+//! The gateway orchestrates the upgrade in four phases, streaming a marker to
+//! the chat room at each step:
+//! 1. `[1/4] downloading`    — POSTs to `{sled_url}/api/upgrade`; sled starts download.
+//! 2. `[2/4] swapping binary` — gateway received 202; sled atomically renamed the binary.
+//! 3. `[3/4] restarting sled` — sled re-execs with the new binary; HTTP goes dark briefly.
+//! 4. `[4/4] reconnected to gateway` — sled's `/health` probe is responding again.
+//!
+//! Concurrent `upgrade` invocations are serialised via a global async mutex so
+//! that two simultaneous upgrades cannot interleave their phase markers or race
+//! on the sled restart.
+
+use crate::service::gateway::config::ProjectEntry;
+use std::collections::BTreeMap;
+use std::future::Future;
+use std::sync::{Arc, OnceLock};
+use std::time::Duration;
+use tokio::sync::{Mutex, RwLock};
+
+// ── Serial lock ────────────────────────────────────────────────────────────────
+
+static UPGRADE_LOCK: OnceLock<Mutex<()>> = OnceLock::new();
+
+fn upgrade_lock() -> &'static Mutex<()> {
+    UPGRADE_LOCK.get_or_init(|| Mutex::new(()))
+}
+
+// ── Command parsing ────────────────────────────────────────────────────────────
+
+/// A parsed `upgrade` command.
+#[derive(Debug, PartialEq)]
+pub enum UpgradeCommand {
+    /// `upgrade <project>` — upgrade the named sled.
+    Upgrade {
+        /// The project/sled name to upgrade.
+        project: String,
+    },
+    /// `upgrade` with no argument — list available projects.
+    ListProjects,
+}
+
+/// Parse an `upgrade [<project>]` command from a raw message body.
+///
+/// Strips the bot mention prefix and checks whether the first word is `upgrade`.
+/// Returns `None` when the message is not an upgrade command.
+pub fn extract_upgrade_command(
+    message: &str,
+    bot_name: &str,
+    bot_user_id: &str,
+) -> Option<UpgradeCommand> {
+    let stripped = crate::chat::util::strip_bot_mention(message, bot_name, bot_user_id);
+    let trimmed = stripped
+        .trim()
+        .trim_start_matches(|c: char| !c.is_alphanumeric());
+
+    let (cmd, rest) = match trimmed.split_once(char::is_whitespace) {
+        Some((c, r)) => (c, r.trim()),
+        None => (trimmed, ""),
+    };
+
+    if !cmd.eq_ignore_ascii_case("upgrade") {
+        return None;
+    }
+
+    if rest.is_empty() {
+        Some(UpgradeCommand::ListProjects)
+    } else {
+        Some(UpgradeCommand::Upgrade {
+            project: rest.split_whitespace().next().unwrap_or(rest).to_string(),
+        })
+    }
+}
+
+// ── Handlers ───────────────────────────────────────────────────────────────────
+
+/// List available projects when `upgrade` is invoked without an argument.
+///
+/// Returns a Markdown string enumerating the registered project names so the
+/// user knows which targets are valid for `upgrade <project>`.
+pub async fn handle_upgrade_list_projects(
+    projects_store: &Arc<RwLock<BTreeMap<String, ProjectEntry>>>,
+) -> String {
+    let projects = projects_store.read().await;
+    if projects.is_empty() {
+        return "No projects are currently registered with the gateway.".to_string();
+    }
+    let names: Vec<&String> = projects.keys().collect();
+    let list = names
+        .iter()
+        .map(|n| format!("- `{n}`"))
+        .collect::<Vec<_>>()
+        .join("\n");
+    format!("Registered projects (use `upgrade <project>` to upgrade one):\n{list}")
+}
+
+/// Upgrade a named sled by streaming phase markers to the chat room.
+///
+/// Acquires the global upgrade lock to serialise concurrent invocations.  Each
+/// phase is announced by calling `send_phase` before the corresponding work
+/// begins.  On any failure, an error message is returned and the previous
+/// binary remains active on the sled.
+///
+/// `gateway_port` is used to derive the default binary source URL
+/// (`http://gateway:<port>/api/huskies-binary`) when neither
+/// `HUSKIES_GATEWAY_BINARY_URL` nor `--source` is set.
+pub async fn handle_sled_upgrade<F, Fut>(
+    project: &str,
+    projects_store: &Arc<RwLock<BTreeMap<String, ProjectEntry>>>,
+    gateway_port: Option<u16>,
+    send_phase: F,
+) -> String
+where
+    F: Fn(String) -> Fut,
+    Fut: Future<Output = ()>,
+{
+    // ── Look up project URL ──────────────────────────────────────────────────
+    let sled_url = {
+        let projects = projects_store.read().await;
+        match projects.get(project).and_then(|e| e.url.clone()) {
+            Some(u) => u,
+            None => {
+                let available: Vec<&String> = projects.keys().collect();
+                return format!(
+                    "Project `{project}` not found. Registered projects: {}",
+                    available
+                        .iter()
+                        .map(|s| s.as_str())
+                        .collect::<Vec<_>>()
+                        .join(", ")
+                );
+            }
+        }
+    };
+
+    // ── Resolve binary source URL ────────────────────────────────────────────
+    let source_url = std::env::var("HUSKIES_GATEWAY_BINARY_URL").unwrap_or_else(|_| {
+        format!(
+            "http://gateway:{}/api/huskies-binary",
+            gateway_port.unwrap_or(3000)
+        )
+    });
+
+    // ── Acquire serial lock ──────────────────────────────────────────────────
+    let _lock = upgrade_lock().lock().await;
+
+    let client = reqwest::Client::builder()
+        .timeout(Duration::from_secs(30))
+        .build()
+        .unwrap_or_default();
+
+    // ── Phase 1: downloading ─────────────────────────────────────────────────
+    send_phase("[1/4] downloading\u{2026}".to_string()).await;
+
+    let upgrade_url = format!("{}/api/upgrade", sled_url.trim_end_matches('/'));
+    let body = serde_json::json!({ "source_url": source_url });
+
+    let resp = match client.post(&upgrade_url).json(&body).send().await {
+        Ok(r) => r,
+        Err(e) => {
+            return format!(
+                "Upgrade failed at **[1/4] downloading**: could not reach sled at `{upgrade_url}`.\n\
+                 Error: {e}\n\n\
+                 The previous version remains active."
+            );
+        }
+    };
+
+    if !resp.status().is_success() && resp.status().as_u16() != 202 {
+        let status = resp.status();
+        let body_text = resp.text().await.unwrap_or_default();
+        return format!(
+            "Upgrade failed at **[1/4] downloading**: sled returned HTTP {status}.\n\
+             Response: {body_text}\n\n\
+             The previous version remains active."
+        );
+    }
+
+    // ── Phase 2: swapping binary ─────────────────────────────────────────────
+    // The sled accepted the request (202) and is downloading + atomically
+    // replacing the binary in the background.
+    send_phase("[2/4] swapping binary\u{2026}".to_string()).await;
+
+    // ── Phase 3: restarting sled ─────────────────────────────────────────────
+    // The sled will re-exec momentarily; announce before the health loop.
+    send_phase("[3/4] restarting sled\u{2026}".to_string()).await;
+
+    // ── Wait for sled to come back up ────────────────────────────────────────
+    let health_url = format!("{}/health", sled_url.trim_end_matches('/'));
+    // Give the sled a few seconds to start the download + re-exec before polling.
+    tokio::time::sleep(Duration::from_secs(3)).await;
+
+    let reconnected = wait_for_health(&client, &health_url, 120).await;
+    if !reconnected {
+        return format!(
+            "Upgrade failed at **[4/4] reconnected to gateway**: sled at `{sled_url}` did not \
+             come back online within 120 seconds after the upgrade was triggered.\n\n\
+             Check the container logs: `docker logs huskies-{project}`"
+        );
+    }
+
+    // ── Phase 4: reconnected ─────────────────────────────────────────────────
+    send_phase("[4/4] reconnected to gateway".to_string()).await;
+
+    // ── Report new version ───────────────────────────────────────────────────
+    let version = fetch_sled_version(&client, &sled_url).await;
+    format!("{project} upgraded to version {version}")
+}
+
+// ── Helpers ───────────────────────────────────────────────────────────────────
+
+/// Poll `GET {health_url}` every 3 seconds until it returns 200 or `timeout_secs` elapses.
+///
+/// Returns `true` when the probe succeeds, `false` on timeout.
+async fn wait_for_health(client: &reqwest::Client, health_url: &str, timeout_secs: u64) -> bool {
+    let deadline = std::time::Instant::now() + Duration::from_secs(timeout_secs);
+    let poll = Duration::from_secs(3);
+    loop {
+        match client.get(health_url).send().await {
+            Ok(r) if r.status().is_success() => return true,
+            _ => {}
+        }
+        if std::time::Instant::now() >= deadline {
+            return false;
+        }
+        tokio::time::sleep(poll).await;
+    }
+}
+
+/// Fetch the running version from the sled's `get_version` MCP tool.
+///
+/// Returns the version string on success, or `"unknown"` on any error so the
+/// final chat reply is still meaningful.
+async fn fetch_sled_version(client: &reqwest::Client, sled_url: &str) -> String {
+    let mcp_url = format!("{}/mcp", sled_url.trim_end_matches('/'));
+    let body = serde_json::json!({
+        "jsonrpc": "2.0",
+        "id": 1,
+        "method": "tools/call",
+        "params": {
+            "name": "get_version",
+            "arguments": {}
+        }
+    });
+    let resp = match client.post(&mcp_url).json(&body).send().await {
+        Ok(r) => r,
+        Err(_) => return "unknown".to_string(),
+    };
+    let val: serde_json::Value = match resp.json().await {
+        Ok(v) => v,
+        Err(_) => return "unknown".to_string(),
+    };
+    // MCP tools/call response: result.content[0].text is a JSON string.
+    let text = val
+        .pointer("/result/content/0/text")
+        .and_then(|v| v.as_str())
+        .unwrap_or("");
+    if text.is_empty() {
+        return "unknown".to_string();
+    }
+    serde_json::from_str::<serde_json::Value>(text)
+        .ok()
+        .and_then(|v| v.get("version").and_then(|v| v.as_str()).map(String::from))
+        .unwrap_or_else(|| "unknown".to_string())
+}
+
+// ── Tests ──────────────────────────────────────────────────────────────────────
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    // ── extract_upgrade_command ───────────────────────────────────────────────
+
+    #[test]
+    fn extract_upgrade_with_project() {
+        let cmd = extract_upgrade_command("Timmy upgrade huskies-server", "Timmy", "@timmy:home");
+        assert_eq!(
+            cmd,
+            Some(UpgradeCommand::Upgrade {
+                project: "huskies-server".to_string()
+            })
+        );
+    }
+
+    #[test]
+    fn extract_upgrade_no_arg_is_list() {
+        let cmd = extract_upgrade_command("Timmy upgrade", "Timmy", "@timmy:home");
+        assert_eq!(cmd, Some(UpgradeCommand::ListProjects));
+    }
+
+    #[test]
+    fn extract_upgrade_with_full_user_id() {
+        let cmd = extract_upgrade_command("@timmy:home upgrade myapp", "Timmy", "@timmy:home");
+        assert_eq!(
+            cmd,
+            Some(UpgradeCommand::Upgrade {
+                project: "myapp".to_string()
+            })
+        );
+    }
+
+    #[test]
+    fn extract_non_upgrade_returns_none() {
+        let cmd = extract_upgrade_command("Timmy status", "Timmy", "@timmy:home");
+        assert!(cmd.is_none());
+    }
+
+    #[test]
+    fn extract_upgrade_case_insensitive() {
+        let cmd = extract_upgrade_command("Timmy UPGRADE alpha", "Timmy", "@timmy:home");
+        assert_eq!(
+            cmd,
+            Some(UpgradeCommand::Upgrade {
+                project: "alpha".to_string()
+            })
+        );
+    }
+
+    // ── handle_upgrade_list_projects ─────────────────────────────────────────
+
+    #[tokio::test]
+    async fn list_projects_empty_store() {
+        let store: Arc<RwLock<BTreeMap<String, ProjectEntry>>> =
+            Arc::new(RwLock::new(BTreeMap::new()));
+        let msg = handle_upgrade_list_projects(&store).await;
+        assert!(
+            msg.contains("No projects"),
+            "empty store should say no projects: {msg}"
+        );
+    }
+
+    #[tokio::test]
+    async fn list_projects_shows_names() {
+        use std::collections::BTreeMap;
+        let mut map = BTreeMap::new();
+        map.insert(
+            "alpha".to_string(),
+            ProjectEntry {
+                url: Some("http://localhost:3001".into()),
+                auth_token: None,
+                ssh_port: None,
+                host_path: None,
+            },
+        );
+        map.insert(
+            "beta".to_string(),
+            ProjectEntry {
+                url: Some("http://localhost:3002".into()),
+                auth_token: None,
+                ssh_port: None,
+                host_path: None,
+            },
+        );
+        let store = Arc::new(RwLock::new(map));
+        let msg = handle_upgrade_list_projects(&store).await;
+        assert!(msg.contains("alpha"), "should list alpha: {msg}");
+        assert!(msg.contains("beta"), "should list beta: {msg}");
+    }
+
+    // ── handle_sled_upgrade validation ───────────────────────────────────────
+
+    #[tokio::test]
+    async fn upgrade_unknown_project_returns_error() {
+        let store: Arc<RwLock<BTreeMap<String, ProjectEntry>>> =
+            Arc::new(RwLock::new(BTreeMap::new()));
+        let phases: std::sync::Mutex<Vec<String>> = std::sync::Mutex::new(vec![]);
+        let result = handle_sled_upgrade("nonexistent", &store, Some(3000), |msg| {
+            phases.lock().unwrap().push(msg);
+            async {}
+        })
+        .await;
+        assert!(
+            result.contains("not found"),
+            "should say not found: {result}"
+        );
+        // No phase markers should have been emitted before the validation error.
+        assert!(
+            phases.lock().unwrap().is_empty(),
+            "no phases should be emitted for unknown project"
+        );
+    }
+
+    #[tokio::test]
+    async fn upgrade_project_with_no_url_fails_gracefully() {
+        let mut map = BTreeMap::new();
+        map.insert(
+            "myapp".to_string(),
+            ProjectEntry {
+                url: None,
+                auth_token: None,
+                ssh_port: None,
+                host_path: None,
+            },
+        );
+        let store = Arc::new(RwLock::new(map));
+        let result = handle_sled_upgrade("myapp", &store, Some(3000), |_msg| async {}).await;
+        assert!(
+            result.contains("not found"),
+            "project with no URL should say not found: {result}"
+        );
+    }
+
+    #[tokio::test]
+    async fn upgrade_unreachable_sled_reports_failure() {
+        let mut map = BTreeMap::new();
+        map.insert(
+            "myapp".to_string(),
+            ProjectEntry {
+                url: Some("http://127.0.0.1:1".into()), // port 1 is never listening
+                auth_token: None,
+                ssh_port: None,
+                host_path: None,
+            },
+        );
+        let store = Arc::new(RwLock::new(map));
+        let phases: std::sync::Mutex<Vec<String>> = std::sync::Mutex::new(vec![]);
+        let result = handle_sled_upgrade("myapp", &store, Some(3000), |msg| {
+            phases.lock().unwrap().push(msg);
+            async {}
+        })
+        .await;
+        // Phase 1 marker must have been sent before the failed request.
+        let sent = phases.lock().unwrap().clone();
+        assert!(
+            sent.iter().any(|m| m.contains("[1/4]")),
+            "phase 1 marker must be sent: {sent:?}"
+        );
+        assert!(
+            result.contains("downloading") || result.contains("reach"),
+            "error should mention the failure: {result}"
+        );
+        assert!(
+            result.contains("previous version"),
+            "error should confirm old version is active: {result}"
+        );
+    }
+
+    // ── wait_for_health ───────────────────────────────────────────────────────
+
+    #[tokio::test]
+    async fn wait_for_health_immediate_success() {
+        let listener = tokio::net::TcpListener::bind("127.0.0.1:0").await.unwrap();
+        let port = listener.local_addr().unwrap().port();
+
+        let handle = tokio::spawn(async move {
+            if let Ok((mut stream, _)) = listener.accept().await {
+                use tokio::io::AsyncWriteExt;
+                let mut buf = [0u8; 4096];
+                let _ = tokio::io::AsyncReadExt::read(&mut stream, &mut buf).await;
+                let _ = stream
+                    .write_all(b"HTTP/1.1 200 OK\r\nContent-Length: 2\r\n\r\nok")
+                    .await;
+            }
+        });
+
+        let client = reqwest::Client::new();
+        let url = format!("http://127.0.0.1:{port}/health");
+        let ok = wait_for_health(&client, &url, 5).await;
+        assert!(ok, "should return true when health probe succeeds");
+        handle.abort();
+    }
+
+    #[tokio::test]
+    async fn wait_for_health_timeout() {
+        let client = reqwest::Client::builder()
+            .timeout(Duration::from_millis(100))
+            .build()
+            .unwrap();
+        // Nothing listening on port 1.
+        let ok = wait_for_health(&client, "http://127.0.0.1:1/health", 1).await;
+        assert!(!ok, "should return false when health probe never succeeds");
+    }
+}

server/src/chat/transport/slack/commands/llm.rs

@@ -29,9 +29,8 @@ pub(super) async fn handle_llm_message(
     };
 
     let bot_name = &ctx.services.bot_name;
-    let event_ctx = crate::llm_session::assemble_prompt_context(
-        resume_session_id.as_deref().unwrap_or(channel),
-    );
+    let persona = bot_name.to_lowercase();
+    let event_ctx = crate::llm_session::assemble_prompt_context(&persona);
     let prompt = format!(
         "{event_ctx}[Your name is {bot_name}. Refer to yourself as {bot_name}, not Claude.]\n\n{user}: {user_message}"
     );

server/src/chat/transport/whatsapp/commands/llm.rs

@@ -27,8 +27,8 @@ pub(super) async fn handle_llm_message(
     };
 
     let bot_name = &ctx.services.bot_name;
-    let event_ctx =
-        crate::llm_session::assemble_prompt_context(resume_session_id.as_deref().unwrap_or(sender));
+    let persona = bot_name.to_lowercase();
+    let event_ctx = crate::llm_session::assemble_prompt_context(&persona);
     let prompt = format!(
         "{event_ctx}[Your name is {bot_name}. Refer to yourself as {bot_name}, not Claude.]\n\n{sender}: {user_message}"
     );

server/src/cli.rs

@@ -27,6 +27,19 @@ pub(crate) struct CliArgs {
     /// forwards all `prompt_permission` tool calls to the gateway over a WebSocket.
     /// Also readable from the `HUSKIES_UPSTREAM_GATEWAY` env var.
     pub(crate) upstream_gateway: Option<String>,
+    /// Whether the `upgrade` subcommand was given.
+    pub(crate) upgrade: bool,
+    /// Source URL for the `upgrade` subcommand (`--source <URL>`).
+    ///
+    /// If omitted, the upgrade subcommand falls back to
+    /// `HUSKIES_BINARY_SOURCE` env var, then derives the URL from
+    /// `HUSKIES_UPSTREAM_GATEWAY`.
+    pub(crate) upgrade_source: Option<String>,
+    /// Path to a trampoline job file (`--trampoline <path>`).
+    ///
+    /// When set, the binary runs as a detached trampoline helper: it kills the
+    /// old gateway, starts the new one, polls its health, and rolls back on failure.
+    pub(crate) trampoline: Option<String>,
 }
 
 /// Parse CLI arguments into `CliArgs`, or exit early for `--help` / `--version`.
@@ -41,6 +54,9 @@ pub(crate) fn parse_cli_args(args: &[String]) -> Result<CliArgs, String> {
     let mut join_token: Option<String> = None;
     let mut gateway_url: Option<String> = None;
     let mut upstream_gateway: Option<String> = None;
+    let mut upgrade = false;
+    let mut upgrade_source: Option<String> = None;
+    let mut trampoline: Option<String> = None;
     let mut i = 0;
 
     while i < args.len() {
@@ -120,6 +136,29 @@ pub(crate) fn parse_cli_args(args: &[String]) -> Result<CliArgs, String> {
             "agent" => {
                 agent = true;
             }
+            "upgrade" => {
+                upgrade = true;
+            }
+            "--source" => {
+                i += 1;
+                if i >= args.len() {
+                    return Err("--source requires a value".to_string());
+                }
+                upgrade_source = Some(args[i].clone());
+            }
+            a if a.starts_with("--source=") => {
+                upgrade_source = Some(a["--source=".len()..].to_string());
+            }
+            "--trampoline" => {
+                i += 1;
+                if i >= args.len() {
+                    return Err("--trampoline requires a path".to_string());
+                }
+                trampoline = Some(args[i].clone());
+            }
+            a if a.starts_with("--trampoline=") => {
+                trampoline = Some(a["--trampoline=".len()..].to_string());
+            }
             a if a.starts_with('-') => {
                 return Err(format!("unknown option: {a}"));
             }
@@ -147,6 +186,9 @@ pub(crate) fn parse_cli_args(args: &[String]) -> Result<CliArgs, String> {
         join_token,
         gateway_url,
         upstream_gateway,
+        upgrade,
+        upgrade_source,
+        trampoline,
     })
 }
 
@@ -155,12 +197,16 @@ pub(crate) fn print_help() {
     println!("huskies init [OPTIONS] [PATH]");
     println!("huskies agent --rendezvous <URL> [OPTIONS] [PATH]");
     println!("huskies --gateway [OPTIONS] [PATH]");
+    println!("huskies upgrade [--source <URL>]");
     println!();
     println!("Serve a huskies project.");
     println!();
     println!("COMMANDS:");
-    println!("  init   Scaffold a new .huskies/ project and start the interactive setup wizard.");
-    println!("  agent  Run as a headless build agent — syncs CRDT state, claims and runs work.");
+    println!("  init     Scaffold a new .huskies/ project and start the interactive setup wizard.");
+    println!("  agent    Run as a headless build agent — syncs CRDT state, claims and runs work.");
+    println!(
+        "  upgrade  Fetch a new huskies binary from SOURCE and atomically replace the current"
+    );
     println!();
     println!("ARGS:");
     println!(
@@ -190,6 +236,8 @@ pub(crate) fn print_help() {
     println!("                           sled connects to WS URL and forwards all");
     println!("                           prompt_permission calls via the uplink protocol.");
     println!("                           Also readable from HUSKIES_UPSTREAM_GATEWAY env var.");
+    println!("  --source <URL>           Binary source URL for the `upgrade` subcommand.");
+    println!("                           Falls back to HUSKIES_BINARY_SOURCE env var.");
 }
 
 /// Resolve the optional positional path argument into an absolute `PathBuf`.
@@ -399,6 +447,58 @@ mod tests {
         assert!(parse_cli_args(&args).is_err());
     }
 
+    // ── upgrade subcommand ──────────────────────────────────────────
+
+    #[test]
+    fn parse_upgrade_subcommand() {
+        let args = vec!["upgrade".to_string()];
+        let result = parse_cli_args(&args).unwrap();
+        assert!(result.upgrade);
+        assert_eq!(result.upgrade_source, None);
+    }
+
+    #[test]
+    fn parse_upgrade_with_source_flag() {
+        let args = vec![
+            "upgrade".to_string(),
+            "--source".to_string(),
+            "http://gateway:3000/api/huskies-binary".to_string(),
+        ];
+        let result = parse_cli_args(&args).unwrap();
+        assert!(result.upgrade);
+        assert_eq!(
+            result.upgrade_source,
+            Some("http://gateway:3000/api/huskies-binary".to_string())
+        );
+    }
+
+    #[test]
+    fn parse_upgrade_with_source_equals_syntax() {
+        let args = vec![
+            "upgrade".to_string(),
+            "--source=http://gw:3000/api/b".to_string(),
+        ];
+        let result = parse_cli_args(&args).unwrap();
+        assert!(result.upgrade);
+        assert_eq!(
+            result.upgrade_source,
+            Some("http://gw:3000/api/b".to_string())
+        );
+    }
+
+    #[test]
+    fn parse_upgrade_source_missing_value_is_error() {
+        let args = vec!["upgrade".to_string(), "--source".to_string()];
+        assert!(parse_cli_args(&args).is_err());
+    }
+
+    #[test]
+    fn parse_no_args_upgrade_is_false() {
+        let result = parse_cli_args(&[]).unwrap();
+        assert!(!result.upgrade);
+        assert_eq!(result.upgrade_source, None);
+    }
+
     // ── resolve_path_arg ────────────────────────────────────────────
 
     #[test]

server/src/crdt_state/lww_maps/llm_sessions.rs

@@ -1,10 +1,10 @@
 //! Read/write helpers for the `llm_sessions` LWW-map collection, including the
-//! atomic `assemble_and_advance_session` helper used by the Matrix bot.
+//! atomic `assemble_and_advance_session` helper used by every chat transport.
 //!
-//! LLM sessions are keyed by `session_id` (typically a Matrix room ID) and track
-//! per-sled high-water marks so that `assemble_and_advance_session` can inject
-//! only events the LLM has not yet seen and advance the marks atomically within
-//! a single CRDT lock acquisition.
+//! LLM sessions are keyed by **persona name** (e.g. `"timmy"` for the
+//! gateway-level bot) and track per-sled high-water marks so that
+//! `assemble_and_advance_session` can inject only events the LLM has not yet
+//! seen and advance the marks atomically within a single CRDT lock acquisition.
 
 use std::collections::{BTreeMap, BTreeSet};
 
@@ -16,16 +16,15 @@ use super::super::state::{apply_and_persist, get_crdt, rebuild_llm_session_index
 use super::super::types::{LlmSessionCrdt, LlmSessionView, ScopeFilter};
 use super::event_log::GAP_PIPELINE_EVENT;
 
-/// Write or upsert an LLM session entry keyed by `session_id`.
+/// Write or upsert an LLM session entry keyed by `persona`.
 ///
-/// Creates a new entry if `session_id` is not yet present; updates
-/// `persona_name` and `scope` on an existing entry.  The `high_water`
-/// register is not touched by this function — use `assemble_and_advance_session`
-/// to advance it atomically.
+/// Creates a new entry if `persona` is not yet present; updates `scope` on an
+/// existing entry.  The `high_water` register is not touched by this function —
+/// use `assemble_and_advance_session` to advance it atomically.
 ///
 /// The `scope` string must be in wire form: `"all"` for [`ScopeFilter::All`]
 /// or `"sleds:hex1,hex2"` for [`ScopeFilter::Sleds`].
-pub fn write_llm_session(session_id: &str, persona_name: &str, scope: &str) {
+pub fn write_llm_session(persona: &str, scope: &str) {
     let Some(state_mutex) = get_crdt() else {
         return;
     };
@@ -33,19 +32,19 @@ pub fn write_llm_session(session_id: &str, persona_name: &str, scope: &str) {
         return;
     };
 
-    if let Some(&idx) = state.llm_session_index.get(session_id) {
+    if let Some(&idx) = state.llm_session_index.get(persona) {
         apply_and_persist(&mut state, |s| {
             s.crdt.doc.llm_sessions[idx]
                 .persona_name
-                .set(persona_name.to_string())
+                .set(persona.to_string())
         });
         apply_and_persist(&mut state, |s| {
             s.crdt.doc.llm_sessions[idx].scope.set(scope.to_string())
         });
     } else {
         let entry: JsonValue = json!({
-            "session_id": session_id,
-            "persona_name": persona_name,
+            "session_id": persona,
+            "persona_name": persona,
             "scope": scope,
             "high_water": "{}",
         })
@@ -57,19 +56,19 @@ pub fn write_llm_session(session_id: &str, persona_name: &str, scope: &str) {
     }
 }
 
-/// Read a single LLM session entry by `session_id`.
-pub fn read_llm_session(session_id: &str) -> Option<LlmSessionView> {
+/// Read a single LLM session entry by persona name.
+pub fn read_llm_session(persona: &str) -> Option<LlmSessionView> {
     let state_mutex = get_crdt()?;
     let state = state_mutex.lock().ok()?;
-    let &idx = state.llm_session_index.get(session_id)?;
+    let &idx = state.llm_session_index.get(persona)?;
     extract_llm_session_view(&state.crdt.doc.llm_sessions[idx])
 }
 
-/// Atomically read new event-log entries for `session_id` past the stored
+/// Atomically read new event-log entries for `persona` past the stored
 /// high-water marks, render them as a block of audit lines, and advance the
 /// marks to prevent double-injection on the next call.
 ///
-/// The set of sleds whose events are collected is determined by the session's
+/// The set of sleds whose events are collected is determined by the persona's
 /// [`ScopeFilter`]:
 /// - [`ScopeFilter::All`]: events from every sled present in the event log are
 ///   included — this is the gateway-level persona default that gives a full
@@ -81,7 +80,7 @@ pub fn read_llm_session(session_id: &str) -> Option<LlmSessionView> {
 ///
 /// Returns an empty `Vec` when there are no new events or the CRDT is not
 /// initialised.
-pub fn assemble_and_advance_session(session_id: &str) -> Vec<String> {
+pub fn assemble_and_advance_session(persona: &str) -> Vec<String> {
     let local_sled_id = crate::crdt_state::our_node_id().unwrap_or_default();
 
     let Some(state_mutex) = get_crdt() else {
@@ -91,9 +90,8 @@ pub fn assemble_and_advance_session(session_id: &str) -> Vec<String> {
         return Vec::new();
     };
 
-    // Determine the session's scope filter and current high-water map.
-    let (scope_filter, current_high_water) = match state.llm_session_index.get(session_id).copied()
-    {
+    // Determine the persona's scope filter and current high-water map.
+    let (scope_filter, current_high_water) = match state.llm_session_index.get(persona).copied() {
         Some(idx) => {
             let filter = parse_scope(&state.crdt.doc.llm_sessions[idx], &local_sled_id);
             let hw = parse_high_water(&state.crdt.doc.llm_sessions[idx]);
@@ -168,8 +166,8 @@ pub fn assemble_and_advance_session(session_id: &str) -> Vec<String> {
     }
     let new_hw_json = serde_json::to_string(&new_high_water).unwrap_or_else(|_| "{}".to_string());
 
-    // Upsert the session entry with the new high-water value.
-    let idx_opt = state.llm_session_index.get(session_id).copied();
+    // Upsert the persona entry with the new high-water value.
+    let idx_opt = state.llm_session_index.get(persona).copied();
     if let Some(idx) = idx_opt {
         apply_and_persist(&mut state, |s| {
             s.crdt.doc.llm_sessions[idx]
@@ -179,8 +177,8 @@ pub fn assemble_and_advance_session(session_id: &str) -> Vec<String> {
     } else {
         let scope_str = scope_filter.to_scope_str();
         let entry: JsonValue = json!({
-            "session_id": session_id,
-            "persona_name": "",
+            "session_id": persona,
+            "persona_name": persona,
             "scope": scope_str,
             "high_water": new_hw_json,
         })
@@ -191,8 +189,8 @@ pub fn assemble_and_advance_session(session_id: &str) -> Vec<String> {
         state.llm_session_index = rebuild_llm_session_index(&state.crdt);
     }
 
-    // Observability: log event-log size and gap count across the session's
-    // target sleds (the scope actually assembled for this session).
+    // Observability: log event-log size and gap count across the persona's
+    // target sleds (the scope actually assembled for this persona).
     let total_entries = state
         .crdt
         .doc
@@ -211,7 +209,7 @@ pub fn assemble_and_advance_session(session_id: &str) -> Vec<String> {
         })
         .count();
     crate::slog!(
-        "[event-log] assemble session={session_id} sled_entries={total_entries} gap_count={gap_count}"
+        "[event-log] assemble persona={persona} sled_entries={total_entries} gap_count={gap_count}"
     );
 
     // Render each new event as a compact audit line; gap sentinels get a

server/src/crdt_state/read.rs

@@ -33,6 +33,8 @@ pub struct CrdtItemDump {
     pub is_deleted: bool,
     /// Origin JSON string, or `None` for items that pre-date story 1088.
     pub origin: Option<String>,
+    /// Explicit item type register, or `None` when unset (infer from story_id prefix).
+    pub item_type: Option<String>,
 }
 
 /// Top-level debug dump of the in-memory CRDT state.
@@ -162,6 +164,10 @@ pub fn dump_crdt_state(story_id_filter: Option<&str>) -> CrdtStateDump {
             JsonValue::String(s) if !s.is_empty() => Some(s),
             _ => None,
         };
+        let item_type = match item_crdt.item_type.view() {
+            JsonValue::String(s) if !s.is_empty() => Some(s),
+            _ => None,
+        };
 
         let content_index = op.id.iter().map(|b| format!("{b:02x}")).collect::<String>();
 
@@ -177,6 +183,7 @@ pub fn dump_crdt_state(story_id_filter: Option<&str>) -> CrdtStateDump {
             content_index,
             is_deleted: op.is_deleted,
             origin,
+            item_type,
         });
     }
 

server/src/event_log/mod.rs

@@ -66,6 +66,15 @@ pub fn log_transition_event(fired: &crate::pipeline_state::TransitionFired) {
         to_stage,
         pipeline_event,
     );
+
+    // Real-time push to per-persona WebSocket subscribers.
+    crate::pipeline_event_bus::broadcast(crate::pipeline_event_bus::BusEvent {
+        sled_id,
+        story_id: fired.story_id.0.clone(),
+        from_stage: crate::pipeline_state::stage_label(&fired.before).to_string(),
+        to_stage: crate::pipeline_state::stage_label(&fired.after).to_string(),
+        pipeline_event: crate::pipeline_state::event_label(&fired.event).to_string(),
+    });
 }
 
 /// Read all persisted events from the CRDT event log.
@@ -121,6 +130,7 @@ pub fn spawn_event_log_subscriber() {
         loop {
             match rx.recv().await {
                 Ok(fired) => {
+                    // log_transition_event also broadcasts to the pipeline_event_bus.
                     log_transition_event(&fired);
                     next_logical_seq += 1;
                 }

server/src/gateway/mod.rs

@@ -4,6 +4,9 @@
 //! Business logic lives in `service::gateway`, HTTP handlers in `http::gateway`.
 //! This file contains only the `run` entrypoint and `build_gateway_route` wiring.
 
+/// Gateway rebuild — builds the new binary and launches the detached trampoline.
+pub mod rebuild;
+
 use crate::http::gateway::*;
 use crate::rebuild::ShutdownReason;
 use crate::service::gateway::{self, GatewayState};
@@ -62,11 +65,25 @@ pub fn build_gateway_route(state_arc: Arc<GatewayState>) -> impl poem::Endpoint
             "/gateway/agents/:id/assign",
             poem::post(gateway_assign_agent_handler),
         )
+        // Binary self-update: serve the gateway binary so sleds can download it.
+        .at(
+            "/api/huskies-binary",
+            poem::get(crate::http::serve_binary_handler),
+        )
         .data(state_arc)
 }
 
 /// Start the gateway HTTP server. This is the entry point when `--gateway` is used.
 pub async fn run(config_path: &Path, port: u16) -> Result<(), std::io::Error> {
+    // Enforce one-active-gateway invariant: acquire an exclusive flock on the
+    // pidfile before doing anything else.  A second gateway start while one is
+    // running will fail here with a clear error.  The flock is held for the
+    // lifetime of `_pidfile_guard`; it is released automatically when this
+    // process exits, allowing the next gateway (spawned by the trampoline) to
+    // acquire it.
+    let _pidfile_guard =
+        crate::pidfile::acquire_gateway_pidfile().map_err(std::io::Error::other)?;
+
     let config_dir = config_path
         .parent()
         .unwrap_or(std::path::Path::new("."))
@@ -106,17 +123,9 @@ pub async fn run(config_path: &Path, port: u16) -> Result<(), std::io::Error> {
     }
 
     // Spawn the Matrix bot if `.huskies/bot.toml` exists in the config directory.
-    let gateway_project_urls: std::collections::BTreeMap<String, String> = state_arc
-        .projects
-        .read()
-        .await
-        .iter()
-        .filter_map(|(name, entry)| entry.url.as_ref().map(|u| (name.clone(), u.clone())))
-        .collect();
     let (bot_abort, bot_shutdown_tx) = gateway::io::spawn_gateway_bot(
         &config_dir,
         Arc::clone(&state_arc.active_project),
-        gateway_project_urls,
         Arc::clone(&state_arc.projects),
         port,
         Some(state_arc.event_tx.clone()),

server/src/gateway/rebuild.rs

@@ -0,0 +1,115 @@
+//! Gateway rebuild — builds the new huskies binary and hands off to the trampoline.
+//!
+//! The trampoline is spawned as a detached process (new Unix session) so that it
+//! survives the gateway's own death.  On success the gateway continues running
+//! until the trampoline kills it; the new gateway then posts "gateway X.Y.Z ready".
+
+use std::path::Path;
+
+/// Build the huskies binary and launch the detached trampoline to swap the gateway.
+///
+/// Returns `Err(message)` (shown to the user in chat) if the build or trampoline
+/// launch fails.  On success returns `Ok(())` — the trampoline is now running
+/// in a detached process and will kill this gateway and replace it with the new
+/// binary within 10 s.
+pub async fn rebuild_gateway(config_dir: &Path, gateway_port: u16) -> Result<(), String> {
+    let manifest_dir = std::path::Path::new(env!("CARGO_MANIFEST_DIR"));
+    let workspace_root = manifest_dir
+        .parent()
+        .ok_or("cannot determine workspace root from CARGO_MANIFEST_DIR")?;
+
+    crate::slog!(
+        "[gateway-rebuild] Building from workspace root: {}",
+        workspace_root.display()
+    );
+
+    // Rebuild the frontend bundle so rust-embed picks up the latest assets.
+    let frontend_dir = workspace_root.join("frontend");
+    if frontend_dir.join("package.json").exists() {
+        crate::slog!("[gateway-rebuild] Building frontend");
+        let fe_output = tokio::task::spawn_blocking({
+            let dir = frontend_dir.clone();
+            move || {
+                std::process::Command::new("npm")
+                    .args(["run", "build"])
+                    .current_dir(&dir)
+                    .output()
+            }
+        })
+        .await
+        .map_err(|e| format!("frontend build task panicked: {e}"))?
+        .map_err(|e| format!("failed to run npm run build: {e}"))?;
+
+        if !fe_output.status.success() {
+            let stderr = String::from_utf8_lossy(&fe_output.stderr);
+            return Err(format!("Frontend build failed:\n{stderr}"));
+        }
+        crate::slog!("[gateway-rebuild] Frontend build succeeded");
+    }
+
+    // Build the server binary matching the current profile.
+    let build_args: Vec<&str> = if cfg!(debug_assertions) {
+        vec!["build", "-p", "huskies"]
+    } else {
+        vec!["build", "--release", "-p", "huskies"]
+    };
+    crate::slog!("[gateway-rebuild] cargo {}", build_args.join(" "));
+
+    let output = tokio::task::spawn_blocking({
+        let root = workspace_root.to_path_buf();
+        move || {
+            std::process::Command::new("cargo")
+                .args(&build_args)
+                .current_dir(&root)
+                .output()
+        }
+    })
+    .await
+    .map_err(|e| format!("build task panicked: {e}"))?
+    .map_err(|e| format!("failed to run cargo build: {e}"))?;
+
+    if !output.status.success() {
+        let stderr = String::from_utf8_lossy(&output.stderr);
+        crate::slog!("[gateway-rebuild] Build failed");
+        return Err(format!("Build failed:\n{stderr}"));
+    }
+
+    crate::slog!("[gateway-rebuild] Build succeeded — launching trampoline");
+
+    // Paths for the new and old binaries.
+    let new_binary = if cfg!(debug_assertions) {
+        workspace_root.join("target/debug/huskies")
+    } else {
+        workspace_root.join("target/release/huskies")
+    };
+
+    let old_binary =
+        std::env::current_exe().map_err(|e| format!("cannot locate current binary: {e}"))?;
+
+    let huskies_dir = config_dir.join(".huskies");
+    std::fs::create_dir_all(&huskies_dir)
+        .map_err(|e| format!("cannot create .huskies dir: {e}"))?;
+    let backup_binary = huskies_dir.join("huskies_backup");
+
+    // Current gateway args (skip argv[0]).
+    let gateway_args: Vec<String> = std::env::args().skip(1).collect();
+
+    let job = crate::trampoline::TrampolineJob {
+        gateway_pid: std::process::id(),
+        new_binary_path: new_binary,
+        old_binary_path: old_binary,
+        backup_binary_path: backup_binary,
+        gateway_args,
+        health_url: format!("http://127.0.0.1:{gateway_port}/api/gateway"),
+    };
+
+    let job_path = huskies_dir.join("trampoline.json");
+    crate::trampoline::write_job_atomic(&job, &job_path)?;
+
+    let exe = std::env::current_exe()
+        .map_err(|e| format!("cannot locate current binary for trampoline: {e}"))?;
+    crate::trampoline::spawn_detached_trampoline(&exe, &job_path)?;
+
+    crate::slog!("[gateway-rebuild] Trampoline launched — gateway will be replaced shortly");
+    Ok(())
+}

server/src/gateway_relay.rs

@@ -271,4 +271,209 @@ mod tests {
         spawn_relay_task(String::new(), "test".into(), broadcaster, client);
         // If we reach here without panic, the guard worked.
     }
+
+    /// End-to-end: a `TransitionFired`-equivalent event published on the sled's
+    /// broadcaster must reach the gateway's [`GatewayStatusEvent`] broadcast
+    /// within 1 second.
+    ///
+    /// Spins up a real poem HTTP server (token endpoint + WS event-push endpoint),
+    /// spawns the relay task pointing at it, fires a [`StatusEvent::StageTransition`],
+    /// and asserts the gateway broadcast receives the matching [`StoredEvent`].
+    #[tokio::test]
+    async fn relay_end_to_end_stage_transition_reaches_gateway_broadcast() {
+        use crate::http::gateway::{gateway_event_push_handler, gateway_generate_token_handler};
+        use crate::service::gateway::{GatewayConfig, GatewayState, ProjectEntry};
+        use poem::EndpointExt as _;
+        use poem::listener::TcpAcceptor;
+        use std::collections::BTreeMap;
+        use std::path::PathBuf;
+        use tokio::net::TcpListener;
+
+        crate::crdt_state::init_for_test();
+
+        // Gateway state: one project whose name matches the relay project name.
+        let mut projects = BTreeMap::new();
+        projects.insert(
+            "sled-test".to_string(),
+            ProjectEntry::with_url("http://sled-test:3001"),
+        );
+        let config = GatewayConfig {
+            projects,
+            sled_tokens: BTreeMap::new(),
+        };
+        let state = Arc::new(GatewayState::new(config, PathBuf::new(), 9000).unwrap());
+
+        // Subscribe before the relay connects so the event is not missed.
+        let mut gw_rx = state.event_tx.subscribe();
+
+        // Start a poem server on an ephemeral loopback port exposing the real
+        // token and event-push handlers.
+        let listener = TcpListener::bind("127.0.0.1:0").await.unwrap();
+        let addr = listener.local_addr().unwrap();
+        let gateway_url = format!("http://127.0.0.1:{}", addr.port());
+
+        let route = poem::Route::new()
+            .at(
+                "/gateway/tokens",
+                poem::post(gateway_generate_token_handler),
+            )
+            .at(
+                "/gateway/events/push",
+                poem::get(gateway_event_push_handler),
+            )
+            .data(state.clone());
+
+        tokio::spawn(async move {
+            let acceptor = TcpAcceptor::from_tokio(listener).unwrap();
+            let _ = poem::Server::new_with_acceptor(acceptor).run(route).await;
+        });
+
+        // Spawn the relay task pointing at our in-process gateway server.
+        let broadcaster = Arc::new(StatusBroadcaster::new());
+        spawn_relay_task(
+            gateway_url,
+            "sled-test".into(),
+            Arc::clone(&broadcaster),
+            reqwest::Client::new(),
+        );
+
+        // Give the relay time to obtain a join token, connect the WebSocket,
+        // and enter its event-receive loop before we publish.
+        tokio::time::sleep(std::time::Duration::from_millis(200)).await;
+
+        // Publish a stage transition on the sled side.
+        broadcaster.publish(StatusEvent::StageTransition {
+            story_id: "42_story_relay_e2e".into(),
+            story_name: "Relay E2E".into(),
+            from_stage: "1_backlog".into(),
+            to_stage: "2_current".into(),
+        });
+
+        // The event must arrive at the gateway broadcast within 1 second.
+        let received = tokio::time::timeout(std::time::Duration::from_secs(1), gw_rx.recv())
+            .await
+            .expect("timed out: event did not arrive at gateway broadcast within 1 s")
+            .expect("gateway broadcast channel closed unexpectedly");
+
+        assert_eq!(received.project, "sled-test");
+        assert!(
+            matches!(
+                received.event,
+                StoredEvent::StageTransition { ref story_id, .. } if story_id == "42_story_relay_e2e"
+            ),
+            "unexpected gateway event: {:?}",
+            received.event
+        );
+    }
+
+    /// Extends `relay_end_to_end_stage_transition_reaches_gateway_broadcast` to
+    /// cover the full wiring path: `project_docker_run_args` embeds
+    /// `HUSKIES_GATEWAY_URL` in the sled's argv; when that URL is used to start
+    /// the relay, a transition fired inside the sled reaches the gateway's CRDT
+    /// event_log within 1 second.
+    #[tokio::test]
+    async fn project_docker_run_args_gateway_url_wires_relay() {
+        use crate::chat::transport::matrix::new_project::project_docker_run_args;
+        use crate::http::gateway::{gateway_event_push_handler, gateway_generate_token_handler};
+        use crate::service::gateway::{GatewayConfig, GatewayState, ProjectEntry};
+        use poem::EndpointExt as _;
+        use poem::listener::TcpAcceptor;
+        use std::collections::BTreeMap;
+        use std::path::PathBuf;
+        use tokio::net::TcpListener;
+
+        crate::crdt_state::init_for_test();
+
+        // Spin up an in-process gateway server on an ephemeral port so we have
+        // a real URL to embed in the docker run args.
+        let listener = TcpListener::bind("127.0.0.1:0").await.unwrap();
+        let addr = listener.local_addr().unwrap();
+        let gateway_url = format!("http://127.0.0.1:{}", addr.port());
+
+        // project_docker_run_args embeds the gateway URL: this is the production
+        // code path that sets HUSKIES_GATEWAY_URL on the sled container.
+        let docker_args = project_docker_run_args(
+            "huskies-sled-relay",
+            3200,
+            2300,
+            "ssh-ed25519 AAAA...",
+            "Test User",
+            "test@example.com",
+            None,
+            &gateway_url,
+        );
+
+        // Extract the injected URL exactly as the sled would read it from its env.
+        let injected_url = docker_args
+            .windows(2)
+            .find(|w| w[0] == "-e" && w[1].starts_with("HUSKIES_GATEWAY_URL="))
+            .map(|w| w[1].trim_start_matches("HUSKIES_GATEWAY_URL=").to_string())
+            .expect("project_docker_run_args must inject HUSKIES_GATEWAY_URL");
+
+        assert_eq!(injected_url, gateway_url, "injected URL must match input");
+
+        // Set up gateway state for the relay project.
+        let mut projects = BTreeMap::new();
+        projects.insert(
+            "sled-relay".to_string(),
+            ProjectEntry::with_url("http://sled-relay:3001"),
+        );
+        let config = GatewayConfig {
+            projects,
+            sled_tokens: BTreeMap::new(),
+        };
+        let state = Arc::new(GatewayState::new(config, PathBuf::new(), 9001).unwrap());
+        let mut gw_rx = state.event_tx.subscribe();
+
+        let route = poem::Route::new()
+            .at(
+                "/gateway/tokens",
+                poem::post(gateway_generate_token_handler),
+            )
+            .at(
+                "/gateway/events/push",
+                poem::get(gateway_event_push_handler),
+            )
+            .data(state.clone());
+
+        tokio::spawn(async move {
+            let acceptor = TcpAcceptor::from_tokio(listener).unwrap();
+            let _ = poem::Server::new_with_acceptor(acceptor).run(route).await;
+        });
+
+        // Spawn the relay using the URL extracted from the docker run args —
+        // this simulates what the sled does when it reads HUSKIES_GATEWAY_URL
+        // from its container environment.
+        let broadcaster = Arc::new(StatusBroadcaster::new());
+        spawn_relay_task(
+            injected_url,
+            "sled-relay".into(),
+            Arc::clone(&broadcaster),
+            reqwest::Client::new(),
+        );
+
+        tokio::time::sleep(std::time::Duration::from_millis(200)).await;
+
+        broadcaster.publish(StatusEvent::StageTransition {
+            story_id: "99_docker_args_relay".into(),
+            story_name: "Docker Args Relay".into(),
+            from_stage: "1_backlog".into(),
+            to_stage: "2_current".into(),
+        });
+
+        let received = tokio::time::timeout(std::time::Duration::from_secs(1), gw_rx.recv())
+            .await
+            .expect("timed out: event did not reach gateway within 1 s")
+            .expect("gateway broadcast channel closed unexpectedly");
+
+        assert_eq!(received.project, "sled-relay");
+        assert!(
+            matches!(
+                received.event,
+                StoredEvent::StageTransition { ref story_id, .. } if story_id == "99_docker_args_relay"
+            ),
+            "unexpected gateway event: {:?}",
+            received.event
+        );
+    }
 }

server/src/http/gateway/mcp.rs

@@ -26,6 +26,10 @@ const GATEWAY_TOOLS: &[&str] = &[
     // Handled at the gateway so the Matrix bot's perm_rx listener is used
     // rather than the container's (which has no interactive session attached).
     "prompt_permission",
+    // Binary self-update: gateway serves its own binary and triggers upgrade on sleds.
+    "upgrade_sled",
+    // One-shot container rebuild: build fresh image, swap container, preserve state.
+    "project_rebuild",
 ];
 
 /// Gateway tool definitions.
@@ -121,6 +125,45 @@ pub(crate) fn gateway_tool_definitions() -> Vec<Value> {
                 "properties": {}
             }
         }),
+        json!({
+            "name": "upgrade_sled",
+            "description": "Trigger a binary self-update on a project sled. The sled downloads the new binary from `source_url` (defaults to this gateway's /api/huskies-binary endpoint), atomically replaces its own executable, drains CRDT persistence so no ops are lost, and re-execs. Without `project`, upgrades the active project.",
+            "inputSchema": {
+                "type": "object",
+                "properties": {
+                    "project": {
+                        "type": "string",
+                        "description": "Name of the project sled to upgrade. Defaults to the currently active project."
+                    },
+                    "source_url": {
+                        "type": "string",
+                        "description": "HTTP URL of the binary to install (e.g. 'http://gateway:3000/api/huskies-binary'). Defaults to this gateway's own binary endpoint."
+                    }
+                }
+            }
+        }),
+        json!({
+            "name": "project_rebuild",
+            "description": "Rebuild a project's Docker image from its Dockerfile.fragment, swap the container, and preserve all CRDT and pipeline state. In-flight coder/merge work is drained before the swap; if not drainable within the timeout the command refuses. On success returns the new image hash and container ID.",
+            "inputSchema": {
+                "type": "object",
+                "properties": {
+                    "name": {
+                        "type": "string",
+                        "description": "Name of the project to rebuild (must exist in projects.toml with host_path set)."
+                    },
+                    "drain_timeout_secs": {
+                        "type": "integer",
+                        "description": "Seconds to wait for active agents to stop before rebuilding (default: 60). Pass 0 to skip the drain check."
+                    },
+                    "force": {
+                        "type": "boolean",
+                        "description": "If true, skip the drain check and rebuild immediately even if agents are running."
+                    }
+                },
+                "required": ["name"]
+            }
+        }),
     ]
 }
 
@@ -385,6 +428,8 @@ async fn handle_gateway_tool(
         "aggregate_pipeline_status" => handle_aggregate_pipeline_status_tool(state, id).await,
         "agents.list" => handle_agents_list_tool(id),
         "prompt_permission" => handle_prompt_permission_tool(params, state, id).await,
+        "upgrade_sled" => handle_upgrade_sled_tool(params, state, id).await,
+        "project_rebuild" => handle_project_rebuild_tool(params, state, id).await,
         _ => JsonRpcResponse::error(id, -32601, format!("Unknown gateway tool: {tool_name}")),
     }
 }
@@ -608,6 +653,7 @@ async fn handle_adopt_project_tool(
         None,
         None,
         Some(path_str),
+        false,
         &state.projects,
         &state.config_dir,
     )
@@ -768,6 +814,142 @@ fn handle_agents_list_tool(id: Option<Value>) -> JsonRpcResponse {
     )
 }
 
+/// Handle the `upgrade_sled` gateway tool.
+///
+/// Posts `{"source_url": "<url>"}` to the target sled's `/api/upgrade` endpoint,
+/// which triggers the sled to download the new binary, drain CRDT persistence,
+/// and re-exec.  Returns 202 text immediately — the sled connection will drop
+/// shortly after as `exec()` replaces the process.
+async fn handle_upgrade_sled_tool(
+    params: &Value,
+    state: &GatewayState,
+    id: Option<Value>,
+) -> JsonRpcResponse {
+    let args = params.get("arguments").unwrap_or(params);
+
+    // Resolve target project URL (explicit project arg or active project).
+    let project_name = args.get("project").and_then(|v| v.as_str());
+    let sled_url = if let Some(name) = project_name {
+        let projects = state.projects.read().await;
+        match projects.get(name).and_then(|e| e.url.clone()) {
+            Some(u) => u,
+            None => {
+                return JsonRpcResponse::error(
+                    id,
+                    -32602,
+                    format!("Project '{name}' not found or has no URL configured"),
+                );
+            }
+        }
+    } else {
+        match state.active_url().await {
+            Ok(u) => u,
+            Err(e) => return JsonRpcResponse::error(id, -32603, e.to_string()),
+        }
+    };
+
+    // Build the binary source URL: caller-supplied or this gateway's own endpoint.
+    let source_url = args
+        .get("source_url")
+        .and_then(|v| v.as_str())
+        .map(|s| s.to_string())
+        .unwrap_or_else(|| {
+            // Default: the gateway serves its own binary at /api/huskies-binary.
+            // Use the same host/port the gateway is bound to.
+            std::env::var("HUSKIES_GATEWAY_BINARY_URL")
+                .unwrap_or_else(|_| format!("http://gateway:{}/api/huskies-binary", state.port))
+        });
+
+    let upgrade_url = format!("{sled_url}/api/upgrade");
+    let body = serde_json::json!({ "source_url": source_url });
+
+    let active_name = project_name.map(|s| s.to_string()).unwrap_or_else(|| {
+        state
+            .active_project
+            .try_read()
+            .map(|g| g.clone())
+            .unwrap_or_default()
+    });
+
+    match state.client.post(&upgrade_url).json(&body).send().await {
+        Ok(resp) if resp.status().is_success() || resp.status().as_u16() == 202 => {
+            JsonRpcResponse::success(
+                id,
+                json!({
+                    "content": [{
+                        "type": "text",
+                        "text": format!(
+                            "Upgrade triggered on '{active_name}'. The sled is downloading the new binary from {source_url} and will re-exec momentarily."
+                        )
+                    }]
+                }),
+            )
+        }
+        Ok(resp) => JsonRpcResponse::error(
+            id,
+            -32603,
+            format!(
+                "Sled returned HTTP {} for upgrade request to {upgrade_url}",
+                resp.status()
+            ),
+        ),
+        Err(e) => JsonRpcResponse::error(
+            id,
+            -32603,
+            format!("Failed to send upgrade request to {upgrade_url}: {e}"),
+        ),
+    }
+}
+
+/// Handle the `project_rebuild` gateway tool.
+///
+/// Rebuilds a project's Docker image, swaps the container, and preserves all
+/// CRDT and pipeline state.  Delegates to `handle_project_rebuild` in the chat
+/// transport module so the logic is shared between the chat and MCP entry points.
+async fn handle_project_rebuild_tool(
+    params: &Value,
+    state: &GatewayState,
+    id: Option<Value>,
+) -> JsonRpcResponse {
+    use crate::chat::transport::matrix::project_rebuild::handle_project_rebuild;
+
+    let args = params.get("arguments").unwrap_or(params);
+    let name = args
+        .get("name")
+        .and_then(|v| v.as_str())
+        .unwrap_or("")
+        .trim();
+
+    if name.is_empty() {
+        return JsonRpcResponse::error(id, -32602, "missing required parameter: name".into());
+    }
+
+    let drain_timeout_secs = args
+        .get("drain_timeout_secs")
+        .and_then(|v| v.as_u64())
+        .unwrap_or(60);
+    let force = args.get("force").and_then(|v| v.as_bool()).unwrap_or(false);
+
+    let result = handle_project_rebuild(
+        name,
+        drain_timeout_secs,
+        force,
+        &state.projects,
+        &state.config_dir,
+    )
+    .await;
+
+    JsonRpcResponse::success(
+        id,
+        json!({
+            "content": [{
+                "type": "text",
+                "text": result
+            }]
+        }),
+    )
+}
+
 /// Handle the `pipeline.get` read-RPC — returns per-project item lists in the
 /// shape expected by the gateway web UI:
 /// `{ "active": "...", "projects": { "name": { "active": [...], "backlog_count": N } } }`.
@@ -884,6 +1066,7 @@ mod tests {
             None,
             None,
             Some(file_path),
+            false,
             &store,
             dir.path(),
         )

server/src/http/mcp/diagnostics/mod.rs

@@ -115,6 +115,7 @@ pub(crate) fn tool_dump_crdt(args: &Value) -> Result<String, String> {
                 "content_index": item.content_index,
                 "is_deleted": item.is_deleted,
                 "origin": item.origin,
+                "item_type": item.item_type,
             })
         })
         .collect();

server/src/http/mcp/dispatch.rs

@@ -102,9 +102,14 @@ pub async fn dispatch_tool_call(
         "move_story" => diagnostics::tool_move_story(&args, ctx),
         // Unblock story
         "unblock_story" => story_tools::tool_unblock_story(&args, ctx),
+        // Convert work-item type in place (story 1141)
+        "convert_item_type" => story_tools::tool_convert_item_type(&args, ctx),
         // Freeze / unfreeze story
         "freeze_story" => story_tools::tool_freeze_story(&args, ctx),
         "unfreeze_story" => story_tools::tool_unfreeze_story(&args, ctx),
+        // Worktree-sandboxed file editing (replaces Claude's built-in Edit/Write for coder agents)
+        "edit" => shell_tools::tool_edit(&args, ctx),
+        "write" => shell_tools::tool_write(&args, ctx),
         // Shell command execution
         "run_command" => shell_tools::tool_run_command(&args, ctx).await,
         "run_tests" => shell_tools::tool_run_tests(&args, ctx).await,

server/src/http/mcp/shell_tools/file_tools.rs

@@ -0,0 +1,452 @@
+//! MCP file-editing tools: `edit` and `write`.
+//!
+//! These are worktree-sandboxed equivalents of Claude's built-in `Edit` and
+//! `Write` tools.  All paths must canonicalize to inside `.huskies/worktrees/`
+//! so agents cannot write to the master working tree.
+
+use crate::http::context::AppContext;
+use serde_json::Value;
+use std::path::{Path, PathBuf};
+
+/// Validate that `file_path` is an absolute path whose nearest existing
+/// ancestor lies inside the project's `.huskies/worktrees/` directory.
+///
+/// Unlike [`crate::service::shell::io::validate_working_dir`], the target file
+/// itself need not exist (write creates it), so we walk up to the first
+/// existing ancestor before canonicalising.
+///
+/// Returns the original (non-canonicalized) `PathBuf` on success so the
+/// caller can use it directly for I/O.
+///
+/// # Errors
+/// Returns a `String` error naming both the worktrees root and the offending
+/// path, matching the style of the `run_command` guard.
+pub(super) fn validate_worktree_file_path(
+    file_path: &str,
+    ctx: &AppContext,
+) -> Result<PathBuf, String> {
+    let path = PathBuf::from(file_path);
+
+    if !path.is_absolute() {
+        return Err(format!(
+            "file_path must be an absolute path, got: {file_path}"
+        ));
+    }
+
+    let project_root = ctx.services.agents.get_project_root(&ctx.state)?;
+    let worktrees_root = project_root.join(".huskies").join("worktrees");
+
+    if !worktrees_root.exists() {
+        return Err(format!(
+            "No worktrees directory found; file_path must be inside {worktrees_root:?}, got: {file_path}"
+        ));
+    }
+
+    let canonical_wt = worktrees_root
+        .canonicalize()
+        .map_err(|e| format!("Cannot canonicalize worktrees root: {e}"))?;
+
+    // Walk up to find the deepest existing ancestor so we can canonicalize it.
+    let canonical_ancestor = find_existing_ancestor(&path)
+        .ok_or_else(|| format!("file_path has no accessible ancestor on disk: {file_path}"))?
+        .canonicalize()
+        .map_err(|e| format!("Cannot canonicalize path: {e}"))?;
+
+    if !canonical_ancestor.starts_with(&canonical_wt) {
+        return Err(format!(
+            "file_path must be inside worktrees root {worktrees_root:?}. Got: {file_path}"
+        ));
+    }
+
+    Ok(path)
+}
+
+/// Return the deepest ancestor of `p` (inclusive) that exists on disk.
+fn find_existing_ancestor(p: &Path) -> Option<&Path> {
+    let mut current = p;
+    loop {
+        if current.exists() {
+            return Some(current);
+        }
+        current = current.parent()?;
+    }
+}
+
+/// Replace `old_string` with `new_string` in a file inside the agent's worktree.
+///
+/// Mirrors Claude's built-in `Edit` tool with worktree path validation.
+/// By default replaces only the first occurrence; pass `replace_all: true`
+/// to replace every occurrence.
+pub(crate) fn tool_edit(args: &Value, ctx: &AppContext) -> Result<String, String> {
+    let file_path = args
+        .get("file_path")
+        .and_then(|v| v.as_str())
+        .ok_or("Missing required argument: file_path")?;
+    let old_string = args
+        .get("old_string")
+        .and_then(|v| v.as_str())
+        .ok_or("Missing required argument: old_string")?;
+    let new_string = args
+        .get("new_string")
+        .and_then(|v| v.as_str())
+        .ok_or("Missing required argument: new_string")?;
+    let replace_all = args
+        .get("replace_all")
+        .and_then(|v| v.as_bool())
+        .unwrap_or(false);
+
+    let path = validate_worktree_file_path(file_path, ctx)?;
+
+    if !path.exists() {
+        return Err(format!("file_path does not exist: {file_path}"));
+    }
+
+    let content =
+        std::fs::read_to_string(&path).map_err(|e| format!("Failed to read {file_path}: {e}"))?;
+
+    if !content.contains(old_string) {
+        return Err(format!(
+            "old_string not found in {file_path}: {old_string:?}"
+        ));
+    }
+
+    let new_content = if replace_all {
+        content.replace(old_string, new_string)
+    } else {
+        content.replacen(old_string, new_string, 1)
+    };
+
+    std::fs::write(&path, &new_content).map_err(|e| format!("Failed to write {file_path}: {e}"))?;
+
+    Ok(format!("Edited {file_path}"))
+}
+
+/// Write `content` to a file inside the agent's worktree, creating the file
+/// (and any missing parent directories) if necessary.
+///
+/// Mirrors Claude's built-in `Write` tool with worktree path validation.
+pub(crate) fn tool_write(args: &Value, ctx: &AppContext) -> Result<String, String> {
+    let file_path = args
+        .get("file_path")
+        .and_then(|v| v.as_str())
+        .ok_or("Missing required argument: file_path")?;
+    let content = args
+        .get("content")
+        .and_then(|v| v.as_str())
+        .ok_or("Missing required argument: content")?;
+
+    let path = validate_worktree_file_path(file_path, ctx)?;
+
+    if let Some(parent) = path.parent() {
+        std::fs::create_dir_all(parent)
+            .map_err(|e| format!("Failed to create parent dirs for {file_path}: {e}"))?;
+    }
+
+    std::fs::write(&path, content).map_err(|e| format!("Failed to write {file_path}: {e}"))?;
+
+    Ok(format!("Written {file_path}"))
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::http::test_helpers::test_ctx;
+    use serde_json::json;
+
+    fn make_worktree(tmp: &tempfile::TempDir, name: &str) -> PathBuf {
+        let wt = tmp.path().join(".huskies").join("worktrees").join(name);
+        std::fs::create_dir_all(&wt).unwrap();
+        wt
+    }
+
+    // ── validate_worktree_file_path ───────────────────────────────────
+
+    #[test]
+    fn validate_rejects_relative_path() {
+        let tmp = tempfile::tempdir().unwrap();
+        make_worktree(&tmp, "42_test");
+        let ctx = test_ctx(tmp.path());
+        let result = validate_worktree_file_path("relative/path.rs", &ctx);
+        assert!(result.is_err());
+        assert!(result.unwrap_err().contains("absolute"));
+    }
+
+    #[test]
+    fn validate_rejects_path_outside_worktree() {
+        let tmp = tempfile::tempdir().unwrap();
+        make_worktree(&tmp, "42_test");
+        let ctx = test_ctx(tmp.path());
+        // /workspace/server/foo.rs is outside .huskies/worktrees/
+        let outside = tmp.path().join("server").join("foo.rs");
+        let result = validate_worktree_file_path(outside.to_str().unwrap(), &ctx);
+        assert!(result.is_err(), "expected rejection, got ok");
+        let msg = result.unwrap_err();
+        assert!(
+            msg.contains("worktrees"),
+            "error should name worktrees root: {msg}"
+        );
+    }
+
+    #[test]
+    fn validate_accepts_existing_file_inside_worktree() {
+        let tmp = tempfile::tempdir().unwrap();
+        let wt = make_worktree(&tmp, "42_test");
+        let file = wt.join("foo.rs");
+        std::fs::write(&file, "content").unwrap();
+        let ctx = test_ctx(tmp.path());
+        let result = validate_worktree_file_path(file.to_str().unwrap(), &ctx);
+        assert!(result.is_ok(), "expected ok, got: {:?}", result);
+    }
+
+    #[test]
+    fn validate_accepts_nonexistent_file_inside_worktree() {
+        let tmp = tempfile::tempdir().unwrap();
+        let wt = make_worktree(&tmp, "42_test");
+        // File doesn't exist yet — parent dir does
+        let file = wt.join("new_file.rs");
+        let ctx = test_ctx(tmp.path());
+        let result = validate_worktree_file_path(file.to_str().unwrap(), &ctx);
+        assert!(
+            result.is_ok(),
+            "expected ok for new file, got: {:?}",
+            result
+        );
+    }
+
+    #[test]
+    fn validate_rejects_no_worktrees_dir() {
+        let tmp = tempfile::tempdir().unwrap();
+        // Do NOT create worktrees dir
+        let ctx = test_ctx(tmp.path());
+        let path = tmp.path().join("file.rs");
+        let result = validate_worktree_file_path(path.to_str().unwrap(), &ctx);
+        assert!(result.is_err());
+        assert!(result.unwrap_err().contains("worktrees"));
+    }
+
+    // ── tool_edit ─────────────────────────────────────────────────────
+
+    /// AC3(a) — path outside worktree is rejected
+    #[test]
+    fn tool_edit_rejects_path_outside_worktree() {
+        let tmp = tempfile::tempdir().unwrap();
+        make_worktree(&tmp, "42_test");
+        // Create a file outside worktrees
+        let outside = tmp.path().join("server");
+        std::fs::create_dir_all(&outside).unwrap();
+        let outside_file = outside.join("foo.rs");
+        std::fs::write(&outside_file, "old content").unwrap();
+        let ctx = test_ctx(tmp.path());
+
+        let result = tool_edit(
+            &json!({
+                "file_path": outside_file.to_str().unwrap(),
+                "old_string": "old content",
+                "new_string": "new content"
+            }),
+            &ctx,
+        );
+        assert!(result.is_err(), "expected rejection");
+        // Master file unchanged
+        let content = std::fs::read_to_string(&outside_file).unwrap();
+        assert_eq!(content, "old content", "master file must be unchanged");
+    }
+
+    /// AC3(b) — path inside worktree succeeds
+    #[test]
+    fn tool_edit_accepts_path_inside_worktree() {
+        let tmp = tempfile::tempdir().unwrap();
+        let wt = make_worktree(&tmp, "42_test");
+        let file = wt.join("foo.rs");
+        std::fs::write(&file, "fn old_fn() {}").unwrap();
+        let ctx = test_ctx(tmp.path());
+
+        let result = tool_edit(
+            &json!({
+                "file_path": file.to_str().unwrap(),
+                "old_string": "old_fn",
+                "new_string": "new_fn"
+            }),
+            &ctx,
+        );
+        assert!(result.is_ok(), "expected ok, got: {:?}", result);
+        let content = std::fs::read_to_string(&file).unwrap();
+        assert!(content.contains("new_fn"));
+        assert!(!content.contains("old_fn"));
+    }
+
+    #[test]
+    fn tool_edit_replace_all_replaces_every_occurrence() {
+        let tmp = tempfile::tempdir().unwrap();
+        let wt = make_worktree(&tmp, "43_test");
+        let file = wt.join("multi.rs");
+        std::fs::write(&file, "foo foo foo").unwrap();
+        let ctx = test_ctx(tmp.path());
+
+        tool_edit(
+            &json!({
+                "file_path": file.to_str().unwrap(),
+                "old_string": "foo",
+                "new_string": "bar",
+                "replace_all": true
+            }),
+            &ctx,
+        )
+        .unwrap();
+
+        let content = std::fs::read_to_string(&file).unwrap();
+        assert_eq!(content, "bar bar bar");
+    }
+
+    #[test]
+    fn tool_edit_default_replaces_first_occurrence_only() {
+        let tmp = tempfile::tempdir().unwrap();
+        let wt = make_worktree(&tmp, "44_test");
+        let file = wt.join("single.rs");
+        std::fs::write(&file, "foo foo foo").unwrap();
+        let ctx = test_ctx(tmp.path());
+
+        tool_edit(
+            &json!({
+                "file_path": file.to_str().unwrap(),
+                "old_string": "foo",
+                "new_string": "bar"
+            }),
+            &ctx,
+        )
+        .unwrap();
+
+        let content = std::fs::read_to_string(&file).unwrap();
+        assert_eq!(content, "bar foo foo");
+    }
+
+    #[test]
+    fn tool_edit_fails_when_old_string_not_found() {
+        let tmp = tempfile::tempdir().unwrap();
+        let wt = make_worktree(&tmp, "45_test");
+        let file = wt.join("missing.rs");
+        std::fs::write(&file, "hello world").unwrap();
+        let ctx = test_ctx(tmp.path());
+
+        let result = tool_edit(
+            &json!({
+                "file_path": file.to_str().unwrap(),
+                "old_string": "not present",
+                "new_string": "x"
+            }),
+            &ctx,
+        );
+        assert!(result.is_err());
+        assert!(result.unwrap_err().contains("not found"));
+    }
+
+    #[test]
+    fn tool_edit_fails_when_file_does_not_exist() {
+        let tmp = tempfile::tempdir().unwrap();
+        let wt = make_worktree(&tmp, "46_test");
+        let ctx = test_ctx(tmp.path());
+
+        let result = tool_edit(
+            &json!({
+                "file_path": wt.join("ghost.rs").to_str().unwrap(),
+                "old_string": "x",
+                "new_string": "y"
+            }),
+            &ctx,
+        );
+        assert!(result.is_err());
+        assert!(result.unwrap_err().contains("does not exist"));
+    }
+
+    // ── tool_write ────────────────────────────────────────────────────
+
+    #[test]
+    fn tool_write_rejects_path_outside_worktree() {
+        let tmp = tempfile::tempdir().unwrap();
+        make_worktree(&tmp, "42_test");
+        let outside = tmp.path().join("master_file.rs");
+        let ctx = test_ctx(tmp.path());
+
+        let result = tool_write(
+            &json!({
+                "file_path": outside.to_str().unwrap(),
+                "content": "evil"
+            }),
+            &ctx,
+        );
+        assert!(result.is_err(), "expected rejection");
+        assert!(!outside.exists(), "master file must not be created");
+    }
+
+    #[test]
+    fn tool_write_creates_new_file_inside_worktree() {
+        let tmp = tempfile::tempdir().unwrap();
+        let wt = make_worktree(&tmp, "47_test");
+        let file = wt.join("new.rs");
+        let ctx = test_ctx(tmp.path());
+
+        tool_write(
+            &json!({
+                "file_path": file.to_str().unwrap(),
+                "content": "pub fn hello() {}"
+            }),
+            &ctx,
+        )
+        .unwrap();
+
+        let content = std::fs::read_to_string(&file).unwrap();
+        assert_eq!(content, "pub fn hello() {}");
+    }
+
+    #[test]
+    fn tool_write_overwrites_existing_file() {
+        let tmp = tempfile::tempdir().unwrap();
+        let wt = make_worktree(&tmp, "48_test");
+        let file = wt.join("existing.rs");
+        std::fs::write(&file, "old").unwrap();
+        let ctx = test_ctx(tmp.path());
+
+        tool_write(
+            &json!({
+                "file_path": file.to_str().unwrap(),
+                "content": "new"
+            }),
+            &ctx,
+        )
+        .unwrap();
+
+        let content = std::fs::read_to_string(&file).unwrap();
+        assert_eq!(content, "new");
+    }
+
+    #[test]
+    fn tool_write_creates_parent_dirs() {
+        let tmp = tempfile::tempdir().unwrap();
+        let wt = make_worktree(&tmp, "49_test");
+        let file = wt.join("deep").join("nested").join("file.rs");
+        let ctx = test_ctx(tmp.path());
+
+        tool_write(
+            &json!({
+                "file_path": file.to_str().unwrap(),
+                "content": "deep content"
+            }),
+            &ctx,
+        )
+        .unwrap();
+
+        let content = std::fs::read_to_string(&file).unwrap();
+        assert_eq!(content, "deep content");
+    }
+
+    #[test]
+    fn tool_write_missing_content_arg_errors() {
+        let tmp = tempfile::tempdir().unwrap();
+        make_worktree(&tmp, "50_test");
+        let ctx = test_ctx(tmp.path());
+
+        let result = tool_write(&json!({"file_path": "/some/path"}), &ctx);
+        assert!(result.is_err());
+        assert!(result.unwrap_err().contains("content"));
+    }
+}

server/src/http/mcp/shell_tools/mod.rs

@@ -1,12 +1,14 @@
-//! MCP shell tools — run commands, execute tests, and stream output via MCP.
+//! MCP shell tools — run commands, execute tests, edit and write files.
 //!
 //! This file is a thin adapter: it deserialises MCP payloads, delegates to
 //! `crate::service::shell` for all business logic, and serialises responses.
 
 mod exec;
+mod file_tools;
 mod script;
 
 pub(crate) use exec::tool_run_command;
+pub(crate) use file_tools::{tool_edit, tool_write};
 pub(crate) use script::{
     tool_get_test_result, tool_run_build, tool_run_check, tool_run_lint, tool_run_tests,
 };

server/src/http/mcp/story_tools/mod.rs

@@ -69,7 +69,7 @@ pub(crate) use epic::{tool_create_epic, tool_list_epics, tool_show_epic};
 pub(crate) use refactor::{tool_create_refactor, tool_list_refactors};
 pub(crate) use spike::tool_create_spike;
 pub(crate) use story::{
-    tool_accept_story, tool_create_story, tool_delete_story, tool_freeze_story,
-    tool_get_pipeline_status, tool_list_upcoming, tool_purge_story, tool_unblock_story,
-    tool_unfreeze_story, tool_update_story, tool_validate_stories,
+    tool_accept_story, tool_convert_item_type, tool_create_story, tool_delete_story,
+    tool_freeze_story, tool_get_pipeline_status, tool_list_upcoming, tool_purge_story,
+    tool_unblock_story, tool_unfreeze_story, tool_update_story, tool_validate_stories,
 };

server/src/http/mcp/story_tools/story/convert.rs

@@ -0,0 +1,178 @@
+//! MCP tool for converting a work item's type in place (story 1141).
+//!
+//! `convert_item_type` changes the type register of an existing CRDT item
+//! from any value to another (story ↔ bug ↔ spike ↔ refactor) without
+//! touching the story_id, ACs, epic association, or any other register.
+
+use crate::http::context::AppContext;
+use crate::pipeline_state::Stage;
+use serde_json::Value;
+
+/// Convert a work item's type in the CRDT.
+///
+/// Accepts `story_id` (full filename stem, e.g. `"42_spike_my_spike"`) and
+/// `new_type` (one of `"story"`, `"bug"`, `"spike"`, `"refactor"`, `"epic"`).
+/// Returns an error when the item does not exist or is in the `Archived` stage.
+pub(crate) fn tool_convert_item_type(args: &Value, _ctx: &AppContext) -> Result<String, String> {
+    let req = crate::validation::ConvertItemTypeRequest::from_json(args)?;
+    let story_id = req.story_id.as_str();
+
+    let item = crate::crdt_state::read_item(story_id)
+        .ok_or_else(|| format!("Work item '{story_id}' not found in CRDT."))?;
+
+    if matches!(item.stage(), Stage::Archived { .. }) {
+        return Err(format!(
+            "Cannot convert '{story_id}': type change on an archived item is not allowed."
+        ));
+    }
+
+    let old_type = item.item_type().map(|t| t.as_str()).unwrap_or("(inferred)");
+    let new_type_str = req.new_type.as_str();
+
+    if !crate::crdt_state::set_item_type(story_id, Some(req.new_type)) {
+        return Err(format!(
+            "Failed to update item type for '{story_id}': CRDT write was rejected."
+        ));
+    }
+
+    Ok(format!(
+        "Converted '{story_id}' from type '{old_type}' to '{new_type_str}'."
+    ))
+}
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::http::test_helpers::test_ctx;
+    use crate::io::story_metadata::ItemType;
+    use serde_json::json;
+
+    fn make_spike(spike_id: &str) {
+        crate::crdt_state::init_for_test();
+        crate::db::ensure_content_store();
+        crate::db::write_item_with_content(
+            spike_id,
+            "backlog",
+            "---\nname: Test Spike\n---\n",
+            crate::db::ItemMeta::named("Test Spike"),
+        );
+    }
+
+    #[test]
+    fn converts_spike_to_story_and_preserves_epic() {
+        crate::crdt_state::init_for_test();
+        let spike_id = "9111_spike_convert_regression";
+        make_spike(spike_id);
+
+        // Attach an epic.
+        crate::crdt_state::set_item_type(spike_id, Some(ItemType::Spike));
+        crate::crdt_state::set_epic(spike_id, crate::crdt_state::EpicId::from_crdt_str("9000"));
+
+        let tmp = tempfile::tempdir().unwrap();
+        let ctx = test_ctx(tmp.path());
+
+        // (i) Convert spike → story.
+        let result =
+            tool_convert_item_type(&json!({"story_id": spike_id, "new_type": "story"}), &ctx);
+        assert!(result.is_ok(), "convert should succeed: {result:?}");
+        assert!(
+            result.unwrap().contains("story"),
+            "response should mention new type"
+        );
+
+        // (i) Verify type is now Story in CRDT.
+        let item = crate::crdt_state::read_item(spike_id).expect("item must exist");
+        assert_eq!(
+            item.item_type(),
+            Some(ItemType::Story),
+            "item_type should be Story after conversion"
+        );
+
+        // (ii) Verify the conversion is visible in dump_crdt.
+        let dump = crate::crdt_state::dump_crdt_state(Some(spike_id));
+        let found = dump
+            .items
+            .iter()
+            .any(|i| i.item_type.as_deref() == Some("story") && !i.is_deleted);
+        assert!(
+            found,
+            "dump_crdt should show item_type='story' after conversion"
+        );
+
+        // (iii) Epic association is preserved.
+        assert_eq!(
+            item.epic(),
+            crate::crdt_state::EpicId::from_crdt_str("9000"),
+            "epic should be unchanged after type conversion"
+        );
+    }
+
+    #[test]
+    fn rejects_missing_story_id() {
+        crate::crdt_state::init_for_test();
+        let tmp = tempfile::tempdir().unwrap();
+        let ctx = test_ctx(tmp.path());
+        let err = tool_convert_item_type(&json!({"new_type": "story"}), &ctx).unwrap_err();
+        assert!(
+            err.contains("story_id"),
+            "error should mention story_id: {err}"
+        );
+    }
+
+    #[test]
+    fn rejects_invalid_new_type() {
+        crate::crdt_state::init_for_test();
+        let tmp = tempfile::tempdir().unwrap();
+        let ctx = test_ctx(tmp.path());
+        let err = tool_convert_item_type(
+            &json!({"story_id": "9112_spike_foo", "new_type": "banana"}),
+            &ctx,
+        )
+        .unwrap_err();
+        assert!(
+            err.contains("new_type") || err.contains("InvalidValue"),
+            "error should mention new_type: {err}"
+        );
+    }
+
+    #[test]
+    fn rejects_nonexistent_item() {
+        crate::crdt_state::init_for_test();
+        let tmp = tempfile::tempdir().unwrap();
+        let ctx = test_ctx(tmp.path());
+        let err = tool_convert_item_type(
+            &json!({"story_id": "9999_spike_not_real", "new_type": "story"}),
+            &ctx,
+        )
+        .unwrap_err();
+        assert!(
+            err.contains("not found"),
+            "error should say not found: {err}"
+        );
+    }
+
+    #[test]
+    fn rejects_archived_item() {
+        crate::crdt_state::init_for_test();
+        let spike_id = "9113_spike_archived_convert";
+        crate::db::ensure_content_store();
+        crate::db::write_item_with_content(
+            spike_id,
+            "archived",
+            "---\nname: Archived Spike\n---\n",
+            crate::db::ItemMeta::named("Archived Spike"),
+        );
+        let tmp = tempfile::tempdir().unwrap();
+        let ctx = test_ctx(tmp.path());
+        let err = tool_convert_item_type(&json!({"story_id": spike_id, "new_type": "story"}), &ctx)
+            .unwrap_err();
+        assert!(
+            err.contains("archived"),
+            "error should mention archived: {err}"
+        );
+    }
+}

server/src/http/mcp/story_tools/story/mod.rs

@@ -1,11 +1,13 @@
 //! Story creation, listing, update, and lifecycle MCP tools.
 
+mod convert;
 mod create;
 mod delete;
 mod freeze;
 mod query;
 mod update;
 
+pub(crate) use convert::tool_convert_item_type;
 pub(crate) use create::{tool_create_story, tool_purge_story};
 pub(crate) use delete::{tool_accept_story, tool_delete_story};
 pub(crate) use freeze::{tool_freeze_story, tool_unfreeze_story};

server/src/http/mcp/tools_list/mod.rs

@@ -114,7 +114,10 @@ mod tests {
         assert!(names.contains(&"schedule_timer"));
         assert!(names.contains(&"list_timers"));
         assert!(names.contains(&"cancel_timer"));
-        assert_eq!(tools.len(), 82);
+        assert!(names.contains(&"convert_item_type"));
+        assert!(names.contains(&"edit"));
+        assert!(names.contains(&"write"));
+        assert_eq!(tools.len(), 85);
     }
 
     #[test]

server/src/http/mcp/tools_list/story_tools.rs

@@ -671,6 +671,25 @@ pub(super) fn story_tools() -> Vec<Value> {
                 "required": ["story_id"]
             }
         }),
+        json!({
+            "name": "convert_item_type",
+            "description": "Convert a work item's type in place (e.g. spike → story). The story_id, ACs, epic association, and all other registers are preserved; only the item_type register changes. Rejected for archived items.",
+            "inputSchema": {
+                "type": "object",
+                "properties": {
+                    "story_id": {
+                        "type": "string",
+                        "description": "Work item identifier (filename stem, e.g. '42_spike_my_spike')"
+                    },
+                    "new_type": {
+                        "type": "string",
+                        "enum": ["story", "bug", "spike", "refactor", "epic"],
+                        "description": "Target item type"
+                    }
+                },
+                "required": ["story_id", "new_type"]
+            }
+        }),
         json!({
             "name": "freeze_story",
             "description": "Freeze a work item at its current pipeline stage, suppressing pipeline advancement and auto-assign until unfrozen.",

server/src/http/mcp/tools_list/system_tools.rs

@@ -173,6 +173,50 @@ pub(super) fn system_tools() -> Vec<Value> {
                 "required": []
             }
         }),
+        json!({
+            "name": "edit",
+            "description": "Replace old_string with new_string in a file inside the agent's assigned worktree. Mirrors Claude's built-in Edit tool but validates that file_path is inside .huskies/worktrees/ to prevent writes to the master worktree. By default replaces the first occurrence only; set replace_all to true to replace every occurrence.",
+            "inputSchema": {
+                "type": "object",
+                "properties": {
+                    "file_path": {
+                        "type": "string",
+                        "description": "Absolute path to the file to edit. Must be inside .huskies/worktrees/."
+                    },
+                    "old_string": {
+                        "type": "string",
+                        "description": "The exact string to replace."
+                    },
+                    "new_string": {
+                        "type": "string",
+                        "description": "The replacement string."
+                    },
+                    "replace_all": {
+                        "type": "boolean",
+                        "description": "If true, replace every occurrence of old_string. Default: false (replace first occurrence only)."
+                    }
+                },
+                "required": ["file_path", "old_string", "new_string"]
+            }
+        }),
+        json!({
+            "name": "write",
+            "description": "Write content to a file inside the agent's assigned worktree, creating the file (and any missing parent directories) if necessary. Mirrors Claude's built-in Write tool but validates that file_path is inside .huskies/worktrees/ to prevent writes to the master worktree.",
+            "inputSchema": {
+                "type": "object",
+                "properties": {
+                    "file_path": {
+                        "type": "string",
+                        "description": "Absolute path to the file to write. Must be inside .huskies/worktrees/."
+                    },
+                    "content": {
+                        "type": "string",
+                        "description": "The content to write to the file."
+                    }
+                },
+                "required": ["file_path", "content"]
+            }
+        }),
         json!({
             "name": "git_status",
             "description": "Return the working tree status of an agent's worktree (staged, unstaged, and untracked files). The worktree_path must be inside .huskies/worktrees/. Push and remote operations are not available.",

server/src/http/mod.rs

@@ -104,6 +104,10 @@ pub fn build_routes(
         route = route.at("/api/events", get(events::events_handler).data(buf));
     }
 
+    route = route
+        .at("/api/upgrade", post(upgrade_trigger_handler))
+        .at("/api/huskies-binary", get(serve_binary_handler));
+
     if let Some(wa_ctx) = whatsapp_ctx {
         route = route.at(
             "/webhook/whatsapp",
@@ -209,6 +213,72 @@ pub fn debug_crdt_handler(req: &poem::Request) -> poem::Response {
         .body(serde_json::to_string_pretty(&body).unwrap_or_default())
 }
 
+/// `POST /api/upgrade` — trigger a self-update on the running sled.
+///
+/// Accepts `{"source_url": "http://gateway:3000/api/huskies-binary"}` and
+/// spawns the upgrade task in the background, returning 202 immediately.
+/// The connection will be dropped when `exec()` replaces the process.
+#[poem::handler]
+pub async fn upgrade_trigger_handler(
+    body: poem::web::Json<serde_json::Value>,
+    ctx: poem::web::Data<&std::sync::Arc<AppContext>>,
+) -> poem::Response {
+    let source_url = match body
+        .0
+        .get("source_url")
+        .and_then(|v| v.as_str())
+        .map(|s| s.to_string())
+    {
+        Some(u) => u,
+        None => {
+            return poem::Response::builder()
+                .status(StatusCode::BAD_REQUEST)
+                .body("Missing required field: source_url");
+        }
+    };
+
+    let project_root = ctx.state.get_project_root().unwrap_or_default();
+
+    // Spawn upgrade in background so we can return 202 before exec() fires.
+    tokio::spawn(async move {
+        if let Err(e) = crate::upgrade::upgrade_and_reexec(&source_url, &project_root).await {
+            crate::slog!("[upgrade] Upgrade failed: {e}");
+        }
+    });
+
+    poem::Response::builder()
+        .status(StatusCode::ACCEPTED)
+        .body("Upgrade triggered. The sled will re-exec momentarily.")
+}
+
+/// `GET /api/huskies-binary` — serve the running binary so peer sleds can download it.
+///
+/// Streams `current_exe()` (the binary that is currently running) as an
+/// `application/octet-stream` download.  Returns 500 if the path cannot be
+/// resolved or read.
+#[poem::handler]
+pub async fn serve_binary_handler() -> poem::Response {
+    let exe = match std::env::current_exe() {
+        Ok(p) => p,
+        Err(e) => {
+            return poem::Response::builder()
+                .status(StatusCode::INTERNAL_SERVER_ERROR)
+                .body(format!("Cannot resolve current executable: {e}"));
+        }
+    };
+
+    match tokio::fs::read(&exe).await {
+        Ok(bytes) => poem::Response::builder()
+            .status(StatusCode::OK)
+            .header("Content-Type", "application/octet-stream")
+            .header("Content-Disposition", "attachment; filename=\"huskies\"")
+            .body(bytes),
+        Err(e) => poem::Response::builder()
+            .status(StatusCode::INTERNAL_SERVER_ERROR)
+            .body(format!("Cannot read binary at {}: {e}", exe.display())),
+    }
+}
+
 #[cfg(test)]
 mod tests {
     use super::*;

server/src/http/ws/mod.rs

@@ -86,6 +86,14 @@ pub async fn ws_handler(ws: WebSocket, ctx: Data<&Arc<AppContext>>) -> impl poem
             ws::subscribe_status(tx.clone(), ctx.services.status.subscribe());
         }
 
+        // Subscribe to real-time pipeline-transition events for this persona.
+        // Events that arrived while no client was connected are caught up by
+        // assemble_prompt_context at turn time.
+        ws::subscribe_persona_pipeline_events(
+            tx.clone(),
+            ctx.services.bot_name.to_lowercase(),
+        );
+
         // Map of pending permission request_id -> oneshot responder.
         let mut pending_perms: HashMap<String, oneshot::Sender<PermissionDecision>> =
             HashMap::new();
@@ -109,9 +117,11 @@ pub async fn ws_handler(ws: WebSocket, ctx: Data<&Arc<AppContext>>) -> impl poem
                     let tx_activity = tx.clone();
                     let ctx_clone = ctx.clone();
 
+                    let persona = ctx_clone.services.bot_name.to_lowercase();
                     let chat_fut = chat::chat(
                         messages,
                         config,
+                        &persona,
                         &ctx_clone.state,
                         ctx_clone.store.as_ref(),
                         move |history| {

server/src/llm/chat/run.rs

@@ -113,10 +113,13 @@ pub fn cancel_chat(state: &SessionState) -> Result<(), String> {
 }
 
 /// Run a multi-turn chat with tool calling against the configured provider.
+///
+/// `persona` is the persona name used to key CRDT event-log assembly (e.g. `"timmy"`).
 #[allow(clippy::too_many_arguments)]
 pub async fn chat<F, U, T, A>(
     mut messages: Vec<Message>,
     config: ProviderConfig,
+    persona: &str,
     state: &SessionState,
     store: &dyn StoreOps,
     mut on_update: F,
@@ -140,12 +143,9 @@ where
     inject_received_at(&mut messages, &received_at);
 
     // Assemble CRDT pipeline-transition events once per turn and advance the
-    // high-water mark.  Uses the Claude Code session_id when available so the
-    // same event stream key is used for resumable sessions; falls back to
-    // "web-ui" for Anthropic/Ollama turns which have no persistent session.
-    let event_ctx = crate::llm_session::assemble_prompt_context(
-        config.session_id.as_deref().unwrap_or("web-ui"),
-    );
+    // high-water mark.  Uses the caller-supplied persona so all transports share
+    // the same event stream regardless of transport-specific session identifiers.
+    let event_ctx = crate::llm_session::assemble_prompt_context(persona);
 
     let _ = state.cancel_tx.send(false);
     let mut cancel_rx = state.cancel_rx.clone();
@@ -628,6 +628,7 @@ mod tests {
         let result = chat(
             messages,
             config,
+            "timmy",
             &state,
             &store,
             |_| {},
@@ -672,6 +673,7 @@ mod tests {
         let result = chat(
             messages,
             config,
+            "timmy",
             &state,
             &store,
             |_| {},
@@ -712,6 +714,7 @@ mod tests {
         let result = chat(
             messages,
             config,
+            "timmy",
             &state,
             &store,
             |_| {},

server/src/llm_session/mod.rs

@@ -1,23 +1,23 @@
 //! LLM session management — CRDT-backed context assembly for bot prompts.
 //!
 //! The central export is [`assemble_prompt_context`], which reads new pipeline
-//! transition events from the CRDT event log past the session's stored high-water
+//! transition events from the CRDT event log past the persona's stored high-water
 //! marks, wraps them in a `<system-reminder>` block for injection at the head of
 //! the next LLM prompt, and atomically advances the marks so a mid-turn crash
 //! cannot double-inject the same events.
 
 /// Assemble a `<system-reminder>` block containing new pipeline-transition events
-/// for `session_id` and atomically advance the high-water marks.
+/// for `persona` and atomically advance the high-water marks.
 ///
-/// Reads events from the local sled's CRDT event log that have not yet been
-/// injected into this session (tracked via per-sled high-water marks stored in
-/// the `LlmSessionCrdt` entity).  Returns an empty string when there are no new
-/// events or the CRDT is not yet initialised.
-pub fn assemble_prompt_context(session_id: &str) -> String {
-    let lines = crate::crdt_state::assemble_and_advance_session(session_id);
+/// All chat transports call this with the same persona name (e.g. `"timmy"`)
+/// so that events are visible to whichever transport handles the next turn,
+/// regardless of transport-specific session identifiers.  Returns an empty
+/// string when there are no new events or the CRDT is not yet initialised.
+pub fn assemble_prompt_context(persona: &str) -> String {
+    let lines = crate::crdt_state::assemble_and_advance_session(persona);
     let event_count = lines.len();
     crate::slog!(
-        "[llm-session] assemble_prompt_context session={session_id} new_events={event_count}"
+        "[llm-session] assemble_prompt_context persona={persona} new_events={event_count}"
     );
     if lines.is_empty() {
         return String::new();
@@ -187,14 +187,14 @@ mod tests {
             "AgentCompleted",
         );
 
-        // Set up a session scoped to ALL sleds.
-        crate::crdt_state::write_llm_session("room-scope-all", "Timmy", "all");
-        // Set up a session scoped to sled-A only.
+        // Set up a persona scoped to ALL sleds.
+        crate::crdt_state::write_llm_session("timmy", "all");
+        // Set up a persona scoped to sled-A only.
         let sled_a_scope = format!("sleds:{sled_a}");
-        crate::crdt_state::write_llm_session("room-scope-sled-a", "Sally", &sled_a_scope);
+        crate::crdt_state::write_llm_session("sally", &sled_a_scope);
 
-        // All-scope session: both events must appear.
-        let ctx_all = assemble_prompt_context("room-scope-all");
+        // All-scope persona: both events must appear.
+        let ctx_all = assemble_prompt_context("timmy");
         assert!(
             ctx_all.contains("10_story_alpha"),
             "All scope must contain sled-A event; got: {ctx_all}"
@@ -204,8 +204,8 @@ mod tests {
             "All scope must contain sled-B event; got: {ctx_all}"
         );
 
-        // Sled-A-only session: only sled-A's event visible.
-        let ctx_a = assemble_prompt_context("room-scope-sled-a");
+        // Sled-A-only persona: only sled-A's event visible.
+        let ctx_a = assemble_prompt_context("sally");
         assert!(
             ctx_a.contains("10_story_alpha"),
             "Sleds filter must contain sled-A event; got: {ctx_a}"
@@ -215,19 +215,73 @@ mod tests {
             "Sleds filter must NOT contain sled-B event; got: {ctx_a}"
         );
 
-        // Second call on both sessions: nothing new (high-water advanced).
-        let ctx_all2 = assemble_prompt_context("room-scope-all");
+        // Second call on both personas: nothing new (high-water advanced).
+        let ctx_all2 = assemble_prompt_context("timmy");
         assert!(
             ctx_all2.is_empty(),
             "All scope second call must be empty; got: {ctx_all2}"
         );
-        let ctx_a2 = assemble_prompt_context("room-scope-sled-a");
+        let ctx_a2 = assemble_prompt_context("sally");
         assert!(
             ctx_a2.is_empty(),
             "Sleds filter second call must be empty; got: {ctx_a2}"
         );
     }
 
+    /// AC 5 e2e: fire a pipeline transition, then verify that calling
+    /// `assemble_prompt_context` with the same persona key from any "transport"
+    /// (simulated by different caller labels) sees the event.  The persona is
+    /// transport-agnostic; subsequent transports sharing the persona see their
+    /// own new events independently via independent calls (each drains a fresh
+    /// batch).
+    #[test]
+    fn persona_key_is_transport_agnostic() {
+        crate::crdt_state::init_for_test();
+        crate::crdt_state::write_llm_session("timmy", "all");
+
+        // Fire event 1.
+        crate::event_log::log_transition_event(&make_fired("e2e_story_1"));
+
+        // Matrix turn: see event 1.
+        let matrix_ctx = assemble_prompt_context("timmy");
+        assert!(
+            matrix_ctx.contains("e2e_story_1"),
+            "Matrix turn must see event 1; got: {matrix_ctx}"
+        );
+
+        // Fire event 2.
+        crate::event_log::log_transition_event(&make_fired("e2e_story_2"));
+
+        // Web-UI turn (same persona): see event 2 only (event 1 high-water already advanced).
+        let web_ui_ctx = assemble_prompt_context("timmy");
+        assert!(
+            web_ui_ctx.contains("e2e_story_2"),
+            "Web-UI turn must see event 2; got: {web_ui_ctx}"
+        );
+        assert!(
+            !web_ui_ctx.contains("e2e_story_1"),
+            "Web-UI turn must NOT re-see event 1; got: {web_ui_ctx}"
+        );
+
+        // Fire event 3.
+        crate::event_log::log_transition_event(&make_fired("e2e_story_3"));
+
+        // CLI turn (same persona): see event 3 only.
+        let cli_ctx = assemble_prompt_context("timmy");
+        assert!(
+            cli_ctx.contains("e2e_story_3"),
+            "CLI turn must see event 3; got: {cli_ctx}"
+        );
+        assert!(
+            !cli_ctx.contains("e2e_story_1"),
+            "CLI turn must NOT re-see event 1; got: {cli_ctx}"
+        );
+        assert!(
+            !cli_ctx.contains("e2e_story_2"),
+            "CLI turn must NOT re-see event 2; got: {cli_ctx}"
+        );
+    }
+
     /// Newly-added sled events appear in an All-scope session without
     /// restarting (AC 5 runtime pickup).
     #[test]
@@ -246,9 +300,9 @@ mod tests {
             "2_current",
             "DepsMet",
         );
-        crate::crdt_state::write_llm_session("room-runtime-pickup", "Timmy", "all");
+        crate::crdt_state::write_llm_session("timmy", "all");
 
-        let ctx1 = assemble_prompt_context("room-runtime-pickup");
+        let ctx1 = assemble_prompt_context("timmy");
         assert!(
             ctx1.contains("30_story_first"),
             "first event must appear; got: {ctx1}"
@@ -264,7 +318,7 @@ mod tests {
             "AgentCompleted",
         );
 
-        let ctx2 = assemble_prompt_context("room-runtime-pickup");
+        let ctx2 = assemble_prompt_context("timmy");
         assert!(
             ctx2.contains("40_story_second"),
             "newly adopted sled event must appear; got: {ctx2}"

server/src/main.rs

@@ -36,6 +36,10 @@ pub mod log_buffer;
 pub mod mesh;
 /// Node identity — Ed25519 keypair generation and stable node ID management.
 pub mod node_identity;
+/// Gateway pidfile — exclusive flock on `$HOME/.huskies/gateway.pid`.
+pub mod pidfile;
+/// Pipeline event bus — real-time broadcast of pipeline-transition events to persona subscribers.
+pub(crate) mod pipeline_event_bus;
 pub(crate) mod pipeline_state;
 /// Reliable process-termination primitives shared across the server.
 pub mod process_kill;
@@ -49,6 +53,10 @@ pub mod sled_uplink;
 mod startup;
 mod state;
 mod store;
+/// Detached trampoline — kills the running gateway and starts the new binary.
+pub mod trampoline;
+/// In-container binary self-update — fetch, atomic replace, and re-exec.
+pub mod upgrade;
 /// Validated input layer — transport-agnostic newtypes and request structs for all MCP write tools.
 pub mod validation;
 mod workflow;
@@ -72,6 +80,19 @@ mod cli;
 
 use cli::{parse_cli_args, resolve_path_arg};
 
+/// Convert a WebSocket gateway URL into the binary download HTTP URL.
+///
+/// `ws://gateway:3000/api/sled-uplink?token=x` → `http://gateway:3000/api/huskies-binary`
+fn derive_binary_url_from_ws(ws_url: &str) -> Option<String> {
+    let http = ws_url
+        .strip_prefix("wss://")
+        .map(|s| format!("https://{s}"))
+        .or_else(|| ws_url.strip_prefix("ws://").map(|s| format!("http://{s}")))?;
+    // Strip any path and query string, then append the binary endpoint.
+    let base = http.split('/').take(3).collect::<Vec<_>>().join("/");
+    Some(format!("{base}/api/huskies-binary"))
+}
+
 #[tokio::main]
 async fn main() -> Result<(), std::io::Error> {
     // Reap zombie grandchildren on Unix (for native deployments without tini/init).
@@ -145,6 +166,32 @@ async fn main() -> Result<(), std::io::Error> {
         }
     }
 
+    // ── Trampoline mode: kill old gateway, start new one ─────────────────────
+    if let Some(ref job_path) = cli.trampoline {
+        trampoline::run_trampoline(std::path::Path::new(job_path)).await;
+    }
+
+    // ── Upgrade mode: fetch new binary, replace, exit ───────────────────────
+    if cli.upgrade {
+        let source = cli
+            .upgrade_source
+            .clone()
+            .or_else(|| std::env::var("HUSKIES_BINARY_SOURCE").ok())
+            .unwrap_or_else(|| {
+                // Derive from HUSKIES_UPSTREAM_GATEWAY: ws://host:port/... → http://host:port/api/huskies-binary
+                std::env::var("HUSKIES_UPSTREAM_GATEWAY")
+                    .ok()
+                    .and_then(|ws| derive_binary_url_from_ws(&ws))
+                    .unwrap_or_else(|| "http://gateway:3000/api/huskies-binary".to_string())
+            });
+        let target = upgrade::resolve_target_path();
+        if let Err(e) = upgrade::run_cli_upgrade(&source, &target).await {
+            eprintln!("error: {e}");
+            std::process::exit(1);
+        }
+        return Ok(());
+    }
+
     // ── Gateway mode: multi-project proxy ────────────────────────────────────
     if is_gateway {
         let config_dir = explicit_path.unwrap_or_else(|| cwd.clone());
@@ -250,6 +297,11 @@ async fn main() -> Result<(), std::io::Error> {
         )),
     });
 
+    // Register the bot's persona in the CRDT so all transports share a single
+    // event-log high-water mark keyed by name rather than transport ids.
+    // scope="all" gives the gateway persona a cross-sled view of pipeline events.
+    crate::crdt_state::write_llm_session(&services.bot_name.to_lowercase(), "all");
+
     // Sled uplink: forward permission requests to an upstream gateway when configured.
     let upstream_gateway = cli
         .upstream_gateway
@@ -368,10 +420,10 @@ async fn main() -> Result<(), std::io::Error> {
             Arc::clone(&services),
             matrix_shutdown_rx,
             None,
-            std::collections::BTreeMap::new(),
             None,
             timer_store_for_bot,
             None,
+            None,
         );
     } else {
         drop(matrix_shutdown_rx);
@@ -465,4 +517,28 @@ name = "coder"
         config::ProjectConfig::load(tmp.path())
             .unwrap_or_else(|e| panic!("Invalid project.toml: {e}"));
     }
+
+    #[test]
+    fn derive_binary_url_strips_ws_scheme_and_path() {
+        let url = derive_binary_url_from_ws("ws://gateway:3000/api/sled-uplink?token=abc");
+        assert_eq!(
+            url.as_deref(),
+            Some("http://gateway:3000/api/huskies-binary")
+        );
+    }
+
+    #[test]
+    fn derive_binary_url_handles_wss_scheme() {
+        let url = derive_binary_url_from_ws("wss://myhost:443/path");
+        assert_eq!(
+            url.as_deref(),
+            Some("https://myhost:443/api/huskies-binary")
+        );
+    }
+
+    #[test]
+    fn derive_binary_url_invalid_scheme_returns_none() {
+        let url = derive_binary_url_from_ws("http://not-a-ws-url");
+        assert!(url.is_none());
+    }
 }

server/src/pidfile.rs

@@ -0,0 +1,121 @@
+//! Gateway pidfile — exclusive flock on `$HOME/.huskies/gateway.pid`.
+//!
+//! A gateway process holds the lock for its lifetime.  A second gateway that
+//! tries to start while one is already running fails immediately with a
+//! human-readable error naming the existing process.  A stale pidfile left by
+//! a dead process is reclaimed automatically: the kernel releases flocks when
+//! the file descriptor is closed, which happens when the process dies.
+
+use std::fs::{File, OpenOptions};
+use std::path::{Path, PathBuf};
+
+// ── Guard ─────────────────────────────────────────────────────────────────────
+
+/// Held for the lifetime of the gateway process.  Dropping it releases the flock.
+#[derive(Debug)]
+pub struct PidfileGuard {
+    _file: File,
+}
+
+// ── Path resolution ───────────────────────────────────────────────────────────
+
+/// Resolve `$HOME/.huskies/gateway.pid`, creating the directory if needed.
+fn default_pidfile_path() -> Result<PathBuf, String> {
+    let home = homedir::my_home()
+        .map_err(|e| format!("cannot determine home directory: {e}"))?
+        .ok_or_else(|| "HOME is not set".to_string())?;
+    let dir = home.join(".huskies");
+    std::fs::create_dir_all(&dir).map_err(|e| format!("cannot create {}: {e}", dir.display()))?;
+    Ok(dir.join("gateway.pid"))
+}
+
+// ── Public API ────────────────────────────────────────────────────────────────
+
+/// Acquire the gateway pidfile at `$HOME/.huskies/gateway.pid`.
+///
+/// Returns a [`PidfileGuard`] that holds the exclusive flock for as long as it
+/// is in scope.  Returns `Err("another gateway is at pid N")` when a live
+/// gateway already holds the lock, or `Err(…)` for unexpected I/O failures.
+pub fn acquire_gateway_pidfile() -> Result<PidfileGuard, String> {
+    let path = default_pidfile_path()?;
+    acquire_gateway_pidfile_at(&path)
+}
+
+/// Acquire the gateway pidfile at an explicit path.
+///
+/// Separated from [`acquire_gateway_pidfile`] so that tests can supply a
+/// temporary directory instead of touching `$HOME/.huskies`.
+pub fn acquire_gateway_pidfile_at(path: &Path) -> Result<PidfileGuard, String> {
+    let mut file = OpenOptions::new()
+        .read(true)
+        .write(true)
+        .create(true)
+        .truncate(false)
+        .open(path)
+        .map_err(|e| format!("cannot open pidfile {}: {e}", path.display()))?;
+
+    #[cfg(unix)]
+    {
+        use std::os::unix::io::AsRawFd;
+        let ret = unsafe { libc::flock(file.as_raw_fd(), libc::LOCK_EX | libc::LOCK_NB) };
+        if ret != 0 {
+            let err = std::io::Error::last_os_error();
+            if err.kind() == std::io::ErrorKind::WouldBlock
+                || err.raw_os_error() == Some(libc::EACCES)
+            {
+                // Another live process holds the lock — read its PID for the error message.
+                let pid_str = std::fs::read_to_string(path).unwrap_or_default();
+                let pid = pid_str.trim().parse::<u32>().unwrap_or(0);
+                return Err(format!("another gateway is at pid {pid}"));
+            }
+            return Err(format!("flock failed: {err}"));
+        }
+    }
+
+    // Write our PID (truncate first so no stale digits remain).
+    use std::io::{Seek, SeekFrom, Write};
+    file.set_len(0)
+        .map_err(|e| format!("cannot truncate pidfile: {e}"))?;
+    file.seek(SeekFrom::Start(0))
+        .map_err(|e| format!("cannot seek pidfile: {e}"))?;
+    write!(file, "{}", std::process::id()).map_err(|e| format!("cannot write pidfile: {e}"))?;
+
+    Ok(PidfileGuard { _file: file })
+}
+
+// ── Tests ─────────────────────────────────────────────────────────────────────
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    /// AC 2 & 3: second gateway fails with pid message; after release, the next
+    /// acquire succeeds (dead-PID reclaim).
+    #[cfg(unix)]
+    #[test]
+    fn second_gateway_fails_with_pid_message_then_reclaims() {
+        let tmp = tempfile::tempdir().unwrap();
+        let path = tmp.path().join("gateway.pid");
+
+        let guard1 = acquire_gateway_pidfile_at(&path).expect("first acquire should succeed");
+
+        let err = acquire_gateway_pidfile_at(&path)
+            .expect_err("second acquire should fail while first is held");
+
+        let my_pid = std::process::id();
+        assert!(
+            err.contains("another gateway is at pid"),
+            "error should contain the prefix, got: {err}"
+        );
+        assert!(
+            err.contains(&my_pid.to_string()),
+            "error should contain our PID {my_pid}, got: {err}"
+        );
+
+        // Release the first guard → flock is freed (simulates gateway death).
+        drop(guard1);
+
+        // Third acquire must succeed — dead-PID reclaim.
+        acquire_gateway_pidfile_at(&path).expect("acquire after release should succeed");
+    }
+}

server/src/pipeline_event_bus.rs

@@ -0,0 +1,84 @@
+//! Real-time pipeline event bus — broadcasts `TransitionFired` events to
+//! per-persona WebSocket subscribers as they happen.
+//!
+//! Turn-time [`crate::llm_session::assemble_prompt_context`] still works as
+//! a fallback catch-up mechanism for any events that accumulated while no
+//! subscriber was connected.
+
+use std::sync::OnceLock;
+use tokio::sync::broadcast;
+
+/// Capacity of the per-persona event bus broadcast channel.
+const BUS_CAPACITY: usize = 256;
+
+/// A raw pipeline-transition event forwarded from `log_transition_event`.
+#[derive(Clone, Debug)]
+pub struct BusEvent {
+    /// Hex-encoded sled ID that fired the transition.
+    pub sled_id: String,
+    /// Story identifier (e.g. `"42_story_foo"`).
+    pub story_id: String,
+    /// Human-readable label of the stage before the transition.
+    pub from_stage: String,
+    /// Human-readable label of the stage after the transition.
+    pub to_stage: String,
+    /// String label of the `PipelineEvent` variant.
+    pub pipeline_event: String,
+}
+
+static BUS_TX: OnceLock<broadcast::Sender<BusEvent>> = OnceLock::new();
+
+/// Initialise the pipeline event bus.  No-op on subsequent calls.
+pub fn init() {
+    let _ = BUS_TX.get_or_init(|| broadcast::channel::<BusEvent>(BUS_CAPACITY).0);
+}
+
+/// Broadcast a pipeline transition event to all active subscribers.
+///
+/// No-op if the bus has not been initialised or there are no subscribers.
+pub fn broadcast(event: BusEvent) {
+    if let Some(tx) = BUS_TX.get() {
+        let _ = tx.send(event);
+    }
+}
+
+/// Subscribe to the pipeline event bus.
+///
+/// Returns `None` if the bus has not been initialised yet.
+pub fn subscribe() -> Option<broadcast::Receiver<BusEvent>> {
+    BUS_TX.get().map(|tx| tx.subscribe())
+}
+
+/// Render a [`BusEvent`] as the same compact audit line used in
+/// `assemble_and_advance_session`.
+pub fn render_event(event: &BusEvent) -> String {
+    if event.pipeline_event == crate::crdt_state::GAP_PIPELINE_EVENT {
+        format!(
+            "events between {} and {} were dropped",
+            event.from_stage, event.to_stage
+        )
+    } else {
+        format!(
+            "pipeline_event sled_id=\"{}\" story_id=\"{}\" from=\"{}\" to=\"{}\" event=\"{}\"",
+            event.sled_id, event.story_id, event.from_stage, event.to_stage, event.pipeline_event
+        )
+    }
+}
+
+/// Returns `true` if `event` should be delivered to `persona` based on the
+/// persona's stored scope filter in the CRDT.
+///
+/// Falls back to local-sled-only if no session entry exists for `persona`.
+pub fn event_matches_persona(event: &BusEvent, persona: &str) -> bool {
+    use crate::crdt_state::ScopeFilter;
+    match crate::crdt_state::read_llm_session(persona) {
+        Some(session) => match &session.scope_filter {
+            ScopeFilter::All => true,
+            ScopeFilter::Sleds(ids) => ids.contains(&event.sled_id),
+        },
+        None => {
+            let local = crate::crdt_state::our_node_id().unwrap_or_default();
+            !local.is_empty() && event.sled_id == local
+        }
+    }
+}

server/src/service/gateway/io.rs

@@ -504,7 +504,6 @@ pub type ActiveProject = std::sync::Arc<tokio::sync::RwLock<String>>;
 pub fn spawn_gateway_bot(
     config_dir: &Path,
     active_project: ActiveProject,
-    gateway_project_urls: BTreeMap<String, String>,
     gateway_projects_store: std::sync::Arc<tokio::sync::RwLock<BTreeMap<String, ProjectEntry>>>,
     port: u16,
     gateway_event_tx: Option<tokio::sync::broadcast::Sender<super::GatewayStatusEvent>>,
@@ -577,10 +576,10 @@ pub fn spawn_gateway_bot(
         services,
         shutdown_rx,
         Some(active_project),
-        gateway_project_urls,
         Some(gateway_projects_store),
         timer_store,
         gateway_event_rx,
+        Some(port),
     );
     (handle, shutdown_tx)
 }
@@ -608,7 +607,6 @@ mod tests {
         let (handle, shutdown_tx) = spawn_gateway_bot(
             tmp.path(),
             active,
-            std::collections::BTreeMap::new(),
             projects_store,
             3001,
             Some(event_tx),

server/src/service/gateway/mod.rs

@@ -673,18 +673,9 @@ pub async fn save_bot_config_and_restart(state: &GatewayState, content: &str) ->
         if let Some(h) = handle.take() {
             h.abort();
         }
-        let gateway_project_urls: BTreeMap<String, String> = state
-            .projects
-            .read()
-            .await
-            .iter()
-            .filter_map(|(name, entry)| entry.url.as_ref().map(|u| (name.clone(), u.clone())))
-            .collect();
-
         let (new_handle, new_shutdown_tx) = io::spawn_gateway_bot(
             &state.config_dir,
             Arc::clone(&state.active_project),
-            gateway_project_urls,
             Arc::clone(&state.projects),
             state.port,
             Some(state.event_tx.clone()),

server/src/service/ws/io.rs

@@ -132,6 +132,34 @@ pub fn subscribe_status(tx: mpsc::UnboundedSender<WsResponse>, mut subscription:
     });
 }
 
+/// Spawn a background task that forwards real-time pipeline-transition events to
+/// the client, filtered to those visible to `persona` based on its scope filter.
+///
+/// Each matching event is delivered as a [`WsResponse::PipelineEvent`] frame.
+/// Events that occur while no subscriber is connected are NOT delivered here;
+/// [`crate::llm_session::assemble_prompt_context`] catches up on those at turn time.
+pub fn subscribe_persona_pipeline_events(tx: mpsc::UnboundedSender<WsResponse>, persona: String) {
+    let Some(mut rx) = crate::pipeline_event_bus::subscribe() else {
+        return;
+    };
+    tokio::spawn(async move {
+        loop {
+            match rx.recv().await {
+                Ok(event) => {
+                    if crate::pipeline_event_bus::event_matches_persona(&event, &persona) {
+                        let line = crate::pipeline_event_bus::render_event(&event);
+                        if tx.send(WsResponse::PipelineEvent { line }).is_err() {
+                            break;
+                        }
+                    }
+                }
+                Err(broadcast::error::RecvError::Lagged(_)) => continue,
+                Err(broadcast::error::RecvError::Closed) => break,
+            }
+        }
+    });
+}
+
 /// Spawn a background task that forwards reconciliation events to the client.
 pub fn subscribe_reconciliation(
     tx: mpsc::UnboundedSender<WsResponse>,

server/src/service/ws/message/response.rs

@@ -127,6 +127,13 @@ pub enum WsResponse {
     StatusUpdate {
         event: StatusEvent,
     },
+    /// A real-time pipeline-transition event pushed to the client as it happens.
+    ///
+    /// Carries the same compact audit-line format used in `<system-reminder>`
+    /// blocks so that LLM-aware clients can consume it without additional parsing.
+    PipelineEvent {
+        line: String,
+    },
 }
 
 #[cfg(test)]

server/src/service/ws/mod.rs

@@ -23,6 +23,7 @@ pub use dispatch::{
 };
 pub use io::{
     check_onboarding, load_initial_pipeline_state, load_recent_logs, load_wizard_state,
-    subscribe_logs, subscribe_reconciliation, subscribe_status, subscribe_watcher,
+    subscribe_logs, subscribe_persona_pipeline_events, subscribe_reconciliation, subscribe_status,
+    subscribe_watcher,
 };
 pub use message::{WizardStepInfo, WsResponse};

server/src/startup/tick_loop.rs

@@ -28,6 +28,10 @@ pub(crate) fn spawn_event_bridges(
     // Audit log subscriber: write one structured line per pipeline transition.
     crate::pipeline_state::spawn_audit_log_subscriber();
 
+    // Pipeline event bus: initialise before the event-log subscriber so that
+    // real-time broadcasts are ready before the first transition fires.
+    crate::pipeline_event_bus::init();
+
     // Event log subscriber: persist every transition to the CRDT event log so
     // the history survives rebuild_and_restart and replicates across nodes.
     crate::event_log::spawn_event_log_subscriber();

server/src/trampoline.rs

@@ -0,0 +1,337 @@
+//! Detached trampoline — kills the running gateway and launches the replacement.
+//!
+//! The trampoline is invoked as `huskies --trampoline <job-file>`.  It is spawned
+//! as a new Unix session (`setsid`) so that SIGKILL/SIGTERM sent to the original
+//! bash-tool process group does not reach it.
+//!
+//! Flow:
+//! 1. Gateway writes a [`TrampolineJob`] atomically and spawns the trampoline.
+//! 2. Trampoline backs up the old binary, kills the gateway, starts the new binary.
+//! 3. If the new binary passes a health-poll within 10 s → exit 0.
+//! 4. If it fails → restore backup, start it with `HUSKIES_TRAMPOLINE_FAILURE` set.
+
+use serde::{Deserialize, Serialize};
+use std::path::{Path, PathBuf};
+use std::time::Duration;
+
+// ── Job descriptor ────────────────────────────────────────────────────────────
+
+/// Descriptor atomically written by the gateway before it hands control to the trampoline.
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct TrampolineJob {
+    /// PID of the currently running gateway process to kill.
+    pub gateway_pid: u32,
+    /// Absolute path to the newly compiled binary to launch.
+    pub new_binary_path: PathBuf,
+    /// Absolute path of the binary currently running as the gateway (for rollback).
+    pub old_binary_path: PathBuf,
+    /// Where to write the backup of the old binary before killing the gateway.
+    pub backup_binary_path: PathBuf,
+    /// Arguments forwarded verbatim to the new/backup gateway (everything after argv[0]).
+    pub gateway_args: Vec<String>,
+    /// HTTP URL the trampoline polls to verify the new gateway is serving.
+    /// Empty string means skip health polling (used in tests).
+    pub health_url: String,
+}
+
+// ── Atomic write ──────────────────────────────────────────────────────────────
+
+/// Write `job` to `path` atomically: write to a sibling `.tmp` file, then rename.
+///
+/// The rename is atomic on POSIX so the trampoline never reads a half-written file.
+pub fn write_job_atomic(job: &TrampolineJob, path: &Path) -> Result<(), String> {
+    let tmp = path.with_extension("tmp");
+    let data = serde_json::to_vec(job).map_err(|e| format!("JSON encode failed: {e}"))?;
+    std::fs::write(&tmp, &data).map_err(|e| format!("tmp write failed: {e}"))?;
+    std::fs::rename(&tmp, path).map_err(|e| format!("rename failed: {e}"))?;
+    Ok(())
+}
+
+// ── Spawn detached ────────────────────────────────────────────────────────────
+
+/// Spawn `exe --trampoline <job_path>` as a fully detached process.
+///
+/// On Unix the child calls `setsid()` in `pre_exec` so it belongs to a new session
+/// and is unreachable by signals sent to the original process group.  stdin/stdout/
+/// stderr are all redirected to `/dev/null` so the child is fully daemonised.
+pub fn spawn_detached_trampoline(exe: &Path, job_path: &Path) -> Result<(), String> {
+    let mut cmd = std::process::Command::new(exe);
+    cmd.arg("--trampoline").arg(job_path);
+    cmd.stdin(std::process::Stdio::null());
+    cmd.stdout(std::process::Stdio::null());
+    cmd.stderr(std::process::Stdio::null());
+
+    #[cfg(unix)]
+    {
+        use std::os::unix::process::CommandExt;
+        // SAFETY: setsid() is async-signal-safe.  This is called in the child
+        // between fork and exec with no other threads running in the child's
+        // address space — the only safe window for pre_exec hooks.
+        unsafe {
+            cmd.pre_exec(|| {
+                if libc::setsid() == -1 {
+                    return Err(std::io::Error::last_os_error());
+                }
+                Ok(())
+            });
+        }
+    }
+
+    cmd.spawn().map_err(|e| format!("spawn failed: {e}"))?;
+    Ok(())
+}
+
+// ── Process management ────────────────────────────────────────────────────────
+
+/// Send SIGTERM to `pid`, wait up to 3 s for it to exit, then SIGKILL.
+///
+/// After SIGKILL the process is unconditionally considered gone — SIGKILL cannot
+/// be ignored, so the process is dead even if it briefly lingers as a zombie
+/// (zombie detection via `kill(pid, 0)` is unreliable from a non-parent process).
+#[cfg(unix)]
+fn kill_gateway_process(pid: u32) -> Result<(), String> {
+    use std::thread::sleep;
+
+    let ipid = pid as libc::pid_t;
+
+    // Safety: kill() is always safe to call with any pid.
+    let running = || unsafe { libc::kill(ipid, 0) } == 0;
+
+    if !running() {
+        return Ok(());
+    }
+
+    unsafe { libc::kill(ipid, libc::SIGTERM) };
+
+    for _ in 0..30 {
+        sleep(Duration::from_millis(100));
+        if !running() {
+            return Ok(());
+        }
+    }
+
+    // SIGKILL cannot be ignored — the kernel will terminate the process.
+    // We don't loop-poll after this: the process may briefly appear as a
+    // zombie (still in the table, not yet reaped by its parent), in which
+    // case kill(pid, 0) returns 0 even though it is effectively dead.
+    unsafe { libc::kill(ipid, libc::SIGKILL) };
+    sleep(Duration::from_millis(200));
+    Ok(())
+}
+
+#[cfg(not(unix))]
+fn kill_gateway_process(pid: u32) -> Result<(), String> {
+    Err(format!("kill not supported on this platform (pid {pid})"))
+}
+
+// ── Health polling ────────────────────────────────────────────────────────────
+
+/// Poll `url` every 500 ms until it returns HTTP 2xx or `timeout` elapses.
+async fn poll_health(url: &str, timeout: Duration) -> Result<(), String> {
+    let client = reqwest::Client::builder()
+        .timeout(Duration::from_secs(2))
+        .build()
+        .unwrap_or_else(|_| reqwest::Client::new());
+
+    let deadline = std::time::Instant::now() + timeout;
+    while std::time::Instant::now() < deadline {
+        if let Ok(resp) = client.get(url).send().await
+            && resp.status().is_success()
+        {
+            return Ok(());
+        }
+        tokio::time::sleep(Duration::from_millis(500)).await;
+    }
+    Err(format!(
+        "health check timed out after {}s: {url}",
+        timeout.as_secs()
+    ))
+}
+
+// ── Core logic (testable) ─────────────────────────────────────────────────────
+
+/// Kill the old gateway, start the new one, and poll its health endpoint.
+///
+/// Returns `Ok(())` on success or `Err(reason)` when the new gateway could not
+/// be started or failed health checks.  Callers are responsible for rollback.
+///
+/// When `job.health_url` is empty the health poll is skipped (for unit tests).
+pub async fn execute_trampoline_core(job: &TrampolineJob) -> Result<(), String> {
+    // Back up old binary (best-effort — rollback won't work if this fails).
+    if let Some(parent) = job.backup_binary_path.parent() {
+        let _ = std::fs::create_dir_all(parent);
+    }
+    let _ = std::fs::copy(&job.old_binary_path, &job.backup_binary_path);
+
+    // Kill old gateway.  Killing the process closes its file descriptors,
+    // which releases the exclusive flock held on `$HOME/.huskies/gateway.pid`.
+    // The new gateway (spawned below) will then acquire that flock on startup,
+    // ensuring the one-active-gateway invariant is maintained across the swap.
+    kill_gateway_process(job.gateway_pid)?;
+
+    // Start new gateway.
+    std::process::Command::new(&job.new_binary_path)
+        .args(&job.gateway_args)
+        .env("HUSKIES_TRAMPOLINE_STARTED", "1")
+        .stdin(std::process::Stdio::null())
+        .stdout(std::process::Stdio::null())
+        .stderr(std::process::Stdio::null())
+        .spawn()
+        .map_err(|e| format!("failed to start new gateway: {e}"))?;
+
+    // Poll health (skip when URL is empty — used in tests).
+    if !job.health_url.is_empty() {
+        poll_health(&job.health_url, Duration::from_secs(10)).await?;
+    }
+
+    Ok(())
+}
+
+// ── Entry point ───────────────────────────────────────────────────────────────
+
+/// Run the trampoline from a job file.  This function never returns.
+///
+/// On success exits 0 (new gateway is up and will post its own "ready" message).
+/// On failure starts the backup binary with `HUSKIES_TRAMPOLINE_FAILURE` set and
+/// exits 1.  On unrecoverable failure (cannot start backup either) exits 2.
+pub async fn run_trampoline(job_path: &Path) -> ! {
+    let data = match std::fs::read(job_path) {
+        Ok(d) => d,
+        Err(e) => {
+            eprintln!(
+                "[trampoline] cannot read job file {}: {e}",
+                job_path.display()
+            );
+            std::process::exit(1);
+        }
+    };
+
+    let job: TrampolineJob = match serde_json::from_slice(&data) {
+        Ok(j) => j,
+        Err(e) => {
+            eprintln!("[trampoline] cannot parse job file: {e}");
+            std::process::exit(1);
+        }
+    };
+
+    eprintln!(
+        "[trampoline] killing gateway PID {} and starting {}",
+        job.gateway_pid,
+        job.new_binary_path.display()
+    );
+
+    match execute_trampoline_core(&job).await {
+        Ok(()) => {
+            eprintln!("[trampoline] new gateway is up — exiting");
+            let _ = std::fs::remove_file(job_path);
+            std::process::exit(0);
+        }
+        Err(reason) => {
+            eprintln!("[trampoline] new gateway failed ({reason}) — rolling back");
+            let result = std::process::Command::new(&job.backup_binary_path)
+                .args(&job.gateway_args)
+                .env("HUSKIES_TRAMPOLINE_FAILURE", &reason)
+                .stdin(std::process::Stdio::null())
+                .stdout(std::process::Stdio::null())
+                .stderr(std::process::Stdio::null())
+                .spawn();
+            match result {
+                Ok(_) => {
+                    let _ = std::fs::remove_file(job_path);
+                    std::process::exit(1);
+                }
+                Err(e) => {
+                    eprintln!("[trampoline] FATAL: cannot start backup gateway: {e}");
+                    std::process::exit(2);
+                }
+            }
+        }
+    }
+}
+
+// ── Tests ─────────────────────────────────────────────────────────────────────
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use std::path::PathBuf;
+
+    /// Locate `sleep` on the current platform (needed for a portable fake-gateway).
+    fn find_sleep() -> PathBuf {
+        for candidate in ["/usr/bin/sleep", "/bin/sleep"] {
+            let p = PathBuf::from(candidate);
+            if p.exists() {
+                return p;
+            }
+        }
+        panic!("sleep binary not found");
+    }
+
+    #[test]
+    fn write_job_atomic_round_trips() {
+        let tmp = tempfile::tempdir().unwrap();
+        let job = TrampolineJob {
+            gateway_pid: 12345,
+            new_binary_path: PathBuf::from("/new/huskies"),
+            old_binary_path: PathBuf::from("/old/huskies"),
+            backup_binary_path: tmp.path().join("backup"),
+            gateway_args: vec!["--gateway".to_string(), "/workspace".to_string()],
+            health_url: "http://127.0.0.1:3000/api/gateway".to_string(),
+        };
+        let path = tmp.path().join("trampoline.json");
+        write_job_atomic(&job, &path).unwrap();
+
+        // No .tmp file should remain.
+        assert!(!path.with_extension("tmp").exists());
+        // Final file must exist.
+        assert!(path.exists());
+
+        // Round-trip: deserialise and compare fields.
+        let data = std::fs::read(&path).unwrap();
+        let loaded: TrampolineJob = serde_json::from_slice(&data).unwrap();
+        assert_eq!(loaded.gateway_pid, job.gateway_pid);
+        assert_eq!(loaded.new_binary_path, job.new_binary_path);
+        assert_eq!(loaded.gateway_args, job.gateway_args);
+    }
+
+    /// AC 5: a fake-gateway `sleep` process is killed and replaced within timeout.
+    #[tokio::test]
+    async fn fake_gateway_killed_and_replaced_within_timeout() {
+        let sleep_exe = find_sleep();
+        let tmp = tempfile::tempdir().unwrap();
+
+        // Spawn the fake gateway (a long-lived sleep process).
+        let mut fake_gw = std::process::Command::new(&sleep_exe)
+            .arg("60")
+            .stdin(std::process::Stdio::null())
+            .spawn()
+            .expect("spawn fake gateway");
+        let fake_pid = fake_gw.id();
+
+        let job = TrampolineJob {
+            gateway_pid: fake_pid,
+            new_binary_path: sleep_exe.clone(),
+            old_binary_path: sleep_exe.clone(),
+            backup_binary_path: tmp.path().join("backup"),
+            gateway_args: vec!["1".to_string()],
+            health_url: String::new(), // skip health check in test
+        };
+
+        let start = std::time::Instant::now();
+        let result = execute_trampoline_core(&job).await;
+        let elapsed = start.elapsed();
+
+        assert!(result.is_ok(), "trampoline core should succeed: {result:?}");
+        assert!(
+            elapsed < Duration::from_secs(10),
+            "should complete well within 10s timeout, took {elapsed:?}"
+        );
+
+        // Reap the zombie — should be dead now.
+        let status = fake_gw.try_wait().expect("try_wait");
+        assert!(
+            status.is_some(),
+            "fake gateway process should be dead after trampoline kill"
+        );
+    }
+}

server/src/upgrade.rs

@@ -0,0 +1,263 @@
+//! In-container binary self-update — fetch a new `huskies` binary, atomically
+//! replace the on-disk executable, drain CRDT persistence, and re-exec.
+
+use crate::slog;
+use std::path::{Path, PathBuf};
+
+// ── Binary fetch ─────────────────────────────────────────────────────────────
+
+/// Download a binary from `source_url` and atomically replace `target_path`.
+///
+/// Writes to a sibling `.tmp` file first, then renames so the replacement is
+/// atomic on the same filesystem.  Sets the execute bit before renaming so the
+/// file is runnable the moment it appears at the target location.
+pub async fn fetch_and_replace_binary(source_url: &str, target_path: &Path) -> Result<(), String> {
+    slog!("[upgrade] Fetching binary from {source_url}");
+
+    let resp = reqwest::get(source_url)
+        .await
+        .map_err(|e| format!("Failed to fetch binary from {source_url}: {e}"))?;
+
+    if !resp.status().is_success() {
+        return Err(format!(
+            "Binary fetch returned HTTP {}: {source_url}",
+            resp.status()
+        ));
+    }
+
+    let bytes = resp
+        .bytes()
+        .await
+        .map_err(|e| format!("Failed to read binary response body: {e}"))?;
+
+    if bytes.is_empty() {
+        return Err("Binary fetch returned an empty body".to_string());
+    }
+
+    // Write to a sibling temp file so the rename is atomic on the same FS.
+    let tmp_path = sibling_tmp_path(target_path)?;
+    std::fs::write(&tmp_path, &bytes)
+        .map_err(|e| format!("Failed to write tmp binary to {}: {e}", tmp_path.display()))?;
+
+    set_executable(&tmp_path)?;
+
+    std::fs::rename(&tmp_path, target_path).map_err(|e| {
+        format!(
+            "Failed to rename {} → {}: {e}",
+            tmp_path.display(),
+            target_path.display()
+        )
+    })?;
+
+    slog!(
+        "[upgrade] Binary replaced at {} ({} bytes)",
+        target_path.display(),
+        bytes.len()
+    );
+    Ok(())
+}
+
+// ── Full server upgrade (called from the running process) ─────────────────
+
+/// Fetch a new binary, atomically replace the current executable, drain CRDT
+/// persistence, and re-exec the running server process with its original args.
+///
+/// This function never returns on success — `exec()` replaces the process.
+/// On failure it returns `Err(message)` so the caller can report the error
+/// while keeping the original server running.
+pub async fn upgrade_and_reexec(source_url: &str, project_root: &Path) -> Result<String, String> {
+    let target = resolve_target_path();
+
+    fetch_and_replace_binary(source_url, &target).await?;
+
+    // Drain queued CRDT ops so nothing is lost when exec() replaces the process.
+    crate::crdt_state::flush_persistence(std::time::Duration::from_secs(5)).await;
+
+    // Clean up the port file so the new process can write a fresh one.
+    let port_file = project_root.join(".huskies_port");
+    if port_file.exists() {
+        let _ = std::fs::remove_file(&port_file);
+    }
+
+    let args: Vec<String> = std::env::args().collect();
+    slog!("[upgrade] Re-execing with new binary: {}", target.display());
+
+    use std::os::unix::process::CommandExt;
+    let err = std::process::Command::new(&target).args(&args[1..]).exec();
+
+    // exec() only returns on failure.
+    Err(format!(
+        "Failed to exec new binary at {}: {err}",
+        target.display()
+    ))
+}
+
+// ── CLI upgrade (no re-exec) ─────────────────────────────────────────────
+
+/// Run the `huskies upgrade` CLI subcommand: download, replace, and exit.
+///
+/// Unlike [`upgrade_and_reexec`], this does not flush the CRDT or re-exec
+/// because the CLI subcommand is run as a standalone command (not the server).
+/// After this returns the caller should exit.
+pub async fn run_cli_upgrade(source_url: &str, target: &Path) -> Result<(), String> {
+    fetch_and_replace_binary(source_url, target).await?;
+    println!(
+        "Upgrade complete. New binary installed at {}.",
+        target.display()
+    );
+    Ok(())
+}
+
+// ── Helpers ───────────────────────────────────────────────────────────────
+
+/// Resolve the path to replace: `current_exe()` if accessible, else
+/// `/usr/local/bin/huskies`.
+pub fn resolve_target_path() -> PathBuf {
+    std::env::current_exe().unwrap_or_else(|_| PathBuf::from("/usr/local/bin/huskies"))
+}
+
+fn sibling_tmp_path(target: &Path) -> Result<PathBuf, String> {
+    let parent = target
+        .parent()
+        .ok_or_else(|| format!("Cannot determine parent dir of {}", target.display()))?;
+    Ok(parent.join(".huskies_upgrade.tmp"))
+}
+
+#[cfg(unix)]
+fn set_executable(path: &Path) -> Result<(), String> {
+    use std::os::unix::fs::PermissionsExt;
+    let meta =
+        std::fs::metadata(path).map_err(|e| format!("Cannot stat {}: {e}", path.display()))?;
+    let mut perms = meta.permissions();
+    perms.set_mode(0o755);
+    std::fs::set_permissions(path, perms)
+        .map_err(|e| format!("Cannot chmod {}: {e}", path.display()))
+}
+
+#[cfg(not(unix))]
+fn set_executable(_path: &Path) -> Result<(), String> {
+    Ok(())
+}
+
+// ── Tests ─────────────────────────────────────────────────────────────────
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    /// Start a tiny HTTP server in the background that serves `content` at `/`.
+    async fn serve_bytes(content: Vec<u8>) -> (u16, tokio::task::JoinHandle<()>) {
+        use std::sync::Arc;
+
+        let content = Arc::new(content);
+        let listener = tokio::net::TcpListener::bind("127.0.0.1:0").await.unwrap();
+        let port = listener.local_addr().unwrap().port();
+
+        let handle = tokio::spawn(async move {
+            loop {
+                let Ok((mut stream, _)) = listener.accept().await else {
+                    break;
+                };
+                let content = Arc::clone(&content);
+                tokio::spawn(async move {
+                    use tokio::io::AsyncWriteExt;
+                    // Drain the HTTP request (ignore it).
+                    let mut buf = [0u8; 4096];
+                    let _ = tokio::io::AsyncReadExt::read(&mut stream, &mut buf).await;
+                    // Write a minimal HTTP/1.1 200 response.
+                    let header = format!(
+                        "HTTP/1.1 200 OK\r\nContent-Length: {}\r\nContent-Type: application/octet-stream\r\n\r\n",
+                        content.len()
+                    );
+                    let _ = stream.write_all(header.as_bytes()).await;
+                    let _ = stream.write_all(&content).await;
+                });
+            }
+        });
+
+        (port, handle)
+    }
+
+    #[tokio::test]
+    async fn fetch_and_replace_binary_downloads_and_replaces() {
+        let dir = tempfile::tempdir().unwrap();
+        let target = dir.path().join("huskies");
+        std::fs::write(&target, b"old binary").unwrap();
+
+        let content = b"new binary content v0.99.0".to_vec();
+        let (port, _srv) = serve_bytes(content.clone()).await;
+
+        let url = format!("http://127.0.0.1:{port}/huskies");
+        fetch_and_replace_binary(&url, &target).await.unwrap();
+
+        let on_disk = std::fs::read(&target).unwrap();
+        assert_eq!(
+            on_disk, content,
+            "target must contain the downloaded content"
+        );
+    }
+
+    #[tokio::test]
+    async fn fetch_and_replace_binary_sets_executable_bit() {
+        #[cfg(unix)]
+        {
+            use std::os::unix::fs::PermissionsExt;
+
+            let dir = tempfile::tempdir().unwrap();
+            let target = dir.path().join("huskies");
+            std::fs::write(&target, b"old").unwrap();
+
+            let (port, _srv) = serve_bytes(b"#!/bin/sh\nexit 0".to_vec()).await;
+            let url = format!("http://127.0.0.1:{port}/huskies");
+            fetch_and_replace_binary(&url, &target).await.unwrap();
+
+            let mode = std::fs::metadata(&target).unwrap().permissions().mode();
+            assert!(mode & 0o111 != 0, "binary must be executable after upgrade");
+        }
+    }
+
+    #[tokio::test]
+    async fn fetch_and_replace_binary_empty_body_is_error() {
+        let dir = tempfile::tempdir().unwrap();
+        let target = dir.path().join("huskies");
+        std::fs::write(&target, b"old").unwrap();
+
+        let (port, _srv) = serve_bytes(vec![]).await;
+        let url = format!("http://127.0.0.1:{port}/huskies");
+        let err = fetch_and_replace_binary(&url, &target).await.unwrap_err();
+        assert!(
+            err.contains("empty"),
+            "expected empty-body error, got: {err}"
+        );
+
+        // Original must be untouched (rename never happened).
+        let on_disk = std::fs::read(&target).unwrap();
+        assert_eq!(on_disk, b"old");
+    }
+
+    #[tokio::test]
+    async fn fetch_and_replace_binary_unreachable_url_is_error() {
+        let dir = tempfile::tempdir().unwrap();
+        let target = dir.path().join("huskies");
+        let err = fetch_and_replace_binary("http://127.0.0.1:1/huskies", &target)
+            .await
+            .unwrap_err();
+        assert!(!err.is_empty(), "expected a non-empty error");
+    }
+
+    #[tokio::test]
+    async fn persisted_ops_count_does_not_decrease_after_flush() {
+        // Initialise an in-process CRDT, flush it, and verify the persisted
+        // count is stable (AC 5 — no ops lost across upgrade).
+        crate::crdt_state::init_for_test();
+
+        let before = crate::crdt_state::dump_crdt_state(None).persisted_ops_count;
+        crate::crdt_state::flush_persistence(std::time::Duration::from_millis(200)).await;
+        let after = crate::crdt_state::dump_crdt_state(None).persisted_ops_count;
+
+        assert!(
+            after >= before,
+            "persisted_ops_count must not decrease after flush: before={before} after={after}"
+        );
+    }
+}

server/src/validation/mod.rs

@@ -22,7 +22,8 @@ pub use newtypes::{
     AcceptanceCriterion, DependsOnId, Description, StoryId, StoryName, TargetStage,
 };
 pub use requests::{
-    AddCriterionRequest, CreateBugRequest, CreateEpicRequest, CreateRefactorRequest,
-    CreateSpikeRequest, CreateStoryRequest, EditCriterionRequest, FreezeStoryRequest,
-    MoveStoryRequest, MoveStoryToMergeRequest, UnblockStoryRequest, UpdateStoryRequest,
+    AddCriterionRequest, ConvertItemTypeRequest, CreateBugRequest, CreateEpicRequest,
+    CreateRefactorRequest, CreateSpikeRequest, CreateStoryRequest, EditCriterionRequest,
+    FreezeStoryRequest, MoveStoryRequest, MoveStoryToMergeRequest, UnblockStoryRequest,
+    UpdateStoryRequest,
 };

server/src/validation/requests.rs

@@ -1212,6 +1212,81 @@ impl FreezeStoryRequest {
         })
     }
 }
+
+// ---------------------------------------------------------------------------
+// ConvertItemTypeRequest
+// ---------------------------------------------------------------------------
+
+/// Fully validated inputs for the `convert_item_type` MCP tool and `convert` chat command.
+#[derive(Debug)]
+pub struct ConvertItemTypeRequest {
+    /// Validated story identifier.
+    pub story_id: StoryId,
+    /// The target item type.
+    pub new_type: crate::io::story_metadata::ItemType,
+}
+
+impl ConvertItemTypeRequest {
+    /// Parse and validate a `convert_item_type` JSON argument map.
+    ///
+    /// Required fields: `story_id` (work-item filename stem), `new_type`
+    /// (one of `"story"`, `"bug"`, `"spike"`, `"refactor"`, `"epic"`).
+    pub fn from_json(args: &serde_json::Value) -> Result<Self, String> {
+        let mut errors: Vec<ValidationError> = Vec::new();
+
+        let story_id = match args.get("story_id").and_then(|v| v.as_str()) {
+            None => {
+                errors.push(ValidationError::FieldMissing {
+                    field: "story_id".into(),
+                });
+                None
+            }
+            Some(raw) => match StoryId::parse(raw) {
+                Ok(id) => Some(id),
+                Err(mut errs) => {
+                    errors.append(&mut errs);
+                    None
+                }
+            },
+        };
+
+        let new_type = match args.get("new_type").and_then(|v| v.as_str()) {
+            None => {
+                errors.push(ValidationError::FieldMissing {
+                    field: "new_type".into(),
+                });
+                None
+            }
+            Some(raw) => match crate::io::story_metadata::ItemType::from_str(raw) {
+                Some(t) => Some(t),
+                None => {
+                    errors.push(ValidationError::InvalidValue {
+                        field: "new_type".into(),
+                        actual: raw.to_string(),
+                        allowed: vec![
+                            "story".into(),
+                            "bug".into(),
+                            "spike".into(),
+                            "refactor".into(),
+                            "epic".into(),
+                        ],
+                    });
+                    None
+                }
+            },
+        };
+
+        if !errors.is_empty() {
+            return Err(format_errors_as_json(&errors));
+        }
+
+        Ok(ConvertItemTypeRequest {
+            story_id: story_id.unwrap(),
+            new_type: new_type.unwrap(),
+        })
+    }
+}
+
 #[cfg(test)]
 mod tests {
     use super::*;

server/src/worktree/create.rs

@@ -152,9 +152,17 @@ pub fn install_pre_commit_hook(wt_path: &Path) -> Result<(), String> {
     std::fs::set_permissions(&hook_path, std::fs::Permissions::from_mode(0o755))
         .map_err(|e| format!("chmod pre-commit hook: {e}"))?;
 
+    // `git config --worktree` requires `extensions.worktreeConfig = true` on
+    // the repository config; enable it idempotently before the per-worktree
+    // hooks-path set below.  Writing without `--worktree` targets the main
+    // GIT_DIR/config which all worktrees share, so a single call is enough.
+    let _ = std::process::Command::new("git")
+        .args(["config", "extensions.worktreeConfig", "true"])
+        .current_dir(wt_path)
+        .output();
+
     // Point git at the per-worktree hooks dir so only this worktree uses
     // these hooks (not the main repo or other worktrees).
-    // Requires extensions.worktreeConfig = true in the repository config.
     let output = std::process::Command::new("git")
         .args(["config", "--worktree", "core.hooksPath", ".git-hooks"])
         .current_dir(wt_path)
@@ -467,6 +475,54 @@ mod tests {
         );
     }
 
+    /// Regression: before the fix, `install_pre_commit_hook` was called directly
+    /// from an async context, monopolising a tokio worker thread per call.  With
+    /// `worker_threads=2` and two concurrent installs the executor would stall.
+    /// After the fix the installs run on `spawn_blocking`'s thread pool, leaving
+    /// both worker threads free to drive async tasks like the sleep below.
+    #[tokio::test(flavor = "multi_thread", worker_threads = 2)]
+    async fn install_pre_commit_hook_does_not_block_tokio_executor() {
+        let tmp = TempDir::new().unwrap();
+
+        // Helper: create a git repo and a linked worktree inside tmp.
+        let setup = |repo: &str, wt: &str, branch: &str| -> std::path::PathBuf {
+            let repo_path = tmp.path().join(repo);
+            fs::create_dir_all(&repo_path).unwrap();
+            init_git_repo(&repo_path);
+            Command::new("git")
+                .args(["config", "extensions.worktreeConfig", "true"])
+                .current_dir(&repo_path)
+                .output()
+                .unwrap();
+            let wt_path = tmp.path().join(wt);
+            Command::new("git")
+                .args(["worktree", "add", wt_path.to_str().unwrap(), "-b", branch])
+                .current_dir(&repo_path)
+                .output()
+                .unwrap();
+            wt_path
+        };
+
+        let wt1 = setup("repo1", "wt1", "feature/noblock-1");
+        let wt2 = setup("repo2", "wt2", "feature/noblock-2");
+
+        // Both hook installs run on the blocking pool — executor threads stay free.
+        let h1 = tokio::task::spawn_blocking(move || install_pre_commit_hook(&wt1));
+        let h2 = tokio::task::spawn_blocking(move || install_pre_commit_hook(&wt2));
+
+        let start = std::time::Instant::now();
+        tokio::time::sleep(std::time::Duration::from_millis(100)).await;
+        let elapsed = start.elapsed();
+
+        h1.await.unwrap().expect("hook install 1 must succeed");
+        h2.await.unwrap().expect("hook install 2 must succeed");
+
+        assert!(
+            elapsed < std::time::Duration::from_millis(500),
+            "tokio executor was starved; 100 ms sleep took {elapsed:?}"
+        );
+    }
+
     #[test]
     fn install_pre_commit_hook_creates_executable_hook_and_sets_hookspath() {
         let tmp = TempDir::new().unwrap();

start.sh

@@ -0,0 +1,7 @@
+#!/usr/bin/env bash
+# Start huskies via the codesign-heal wrapper.
+#
+# The wrapper at ~/bin/huskies re-signs the underlying binary if needed before
+# exec-ing it, so a missed re-sign after a build/copy never produces a silent
+# SIGKILL on Apple Silicon.
+exec "${HOME}/bin/huskies" "$@"