ref(runtime): Simplify daemon routing and normalize manifests

Remove legacy daemon routing knobs and CLI daemon flags so routing is

driven by tool statefulness plus the explicit xcode-ide special case.

Add idle shutdown with an activity lease registry so long-running tools

signal lifecycle activity without hardcoded daemon imports.

Clean manifest files by removing values that match schema defaults and

regenerate generated tool documentation.

Co-Authored-By: Claude <noreply@anthropic.com>

Author: cameroncooke

CHANGELOG.md

@@ -7,6 +7,11 @@
 
 ### Changed
 - Hide `xcode_tools_bridge_{status,sync,disconnect}` unless `debug: true` is enabled (these are troubleshooting tools).
+- Simplified CLI daemon routing: stateless tools now always execute directly, stateful tools route through daemon with auto-start, and dynamic `xcode-ide` bridge tools remain an explicit daemon-backed special-case.
+- Removed manifest daemon routing knobs `availability.daemon` and `routing.daemonAffinity`; manifests now use `availability.{mcp,cli}` plus optional `routing.stateful`.
+- Removed hidden CLI daemon-routing flags; stateful routing is now automatic and only hidden `--socket` remains for advanced socket override workflows.
+- Added daemon idle shutdown in CLI mode: per-workspace daemons now auto-exit after 10 minutes of inactivity when no active stateful sessions exist.
+- Inverted idle activity tracking to a generic daemon activity registry so long-running tools report lifecycle activity without hardcoded daemon imports.
 
 ## [2.0.0] - 2026-02-02
 

docs/CLI.md

@@ -121,28 +121,34 @@ See [CONFIGURATION.md](CONFIGURATION.md) for the full schema.
 | Variable | Description |
 |----------|-------------|
 | `XCODEBUILDMCP_SOCKET` | Override socket path for all commands |
+| `XCODEBUILDMCP_DAEMON_IDLE_TIMEOUT_MS` | Daemon idle timeout in ms (default `600000`, set `0` to disable) |
 | `XCODEBUILDMCP_DISABLE_SESSION_DEFAULTS` | Disable session defaults |
 
 ## CLI vs MCP Mode
 
 | Feature | CLI (`xcodebuildmcp <tool>`) | MCP (`xcodebuildmcp mcp`) |
 |---------|------------------------------|---------------------------|
 | Invocation | Direct terminal | MCP client (Claude, etc.) |
-| Session state | Per-workspace daemon | In-process |
+| Session state | Stateless direct + daemon for stateful tools | In-process |
 | Use case | Scripts, CI, manual | AI-assisted development |
 | Configuration | Same config.yaml | Same config.yaml |
 
 Both share the same underlying tool implementations.
 
 ## Per-Workspace Daemon
 
-The CLI uses a per-workspace daemon architecture for stateful operations (log capture, video recording, debugging). Each workspace gets its own daemon instance.
+The CLI uses a per-workspace daemon architecture only when needed:
+
+- Stateless tools run directly in the CLI process.
+- Stateful tools route through the daemon (auto-started as needed).
+- Dynamic `xcode-ide` bridge tools are a special-case daemon-backed path for persistent bridge sessions.
 
 ### How It Works
 
 - **Workspace identity**: The workspace root is determined by the location of `.xcodebuildmcp/config.yaml`, or falls back to the current directory.
 - **Socket location**: Each daemon runs on a Unix socket at `~/.xcodebuildmcp/daemons/<workspace-key>/daemon.sock`
 - **Auto-start**: The daemon starts automatically when you invoke a stateful tool - no manual setup required.
+- **Auto-shutdown**: The daemon exits after 10 minutes of inactivity, but only when there are no active stateful sessions (log capture, debugging, video capture, background swift-package processes).
 
 ### Daemon Commands
 
@@ -198,16 +204,6 @@ Daemons:
 Total: 2 (1 running, 1 stale)
 ```
 
-### Opting Out of Daemon
-
-If you want to disable daemon auto-start (stateful tools will error):
-
-```bash
-xcodebuildmcp build-sim --no-daemon --scheme MyApp
-```
-
-This is useful for CI environments or when you want explicit control.
-
 ## Stateful vs Stateless Tools
 
 ### Stateless Tools (run in-process)
@@ -230,8 +226,6 @@ When you invoke a stateful tool, the daemon auto-starts if needed.
 | Option | Description |
 |--------|-------------|
 | `--socket <path>` | Override the daemon socket path (hidden) |
-| `--daemon` | Force daemon execution for stateless tools (hidden) |
-| `--no-daemon` | Disable daemon usage; stateful tools will fail |
 | `-h, --help` | Show help |
 | `-v, --version` | Show version |
 
@@ -266,4 +260,4 @@ The socket directory (`~/.xcodebuildmcp/daemons/`) should have mode 0700. If you
 ```bash
 chmod 700 ~/.xcodebuildmcp
 chmod -R 700 ~/.xcodebuildmcp/daemons
-```
+```

docs/TOOLS-CLI.md

@@ -187,4 +187,4 @@ XcodeBuildMCP provides 71 canonical tools organized into 13 workflow groups.
 
 ---
 
-*This documentation is automatically generated by `scripts/update-tools-docs.ts` from the tools manifest. Last updated: 2026-02-05T21:23:22.870Z UTC*
+*This documentation is automatically generated by `scripts/update-tools-docs.ts` from the tools manifest. Last updated: 2026-02-06T11:40:14.287Z UTC*

docs/TOOLS.md

