---
phase: 01-daemon-decomposition
plan: 03
subsystem: infra
tags: [daemon, refactoring, composition-root, services-extraction, typescript]

# Dependency graph
requires:
  - phase: 01-01
    provides: "models.ts, memory.ts, tools.ts extraction reducing daemon/index.ts to ~458 lines"
  - phase: 01-02
    provides: "routing.ts, agents.ts, channels.ts extraction reducing daemon/index.ts to ~385 lines"
provides:
  - "src/daemon/services.ts — skills, MCP, system prompt, pairing manager, gateway server, service startup, signal handlers"
  - "src/daemon/index.ts as thin 140-line composition root — imports, wiring, lifecycle, DaemonContext"
  - "Phase 1 complete: daemon fully decomposed into 8 focused modules"
affects: [02-config-overlays, 03-live-ops-dashboard]

# Tech tracking
tech-stack:
  added: []
  patterns:
    - "Callback-based late binding: getChannelAgents() callback passed to gateway for deferred token usage reporting"
    - "Type-only imports for values only used in DaemonContext type definition"
    - "Section dividers with Unicode box-drawing comments for scannable composition root"

key-files:
  created:
    - src/daemon/services.ts
  modified:
    - src/daemon/index.ts

key-decisions:
  - "Grouped skills, MCP, pairing, gateway, system prompt, and service startup into one services.ts rather than multiple tiny modules — related service-init code stays together"
  - "Used getChannelAgents callback for late-binding channel agents into gateway token usage reporting"
  - "Converted ModelRouter, McpManager, SkillRegistry, SkillInstaller, GatewayServer to type-only imports in index.ts"

patterns-established:
  - "Composition root pattern: daemon/index.ts is pure wiring — import → init → connect → return"
  - "Services module groups service initialization that shares config/lifecycle dependencies"

# Metrics
duration: ~8min
completed: 2026-02-10
---

# Phase 1 Plan 3: Daemon Composition Root Summary

**Extracted services/skills/MCP/gateway/lifecycle into services.ts (269 lines), achieving 140-line composition root — 87% reduction from 1087-line baseline**

## Performance

- **Duration:** ~8 min (across two sessions)
- **Started:** 2026-02-10T04:19:31Z
- **Completed:** 2026-02-10T04:27:00Z
- **Tasks:** 2
- **Files modified:** 2 (1 created, 1 modified)

## Accomplishments
- Extracted 6 functions into `src/daemon/services.ts`: initSkills(), initMcp(), loadSystemPrompt(), initPairingManager(), createGateway(), startServices()
- Reduced daemon/index.ts from 385 lines (post-Plan 02) to 140 lines — well under the 200-line target
- daemon/index.ts is now a pure composition root: imports → init calls → wire → return DaemonContext
- All 1077 tests pass, zero type errors, zero regressions
- Cumulative reduction: 1087 → 140 lines (87% reduction, 947 lines extracted)

## Task Commits

Each task was committed atomically:

1. **Task 1: Extract services/skills/gateway/MCP into services.ts, clean up index.ts** — `701fcfc` (refactor)
2. **Task 2: Final validation** — No separate commit (validation-only task, all changes in Task 1)

## Files Created/Modified
- `src/daemon/services.ts` — Skills registry/installer, MCP server manager, system prompt assembly, pairing manager, gateway server creation, channel/gateway startup, Tailscale serve, heartbeat monitor, signal handlers (269 lines)
- `src/daemon/index.ts` — Thin composition root with organized imports, section dividers, DaemonContext return (140 lines)

## Decisions Made
- Grouped all remaining service initialization (skills, MCP, pairing, gateway, system prompt, lifecycle startup) into a single `services.ts` rather than multiple tiny modules — these all share config/lifecycle dependencies and are called sequentially
- Used `getChannelAgents()` callback pattern to handle late-binding of channel agents into gateway's token usage reporting — avoids circular dependency between channel registration and gateway creation
- Converted `ModelRouter`, `McpManager`, `SkillRegistry`, `SkillInstaller`, `GatewayServer` to type-only imports in index.ts since they're only referenced in the DaemonContext type definition (values come from factory functions in extracted modules)

## Deviations from Plan

None — plan executed exactly as written. daemon/index.ts was 385 lines as expected, extraction targets matched plan analysis, final line count (140) comfortably under the 200-line target.

## Issues Encountered
None.

## User Setup Required
None — no external service configuration required.

## Next Phase Readiness
- **Phase 1 complete:** daemon/index.ts is a 140-line composition root
- 8 daemon modules total: models.ts (251), memory.ts (99), tools.ts (89), routing.ts (239), agents.ts (48), channels.ts (102), services.ts (269), lifecycle.ts (34) — 1131 lines of extracted logic
- All modules use consistent factory pattern with typed deps/result interfaces
- Phase 2 (Config Overlays) can proceed — config loading changes are low-risk since daemon wiring is now modular
- Phase 3 (Live Ops Dashboard) can proceed — metrics hooks can be wired into individual modules rather than the monolithic god file

## Module Summary (Final State)

| Module | Lines | Responsibility |
|--------|-------|---------------|
| index.ts | 140 | Composition root — imports, wiring, DaemonContext |
| models.ts | 251 | Model client factory, GitHub mapping, auto-fallback, model router |
| services.ts | 269 | Skills, MCP, system prompt, pairing, gateway, service startup |
| routing.ts | 239 | Message router, agent cache, sandbox wiring, audio |
| channels.ts | 102 | All channel adapter registration (8 adapters) |
| memory.ts | 99 | Memory store, vector store, hybrid search, indexer |
| tools.ts | 89 | Tool registry, builtin tools, web search, process/browser managers |
| agents.ts | 48 | Agent config registry, agent router, sandbox manager |
| lifecycle.ts | 34 | Lifecycle state management |
| **Total** | **1271** | **Full daemon initialization** |

---
*Phase: 01-daemon-decomposition*
*Completed: 2026-02-10*

## Self-Check: PASSED

- All 2 files verified present (services.ts, index.ts)
- Task 1 commit verified (701fcfc)
- Line counts match: index.ts=140, services.ts=269
- Typecheck: clean
- Tests: 1077/1077 passed