1jehuang--jcode/docs/UNIFIED_SELFDEV_SERVER_PLAN.md

# Unified Self-Dev / Normal Server Plan

> Status: **Implemented.**
>
> This document is preserved as a historical design/rollout plan. The current
> architecture uses a single shared server, with self-dev handled as a
> session-local canary capability rather than a separate dedicated daemon/socket.
> Any references below to `/tmp/jcode-selfdev.sock`, `canary-wrapper`, or
> `JCODE_SELFDEV_MODE` describe the pre-merge architecture or transition steps,
> not the current runtime design.

## Goal

Reduce RAM usage by removing the dedicated self-dev daemon/socket pair and treating self-dev as a **session capability** on the normal shared server.

Today, normal sessions and self-dev sessions can end up with separate long-lived server processes, which duplicates:

- Tokio runtime overhead
- allocator heap / fragmentation footprint
- MCP pool state
- embedding/model lifecycle machinery
- event buffers, registries, session maps, swarm maps
- general server baseline RSS

## Current Architecture

### Normal mode
- Main socket: runtime `jcode.sock`
- Debug socket: runtime `jcode-debug.sock`
- Startup path: `jcode` -> default client flow -> spawn `jcode serve` if needed

### Self-dev mode
- Main socket: `/tmp/jcode-selfdev.sock`
- Debug socket: `/tmp/jcode-selfdev-debug.sock`
- Startup path:
  - repo auto-detection or `jcode self-dev`
  - `cli/selfdev.rs::run_self_dev()`
  - exec into `canary-wrapper`
  - wrapper ensures self-dev server exists on dedicated socket
  - wrapper launches TUI client against that socket

## Key Finding From Code Inspection

The runtime already supports **per-session self-dev state**:

- protocol `Subscribe { working_dir, selfdev }`
- server subscribe handling can mark only that session as canary/self-dev
- `selfdev` tool availability is already gated on `session.is_canary`
- prompt additions are already gated on `session.is_canary`
- clear/resume/headless flows already preserve or infer canary state per session

This means the main remaining split is not the session model, but the **startup / reload / wrapper plumbing**.

## Target Architecture

### One shared server
- Main socket: runtime `jcode.sock`
- Debug socket: runtime `jcode-debug.sock`
- Self-dev sessions connect to the same server as normal sessions

### Self-dev becomes session-local
A client is self-dev if any of the following are true:
- explicit `jcode self-dev`
- current working directory is the jcode repo (auto-detected)
- resumed session is already canary

That client connects to the shared server and sends:
- `working_dir`
- `selfdev: true`

The server then:
- marks the session canary
- registers selfdev tools for that session
- includes selfdev prompt additions for that session only

### Debug socket
With one shared server, there is one shared debug socket.

Consequences:
- no dedicated self-dev debug socket
- debug tooling sees both normal and self-dev sessions from the same server
- selfdev-sensitive actions remain gated by target session canary state

## Important Policy Decision

If a self-dev session triggers a reload, it reloads the **shared server**.
That means all clients reconnect.

This is the cleanest design for RAM savings.

The binary chosen for reload should depend on the **triggering session**, not a server-global self-dev mode flag:

- normal session reload -> stable / launcher candidate
- canary session reload -> repo / canary candidate

## Implementation Phases

### Phase 1 - Client-side self-dev on shared server path
**Goal:** stop repo auto-detection from forcing a separate self-dev daemon.

Changes:
- do not auto-divert repo startup into `canary-wrapper`
- introduce a client-only self-dev signal (separate from server self-dev env)
- keep using normal server spawn/connect path
- continue sending `Subscribe { selfdev: true }`
- prevent the shared server child process from inheriting the client-only self-dev env
- stop server self-dev detection from inferring self-dev based on current working directory

Expected result:
- opening jcode inside the repo uses the shared server path by default
- session still becomes canary/self-dev
- explicit `jcode self-dev` command may still use legacy wrapper temporarily

### Phase 2 - Move explicit `jcode self-dev` onto shared server path
**Goal:** make explicit self-dev command use the same shared-server flow.

Changes:
- simplify `cli/selfdev.rs::run_self_dev()`
- keep optional `cargo build --release`
- set client-only self-dev mode
- connect through normal client/server startup path
- remove need for `canary-wrapper` in standard usage

Expected result:
- both auto-detected self-dev and explicit `jcode self-dev` share one server

### Phase 3 - Session-targeted reload selection
**Goal:** remove server-global self-dev assumptions from reload/update behavior.

Changes:
- include triggering session context in reload handling
- choose server exec target based on triggering session canary state
- always run reload monitor on the shared server, but authorize via session state / request policy

Expected result:
- one shared server can still reload into the right binary

### Phase 4 - Remove dedicated self-dev socket assumptions
**Goal:** fully retire the separate socket model.

Changes:
- deprecate `/tmp/jcode-selfdev.sock` and `/tmp/jcode-selfdev-debug.sock`
- update docs, tests, and scripts that probe self-dev via separate sockets
- simplify debug/test tooling to use the shared debug socket

## Risks / Tradeoffs

### Shared reload impact
A self-dev-triggered reload affects all clients on the shared server.
This is the main behavior change and the key tradeoff for RAM savings.

### Legacy tooling assumptions
Some scripts and tests currently prefer the self-dev debug socket path and will need updating.

### Scattered env-based logic
There are multiple `JCODE_SELFDEV_MODE` checks across startup, hot reload, and server behavior; these need to be separated into:
- client self-dev request
- server self-dev mode (legacy / compatibility)
- session canary capability

## Files Likely To Change

- `src/cli/dispatch.rs`
- `src/cli/selfdev.rs`
- `src/cli/hot_exec.rs`
- `src/server.rs`
- `src/server/reload.rs`
- `src/server/client_session.rs`
- `src/tui/mod.rs`
- `src/tui/backend.rs`
- `docs/SERVER_ARCHITECTURE.md`
- debug/test scripts that assume separate self-dev sockets

## Recommended Order

1. Land Phase 1 foundations and shared-path client self-dev
2. Land explicit `jcode self-dev` shared-path behavior
3. Refactor reload/update selection to be session-targeted
4. Remove legacy wrapper/socket assumptions and update tests/docs