@@ -202,4 +202,4 @@ This document lists MCP tool names as exposed to MCP clients. XcodeBuildMCP prov
 
 ---
 
-*This documentation is automatically generated by `scripts/update-tools-docs.ts` from the tools manifest. Last updated: 2026-02-05T21:23:22.870Z UTC*
+*This documentation is automatically generated by `scripts/update-tools-docs.ts` from the tools manifest. Last updated: 2026-02-06T11:40:14.287Z UTC*

docs/dev/MANIFEST_FORMAT.md

@@ -56,11 +56,9 @@ description: string     # Tool description (shown in tool listings)
 availability:           # Per-runtime availability flags
   mcp: boolean          # Available via MCP server (default: true)
   cli: boolean          # Available via CLI (default: true)
-  daemon: boolean       # Available via daemon (default: true)
 predicates: string[]    # Predicate names for visibility filtering (default: [])
-routing:                # Daemon routing hints
+routing:                # CLI daemon routing
   stateful: boolean     # Tool maintains state (default: false)
-  daemonAffinity: enum  # 'preferred' or 'required' (optional)
 annotations:            # MCP tool annotations (hints for clients)
   title: string         # Human-readable title (optional)
   readOnlyHint: boolean # Tool only reads data (optional)
@@ -80,11 +78,7 @@ description: "List available iOS simulators."
 availability:
   mcp: true
   cli: true
-  daemon: true
 predicates: []
-routing:
-  stateful: false
-  daemonAffinity: preferred
 annotations:
   title: "List Simulators"
   readOnlyHint: true
@@ -101,12 +95,8 @@ description: "Build for iOS sim."
 availability:
   mcp: true
   cli: true
-  daemon: true
 predicates:
   - hideWhenXcodeAgentMode  # Hidden when Xcode provides equivalent tool
-routing:
-  stateful: false
-  daemonAffinity: preferred
 ```
 
 ### Example: MCP-Only Tool
@@ -120,7 +110,6 @@ description: "Manage enabled workflows at runtime."
 availability:
   mcp: true
   cli: false                # Not available in CLI
-  daemon: false             # Not available via daemon
 predicates:
   - experimentalWorkflowDiscoveryEnabled
 ```
@@ -142,7 +131,6 @@ tools: string[]         # Array of tool IDs belonging to this workflow
 availability:           # Per-runtime availability flags
   mcp: boolean          # Available via MCP server (default: true)
   cli: boolean          # Available via CLI (default: true)
-  daemon: boolean       # Available via daemon (default: true)
 selection:              # MCP selection rules
   mcp:
     defaultEnabled: boolean  # Enabled when config.enabledWorkflows is empty (default: false)
@@ -159,7 +147,6 @@ description: "Complete iOS development workflow for simulators."
 availability:
   mcp: true
   cli: true
-  daemon: true
 selection:
   mcp:
     defaultEnabled: true   # Enabled by default
@@ -183,7 +170,6 @@ description: "Diagnostic tool for the MCP server environment."
 availability:
   mcp: true
   cli: true
-  daemon: true
 selection:
   mcp:
     defaultEnabled: false
@@ -203,7 +189,6 @@ description: "Manage enabled workflows at runtime."
 availability:
   mcp: true
   cli: false
-  daemon: false
 selection:
   mcp:
     defaultEnabled: false
@@ -227,10 +212,8 @@ tools:
 | `description` | string | No | - | Tool description |
 | `availability.mcp` | boolean | No | `true` | Available via MCP |
 | `availability.cli` | boolean | No | `true` | Available via CLI |
-| `availability.daemon` | boolean | No | `true` | Available via daemon |
 | `predicates` | string[] | No | `[]` | Visibility predicates (all must pass) |
 | `routing.stateful` | boolean | No | `false` | Tool maintains state |
-| `routing.daemonAffinity` | enum | No | - | `'preferred'` or `'required'` |
 | `annotations.title` | string | No | - | Human-readable title |
 | `annotations.readOnlyHint` | boolean | No | - | Tool only reads data |
 | `annotations.destructiveHint` | boolean | No | - | Tool may modify/delete data |
@@ -247,7 +230,6 @@ tools:
 | `tools` | string[] | Yes | - | Tool IDs in this workflow |
 | `availability.mcp` | boolean | No | `true` | Available via MCP |
 | `availability.cli` | boolean | No | `true` | Available via CLI |
-| `availability.daemon` | boolean | No | `true` | Available via daemon |
 | `selection.mcp.defaultEnabled` | boolean | No | `false` | Enabled when no workflows configured |
 | `selection.mcp.autoInclude` | boolean | No | `false` | Auto-include when predicates pass |
 | `predicates` | string[] | No | `[]` | Visibility predicates (all must pass) |
@@ -402,11 +384,11 @@ The tool is defined once in `manifests/tools/clean.yaml` but referenced by both
 
 ## Daemon Routing
 
-The `routing` field provides hints for daemon-based execution:
+Daemon routing is intentionally simple:
 
-- **`stateful: true`**: Tool maintains state across calls (e.g., debug sessions)
-- **`daemonAffinity: 'preferred'`**: Prefer daemon execution but fall back to direct
-- **`daemonAffinity: 'required'`**: Must run via daemon (fails if daemon unavailable)
+- **`routing.stateful: true`**: CLI routes this tool through the daemon.
+- **`routing` omitted or `stateful: false`**: CLI runs the tool directly.
+- **Special-case**: dynamic `xcode-ide` bridge tools use daemon-backed routing for bridge session persistence.
 
 ## Validation