# spacesh M4 Implementation Plan — CLI + status primitive

> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.

**Goal:** Ship the `spacesh` CLI (a one-shot client at full bus parity minus interactive panels) and the `set_state`/`state` status primitive (5 ephemeral states stored in the daemon, emitted as a `state` event, surfaced in `status`).

**Architecture:** New `spacesh-cli` crate produces the `spacesh` binary with a small blocking-over-async one-shot UDS client built on `spacesh-proto`'s codec. The daemon gains an in-memory per-surface `SurfaceState` map (not persisted), a `SetState` command, and a `State` event. Both daemon and CLI honor `SPACESH_SOCK` to locate the socket (defaults to `~/.spacesh/sock`), which also isolates tests.

**Tech Stack:** Rust — clap + clap_complete (CLI), tokio (net/rt), serde_json, anyhow; builds on the shipped M0–M2 crates.

**Spec:** `DOCS/superpowers/specs/2026-06-09-spacesh-m4-design.md`. Base: `DOCS/MAIN.md` §5/§7.4/§10.1/§12.

**Conventions:** English code/comments. `cargo test --workspace` is the DoD and must stay green & non-flaky — new socket/PTY integration tests use `#[tokio::test(flavor = "multi_thread", worker_threads = 2)]` + a `serial()` guard (the daemon crate already has `crate::test_support::serial()`; the CLI crate introduces its own). Commit after each task; append:
`Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>`. Do not `git push`.

---

## File Structure

```
Cargo.toml                          # + crates/spacesh-cli workspace member
crates/spacesh-proto/src/
  status.rs   (new)                 # SurfaceState enum
  message.rs                        # + Cmd::SetState, Evt::State
  workspace.rs                      # + SurfaceView.state
  lib.rs                            # + re-exports
crates/spaceshd/src/
  registry.rs                       # + states map (idle on spawn / drop on exit) + state in to_view
  server.rs                         # + Cmd::SetState dispatch + Evt::State; init idle on every spawn; drop on exit
  lifecycle.rs                      # + SPACESH_SOCK env override in socket_path()
crates/spacesh-cli/   (new)
  Cargo.toml
  src/
    main.rs                         # clap parse -> dispatch -> exit code
    cli.rs                          # clap derive types (Cli, Sub, arg enums)
    mapping.rs                      # Sub -> proto Cmd (pure, unit-tested)
    client.rs                       # one-shot UDS: ensure_daemon, request, notify
    output.rs                       # render res (human / --json), status table
```

---

## Phase 1 — proto: status primitive

### Task 1: SurfaceState + SetState/State + SurfaceView.state

**Files:**
- Create: `crates/spacesh-proto/src/status.rs`
- Modify: `crates/spacesh-proto/src/message.rs`, `crates/spacesh-proto/src/workspace.rs`, `crates/spacesh-proto/src/lib.rs`

- [ ] **Step 1: SurfaceState enum + test**

Create `crates/spacesh-proto/src/status.rs`:
```rust
use serde::{Deserialize, Serialize};

/// Ephemeral agent-activity status of a running surface (orthogonal to the
/// running/stopped process lifecycle). Defaults to `Idle`.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum SurfaceState {
    Work,
    Wait,
    Done,
    Error,
    #[default]
    Idle,
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn serializes_snake_case() {
        assert_eq!(serde_json::to_string(&SurfaceState::Work).unwrap(), r#""work""#);
        assert_eq!(serde_json::to_string(&SurfaceState::Idle).unwrap(), r#""idle""#);
    }

    #[test]
    fn default_is_idle() {
        assert_eq!(SurfaceState::default(), SurfaceState::Idle);
    }

    #[test]
    fn round_trips() {
        for s in [SurfaceState::Work, SurfaceState::Wait, SurfaceState::Done, SurfaceState::Error, SurfaceState::Idle] {
            let j = serde_json::to_string(&s).unwrap();
            let back: SurfaceState = serde_json::from_str(&j).unwrap();
            assert_eq!(back, s);
        }
    }
}
```

- [ ] **Step 2: Add `state` to SurfaceView**

In `crates/spacesh-proto/src/workspace.rs`, add the import and the field. Change the top import:
```rust
use crate::status::SurfaceState;
```
And add the field to `SurfaceView`:
```rust
pub struct SurfaceView {
    pub spec: SurfaceSpec,
    /// true = has a live actor/PTY; false = stopped (in tree, no process).
    pub running: bool,
    /// Ephemeral agent-activity status (meaningful while running).
    #[serde(default)]
    pub state: SurfaceState,
}
```

- [ ] **Step 3: Add SetState command and State event**

In `crates/spacesh-proto/src/message.rs`, add the import:
```rust
use crate::status::SurfaceState;
```
Add to `enum Cmd` (before `Status`):
```rust
    SetState { surface_id: SurfaceId, state: SurfaceState },
```
Add to `enum Evt`:
```rust
    State { surface_id: SurfaceId, state: SurfaceState },
```

- [ ] **Step 4: Wire lib.rs**

`crates/spacesh-proto/src/lib.rs`:
```rust
pub mod codec;
pub mod ids;
pub mod layout;
pub mod message;
pub mod status;
pub mod workspace;

pub use ids::{GroupId, SurfaceId, WorkspaceId};
pub use layout::{LayoutNode, Orient};
pub use message::{Cmd, Envelope, ErrorBody, Evt};
pub use status::SurfaceState;
pub use workspace::{Group, SurfaceSpec, SurfaceView, Workspace, WorkspaceView};
```

- [ ] **Step 5: Add proto round-trip tests for the new variants**

Append to the `tests` module in `crates/spacesh-proto/src/message.rs`:
```rust
    #[test]
    fn set_state_round_trips() {
        let env = Envelope::Req {
            id: 1,
            cmd: Cmd::SetState { surface_id: SurfaceId("s_1".into()), state: crate::status::SurfaceState::Done },
        };
        let back: Envelope = serde_json::from_str(&serde_json::to_string(&env).unwrap()).unwrap();
        assert_eq!(back, env);
    }

    #[test]
    fn state_event_round_trips() {
        let evt = Envelope::Evt(Evt::State { surface_id: SurfaceId("s_1".into()), state: crate::status::SurfaceState::Wait });
        let j = serde_json::to_string(&evt).unwrap();
        assert!(j.contains(r#""evt":"state""#));
        let back: Envelope = serde_json::from_str(&j).unwrap();
        assert_eq!(back, evt);
    }
```

- [ ] **Step 6: Run tests**

Run: `cargo test -p spacesh-proto`
Expected: PASS (all proto tests incl. status + 2 new message tests). Note: the daemon will NOT compile after this task (its `to_view` is missing the new `state` field and its `match cmd` lacks `SetState`) — that is expected and fixed in Task 2. Verify proto in isolation only.

- [ ] **Step 7: Commit**

```bash
git add crates/spacesh-proto/src/status.rs crates/spacesh-proto/src/message.rs crates/spacesh-proto/src/workspace.rs crates/spacesh-proto/src/lib.rs
git commit -m "feat(proto): SurfaceState + SetState command + State event + SurfaceView.state"
```

---

## Phase 2 — daemon: status storage & dispatch

### Task 2: states map, SetState dispatch, idle-on-spawn, drop-on-exit, SPACESH_SOCK

**Files:**
- Modify: `crates/spaceshd/src/registry.rs`, `crates/spaceshd/src/server.rs`, `crates/spaceshd/src/lifecycle.rs`

- [ ] **Step 1: Add the states map to the registry**

In `crates/spaceshd/src/registry.rs`:

Add the import:
```rust
use spacesh_proto::status::SurfaceState;
```
Add the field to `struct Registry`:
```rust
    /// Ephemeral per-surface status. In-memory only (never persisted).
    states: HashMap<SurfaceId, SurfaceState>,
```
Add these methods inside `impl Registry` (near the live-actor section):
```rust
    pub fn set_state(&mut self, sid: &SurfaceId, state: SurfaceState) {
        self.states.insert(sid.clone(), state);
    }
    pub fn state(&self, sid: &SurfaceId) -> SurfaceState {
        self.states.get(sid).copied().unwrap_or_default()
    }
    pub fn drop_state(&mut self, sid: &SurfaceId) {
        self.states.remove(sid);
    }
```
Update `to_view` to include the state:
```rust
    fn to_view(&self, w: &Workspace) -> WorkspaceView {
        let surfaces = w.surfaces.iter().map(|(sid, spec)| {
            (sid.clone(), SurfaceView {
                spec: spec.clone(),
                running: self.live.contains_key(sid),
                state: self.state(sid),
            })
        }).collect();
        WorkspaceView {
            id: w.id.clone(), path: w.path.clone(), name: w.name.clone(),
            group_id: w.group_id.clone(), order: w.order, unread: w.unread,
            layout: w.layout.clone(), surfaces,
        }
    }
```
Also clear states in `restore` (cold start): add `self.states.clear();` next to `self.live.clear();`.

- [ ] **Step 2: Add registry unit tests**

Append to the `tests` module in `registry.rs`:
```rust
    #[test]
    fn state_defaults_idle_and_can_be_set() {
        let mut r = Registry::new();
        let (ws, _) = r.open_workspace(std::env::temp_dir());
        let sid = r.new_surface_id();
        r.add_surface_spec(&ws, sid.clone(), spec());
        assert_eq!(r.state(&sid), spacesh_proto::status::SurfaceState::Idle);
        r.set_state(&sid, spacesh_proto::status::SurfaceState::Work);
        assert_eq!(r.state(&sid), spacesh_proto::status::SurfaceState::Work);
        let v = r.workspace_view(&ws).unwrap();
        assert_eq!(v.surfaces.get(&sid).unwrap().state, spacesh_proto::status::SurfaceState::Work);
    }

    #[test]
    fn drop_state_resets_to_idle() {
        let mut r = Registry::new();
        let (ws, _) = r.open_workspace(std::env::temp_dir());
        let sid = r.new_surface_id();
        r.add_surface_spec(&ws, sid.clone(), spec());
        r.set_state(&sid, spacesh_proto::status::SurfaceState::Error);
        r.drop_state(&sid);
        assert_eq!(r.state(&sid), spacesh_proto::status::SurfaceState::Idle);
    }
```

- [ ] **Step 3: SPACESH_SOCK override in lifecycle**

In `crates/spaceshd/src/lifecycle.rs`, replace `socket_path`:
```rust
pub fn socket_path() -> Result<PathBuf> {
    if let Ok(p) = std::env::var("SPACESH_SOCK") {
        if !p.is_empty() {
            return Ok(PathBuf::from(p));
        }
    }
    Ok(spacesh_dir()?.join("sock"))
}
```
Add a test in `lifecycle.rs` tests module:
```rust
    #[test]
    fn socket_path_honors_env_override() {
        // Note: set/remove around the assertion; tests in this module run serially enough,
        // but guard by restoring afterwards.
        std::env::set_var("SPACESH_SOCK", "/tmp/spacesh-test-override.sock");
        let p = socket_path().unwrap();
        std::env::remove_var("SPACESH_SOCK");
        assert_eq!(p, std::path::PathBuf::from("/tmp/spacesh-test-override.sock"));
    }
```

- [ ] **Step 4: Initialize idle on every spawn; drop on exit; dispatch SetState**

In `crates/spaceshd/src/server.rs`:

(a) After EACH place that calls `reg.set_live(handle)` for a newly spawned surface — there are four: `NewSurface`, `SplitSurface`, `ApplyPreset` (inside the loop), `RestartSurface` — add an idle init right after `set_live`. For the single-surface handlers:
```rust
                    reg.set_live(handle);
                    reg.set_state(&sid, spacesh_proto::status::SurfaceState::Idle);
```
(use `new_sid` in `SplitSurface`, `surface_id` in `RestartSurface`, the loop's `new_sid` in `ApplyPreset`).

(b) In the `router`'s `ServerMsg::Exit` arm, drop the state alongside `mark_stopped`:
```rust
            ServerMsg::Exit { surface_id, code } => {
                reg.mark_stopped(&surface_id);
                reg.drop_state(&surface_id);
                let evt = Envelope::Evt(Evt::Exit { surface_id: surface_id.clone(), code });
                broadcast_evt(&clients, &evt);
            }
```

(c) Add the `Cmd::SetState` arm to `handle_request` (place it near `Cmd::RestartSurface`):
```rust
        Cmd::SetState { surface_id, state } => {
            if reg.is_running(&surface_id) {
                reg.set_state(&surface_id, state);
                broadcast_evt(clients, &Envelope::Evt(Evt::State { surface_id: surface_id.clone(), state }));
                let _ = out.send(ok(id, serde_json::Value::Null)).await;
            } else {
                // unknown or stopped surface — status is only meaningful while running.
                let _ = out.send(err(id, "NOT_FOUND", "surface not running")).await;
            }
        }
```

- [ ] **Step 5: Add a daemon integration test for SetState**

Append to the `tests` module in `server.rs` (mirror the existing integration-test scaffolding — `tempdir_path`, `wait_for_socket`, `req`, `res_data`, the store construction):
```rust
    #[tokio::test(flavor = "multi_thread", worker_threads = 2)]
    async fn set_state_updates_status_and_emits_event() {
        let _serial = crate::test_support::serial();
        let dir = tempdir_path();
        let sock = dir.join("sock");
        let store: std::sync::Arc<dyn crate::state_store::StateStore> =
            std::sync::Arc::new(crate::state_store::JsonStateStore::new(dir.join("state.json")));
        let sock2 = sock.clone();
        tokio::spawn(async move { let _ = serve(&sock2, store).await; });
        wait_for_socket(&sock).await;
        let mut s = UnixStream::connect(&sock).await.unwrap();

        let r = req(&mut s, 1, Cmd::Open { path: std::env::temp_dir().to_string_lossy().into() }).await;
        let ws = res_data(&r)["workspace_id"].as_str().unwrap().to_string();
        let r = req(&mut s, 2, Cmd::NewSurface {
            workspace_id: spacesh_proto::WorkspaceId(ws.clone()),
            command: Some("/bin/sh".into()),
            args: vec!["-c".into(), "sleep 1".into()],
            cols: 80, rows: 24,
        }).await;
        let sid = res_data(&r)["surface_id"].as_str().unwrap().to_string();
        let surface_id = spacesh_proto::SurfaceId(sid.clone());

        // set_state on the running surface
        let r = req(&mut s, 3, Cmd::SetState { surface_id: surface_id.clone(), state: spacesh_proto::status::SurfaceState::Work }).await;
        assert!(matches!(r, Envelope::Res { ok: true, .. }));

        // status reflects it
        let r = req(&mut s, 4, Cmd::Status).await;
        let wss = res_data(&r)["workspaces"].as_array().unwrap();
        let w0 = wss.iter().find(|w| w["id"] == ws).unwrap();
        assert_eq!(w0["surfaces"][&sid]["state"], "work");

        // unknown surface -> NOT_FOUND
        let r = req(&mut s, 5, Cmd::SetState { surface_id: spacesh_proto::SurfaceId("s_nope".into()), state: spacesh_proto::status::SurfaceState::Done }).await;
        match r { Envelope::Res { ok, error, .. } => { assert!(!ok); assert_eq!(error.unwrap().code, "NOT_FOUND"); }, _ => panic!() }
    }
```

- [ ] **Step 6: Run the full suite (3×)**

Run: `cargo test --workspace > /tmp/m4.log 2>&1; echo EXIT=$?` — three times, all 0.
Expected: proto + daemon (incl. new tests) green.

- [ ] **Step 7: Commit**

```bash
git add crates/spaceshd/src/registry.rs crates/spaceshd/src/server.rs crates/spaceshd/src/lifecycle.rs
git commit -m "feat(daemon): per-surface status (set_state/state), idle-on-spawn, SPACESH_SOCK override"
```

---

## Phase 3 — spacesh-cli

### Task 3: CLI scaffold — crate, clap tree, client, mapping (with unit tests)

**Files:**
- Modify: `Cargo.toml` (workspace members)
- Create: `crates/spacesh-cli/Cargo.toml`, `crates/spacesh-cli/src/main.rs`, `cli.rs`, `mapping.rs`, `client.rs`

- [ ] **Step 1: Add to workspace + crate manifest**

In the root `Cargo.toml` `[workspace] members`, add `"crates/spacesh-cli"`. Add to `[workspace.dependencies]`:
```toml
clap = { version = "4", features = ["derive"] }
clap_complete = "4"
```

Create `crates/spacesh-cli/Cargo.toml` (lib + bin so integration tests can call the real client/mapping):
```toml
[package]
name = "spacesh-cli"
edition.workspace = true
version.workspace = true

[lib]
name = "spacesh_cli"
path = "src/lib.rs"

[[bin]]
name = "spacesh"
path = "src/main.rs"

[dependencies]
spacesh-proto = { path = "../spacesh-proto" }
clap.workspace = true
clap_complete.workspace = true
tokio = { workspace = true }
serde_json.workspace = true
anyhow.workspace = true
```

- [ ] **Step 2: clap types**

Create `crates/spacesh-cli/src/cli.rs`:
```rust
use clap::{Parser, Subcommand, ValueEnum};

#[derive(Parser, Debug)]
#[command(name = "spacesh", about = "spacesh CLI — thin client to the spacesh daemon")]
pub struct Cli {
    /// Print raw JSON instead of human output.
    #[arg(long, global = true)]
    pub json: bool,
    #[command(subcommand)]
    pub cmd: Sub,
}

#[derive(ValueEnum, Clone, Copy, Debug, PartialEq)]
pub enum StateArg { Work, Wait, Done, Error, Idle }

#[derive(ValueEnum, Clone, Copy, Debug, PartialEq)]
pub enum DirArg { Right, Down }

#[derive(ValueEnum, Clone, Copy, Debug, PartialEq)]
pub enum EdgeArg { Left, Right, Top, Bottom }

#[derive(Subcommand, Debug)]
pub enum Sub {
    Open { path: String },
    Status,
    NewSurface {
        workspace_id: String,
        #[arg(long)] cmd: Option<String>,
        #[arg(long = "arg")] args: Vec<String>,
        #[arg(long, default_value_t = 80)] cols: u16,
        #[arg(long, default_value_t = 24)] rows: u16,
    },
    Split {
        surface_id: String,
        #[arg(long, value_enum, default_value_t = DirArg::Right)] dir: DirArg,
        #[arg(long)] cmd: Option<String>,
        #[arg(long = "arg")] args: Vec<String>,
    },
    Close { surface_id: String },
    Focus { surface_id: String },
    Restart { surface_id: String },
    Notify {
        #[arg(long)] surface: String,
        #[arg(long, value_enum)] state: StateArg,
    },
    ApplyPreset {
        workspace_id: String,
        #[arg(long)] preset: String,
        #[arg(long = "agent")] agents: Vec<String>,
    },
    SetRatios {
        workspace_id: String,
        #[arg(long, value_delimiter = ',')] path: Vec<u32>,
        #[arg(long, value_delimiter = ',')] ratios: Vec<f32>,
    },
    Move {
        surface_id: String,
        #[arg(long)] target: String,
        #[arg(long, value_enum)] edge: EdgeArg,
    },
    CloseWorkspace { workspace_id: String },
    Group {
        #[command(subcommand)] action: GroupAction,
    },
    SetMeta {
        workspace_id: String,
        #[arg(long)] name: Option<String>,
        #[arg(long)] group: Option<String>,
        #[arg(long)] unread: Option<bool>,
        #[arg(long)] order: Option<u32>,
    },
    Shutdown,
    Completions { shell: clap_complete::Shell },
}

#[derive(Subcommand, Debug)]
pub enum GroupAction {
    Create { #[arg(long)] name: String, #[arg(long)] color: String },
    Set { group_id: String, #[arg(long)] name: Option<String>, #[arg(long)] color: Option<String>, #[arg(long)] order: Option<u32> },
    Delete { group_id: String },
}
```

- [ ] **Step 3: Write the mapping + its failing tests**

Create `crates/spacesh-cli/src/mapping.rs`:
```rust
use spacesh_proto::ids::{GroupId, SurfaceId, WorkspaceId};
use spacesh_proto::message::{Cmd, Edge, PresetSlot, SplitDir};
use spacesh_proto::status::SurfaceState;
use crate::cli::{DirArg, EdgeArg, GroupAction, StateArg, Sub};

pub fn state_of(a: StateArg) -> SurfaceState {
    match a {
        StateArg::Work => SurfaceState::Work,
        StateArg::Wait => SurfaceState::Wait,
        StateArg::Done => SurfaceState::Done,
        StateArg::Error => SurfaceState::Error,
        StateArg::Idle => SurfaceState::Idle,
    }
}

/// Map a parsed subcommand to a bus command. `Completions` has no Cmd (handled
/// before dispatch), so callers must not pass it here.
pub fn to_cmd(sub: Sub) -> Cmd {
    match sub {
        Sub::Open { path } => Cmd::Open { path },
        Sub::Status => Cmd::Status,
        Sub::NewSurface { workspace_id, cmd, args, cols, rows } => Cmd::NewSurface {
            workspace_id: WorkspaceId(workspace_id), command: cmd, args, cols, rows,
        },
        Sub::Split { surface_id, dir, cmd, args } => Cmd::SplitSurface {
            surface_id: SurfaceId(surface_id),
            dir: match dir { DirArg::Right => SplitDir::Right, DirArg::Down => SplitDir::Down },
            command: cmd, args,
        },
        Sub::Close { surface_id } => Cmd::Close { surface_id: SurfaceId(surface_id) },
        Sub::Focus { surface_id } => Cmd::Focus { surface_id: SurfaceId(surface_id) },
        Sub::Restart { surface_id } => Cmd::RestartSurface { surface_id: SurfaceId(surface_id) },
        Sub::Notify { surface, state } => Cmd::SetState { surface_id: SurfaceId(surface), state: state_of(state) },
        Sub::ApplyPreset { workspace_id, preset, agents } => Cmd::ApplyPreset {
            workspace_id: WorkspaceId(workspace_id),
            preset_id: preset,
            slots: agents.into_iter().map(|a| if a == "shell" {
                PresetSlot { command: None, args: vec![] }
            } else {
                PresetSlot { command: Some(a), args: vec![] }
            }).collect(),
        },
        Sub::SetRatios { workspace_id, path, ratios } => Cmd::SetRatios {
            workspace_id: WorkspaceId(workspace_id), node_path: path, ratios,
        },
        Sub::Move { surface_id, target, edge } => Cmd::MoveSurface {
            surface_id: SurfaceId(surface_id),
            target_surface_id: SurfaceId(target),
            edge: match edge { EdgeArg::Left => Edge::Left, EdgeArg::Right => Edge::Right, EdgeArg::Top => Edge::Top, EdgeArg::Bottom => Edge::Bottom },
        },
        Sub::CloseWorkspace { workspace_id } => Cmd::CloseWorkspace { workspace_id: WorkspaceId(workspace_id) },
        Sub::Group { action } => match action {
            GroupAction::Create { name, color } => Cmd::CreateGroup { name, color },
            GroupAction::Set { group_id, name, color, order } => Cmd::SetGroup { group_id: GroupId(group_id), name, color, order },
            GroupAction::Delete { group_id } => Cmd::DeleteGroup { group_id: GroupId(group_id) },
        },
        Sub::SetMeta { workspace_id, name, group, unread, order } => Cmd::SetWorkspaceMeta {
            workspace_id: WorkspaceId(workspace_id),
            name,
            // None = no change; Some("") = ungroup; Some(g) = set group.
            group_id: group.map(|g| if g.is_empty() { None } else { Some(GroupId(g)) }),
            unread,
            order,
        },
        Sub::Shutdown => Cmd::Shutdown,
        Sub::Completions { .. } => unreachable!("completions handled before dispatch"),
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::cli::Cli;
    use clap::Parser;

    fn parse(argv: &[&str]) -> Sub {
        Cli::try_parse_from(argv).unwrap().cmd
    }

    #[test]
    fn notify_maps_to_set_state() {
        let cmd = to_cmd(parse(&["spacesh", "notify", "--surface", "s_1", "--state", "done"]));
        assert!(matches!(cmd, Cmd::SetState { state: SurfaceState::Done, .. }));
    }

    #[test]
    fn split_default_dir_is_right() {
        let cmd = to_cmd(parse(&["spacesh", "split", "s_1"]));
        match cmd { Cmd::SplitSurface { dir, .. } => assert_eq!(dir, SplitDir::Right), _ => panic!() }
    }

    #[test]
    fn set_ratios_parses_csv() {
        let cmd = to_cmd(parse(&["spacesh", "set-ratios", "w_1", "--path", "0,1", "--ratios", "0.3,0.7"]));
        match cmd { Cmd::SetRatios { node_path, ratios, .. } => { assert_eq!(node_path, vec![0,1]); assert_eq!(ratios, vec![0.3,0.7]); }, _ => panic!() }
    }

    #[test]
    fn apply_preset_shell_agent_is_empty_slot() {
        let cmd = to_cmd(parse(&["spacesh", "apply-preset", "w_1", "--preset", "2lr", "--agent", "shell", "--agent", "claude"]));
        match cmd {
            Cmd::ApplyPreset { slots, .. } => {
                assert!(slots[0].command.is_none());
                assert_eq!(slots[1].command.as_deref(), Some("claude"));
            }
            _ => panic!(),
        }
    }

    #[test]
    fn set_meta_group_empty_means_ungroup() {
        let cmd = to_cmd(parse(&["spacesh", "set-meta", "w_1", "--group", ""]));
        match cmd { Cmd::SetWorkspaceMeta { group_id, .. } => assert_eq!(group_id, Some(None)), _ => panic!() }
    }
}
```

- [ ] **Step 4: One-shot client**

Create `crates/spacesh-cli/src/client.rs`:
```rust
use std::path::PathBuf;
use anyhow::{anyhow, Context, Result};
use serde_json::Value;
use spacesh_proto::codec::{read_frame, write_frame};
use spacesh_proto::{Cmd, Envelope};
use tokio::net::UnixStream;

pub fn socket_path() -> PathBuf {
    if let Ok(p) = std::env::var("SPACESH_SOCK") {
        if !p.is_empty() {
            return PathBuf::from(p);
        }
    }
    let home = std::env::var("HOME").unwrap_or_else(|_| ".".into());
    PathBuf::from(home).join(".spacesh").join("sock")
}

/// Connect, lazy-starting the daemon if the socket is absent.
async fn connect_or_start() -> Result<UnixStream> {
    let sock = socket_path();
    if let Ok(s) = UnixStream::connect(&sock).await {
        return Ok(s);
    }
    // Locate the daemon next to this binary and spawn it.
    let exe = std::env::current_exe().context("current_exe")?;
    let daemon = exe.with_file_name("spaceshd");
    let _ = std::process::Command::new(daemon).spawn();
    for _ in 0..100 {
        if let Ok(s) = UnixStream::connect(&sock).await {
            return Ok(s);
        }
        tokio::time::sleep(std::time::Duration::from_millis(30)).await;
    }
    Err(anyhow!("daemon unavailable"))
}

/// One-shot request/response. Skips any interleaved events; returns `data` on ok.
pub async fn request(cmd: Cmd) -> Result<Value> {
    let mut stream = connect_or_start().await?;
    send_and_read(&mut stream, cmd).await
}

/// Best-effort status notify: connect only (no spawn); silently succeed if absent.
pub async fn notify(cmd: Cmd) -> Result<()> {
    let sock = socket_path();
    let Ok(mut stream) = UnixStream::connect(&sock).await else {
        return Ok(()); // no daemon — best-effort no-op
    };
    let _ = send_and_read(&mut stream, cmd).await;
    Ok(())
}

async fn send_and_read(stream: &mut UnixStream, cmd: Cmd) -> Result<Value> {
    write_frame(stream, &Envelope::Req { id: 1, cmd }).await.map_err(|e| anyhow!(e.to_string()))?;
    loop {
        match read_frame(stream).await.map_err(|e| anyhow!(e.to_string()))? {
            Some(Envelope::Res { id: 1, ok, data, error }) => {
                if ok {
                    return Ok(data);
                }
                let (code, msg) = error.map(|e| (e.code, e.msg)).unwrap_or_else(|| ("ERROR".into(), "error".into()));
                return Err(anyhow!("{code}: {msg}"));
            }
            Some(_) => continue, // events / non-matching res
            None => return Err(anyhow!("connection closed")),
        }
    }
}
```

- [ ] **Step 5: lib.rs (module roots) + thin main.rs**

Create `crates/spacesh-cli/src/lib.rs`:
```rust
pub mod cli;
pub mod client;
pub mod mapping;
pub mod output;
```

Create `crates/spacesh-cli/src/main.rs`:
```rust
use clap::Parser;
use spacesh_cli::cli::Cli;
use spacesh_cli::output;

#[tokio::main(flavor = "multi_thread", worker_threads = 2)]
async fn main() {
    let parsed = Cli::parse();
    std::process::exit(output::run(parsed).await);
}
```

(`output::run` is created in Task 4. To make Task 3 compile on its own, create a temporary `output.rs` with a stub `pub async fn run(_c: crate::cli::Cli) -> i32 { 0 }`, replaced fully in Task 4. The modules in `mapping.rs`/`client.rs`/`cli.rs`/`output.rs` reference each other via `crate::...` — correct under the lib root.)

Temporary `crates/spacesh-cli/src/output.rs`:
```rust
pub async fn run(_c: crate::cli::Cli) -> i32 { 0 }
```

- [ ] **Step 6: Run mapping tests**

Run: `cargo test -p spacesh-cli mapping`
Expected: PASS (5 tests). Also `cargo build -p spacesh-cli` succeeds.

- [ ] **Step 7: Commit**

```bash
git add Cargo.toml crates/spacesh-cli/
git commit -m "feat(cli): spacesh-cli scaffold — clap tree, one-shot client, command mapping"
```

---

### Task 4: dispatch, output rendering, completions

**Files:**
- Modify: `crates/spacesh-cli/src/output.rs` (replace the stub)

- [ ] **Step 1: Implement run + rendering**

Replace `crates/spacesh-cli/src/output.rs`:
```rust
use clap::CommandFactory;
use serde_json::Value;
use crate::cli::{Cli, Sub};
use crate::{client, mapping};

/// Entry point: returns the process exit code.
pub async fn run(cli: Cli) -> i32 {
    // Completions are local — no daemon.
    if let Sub::Completions { shell } = cli.cmd {
        let mut cmd = Cli::command();
        clap_complete::generate(shell, &mut cmd, "spacesh", &mut std::io::stdout());
        return 0;
    }

    // notify is best-effort: never fails the caller.
    if let Sub::Notify { .. } = &cli.cmd {
        let _ = client::notify(mapping::to_cmd(cli.cmd)).await;
        return 0;
    }

    let is_status = matches!(cli.cmd, Sub::Status);
    let cmd = mapping::to_cmd(cli.cmd);
    match client::request(cmd).await {
        Ok(data) => {
            if cli.json {
                println!("{}", serde_json::to_string_pretty(&data).unwrap_or_else(|_| "null".into()));
            } else if is_status {
                print_status(&data);
            } else {
                print_human(&data);
            }
            0
        }
        Err(e) => {
            if cli.json {
                println!("{}", serde_json::json!({ "ok": false, "error": e.to_string() }));
            } else {
                eprintln!("{e}");
            }
            1
        }
    }
}

/// Human render for non-status commands: surface the salient id, else "ok".
fn print_human(data: &Value) {
    if let Some(id) = data.get("workspace_id").and_then(|v| v.as_str()) {
        println!("{id}");
    } else if let Some(id) = data.get("surface_id").and_then(|v| v.as_str()) {
        println!("{id}");
    } else if let Some(id) = data.get("group_id").and_then(|v| v.as_str()) {
        println!("{id}");
    } else if let Some(ids) = data.get("surface_ids").and_then(|v| v.as_array()) {
        for id in ids {
            if let Some(s) = id.as_str() { println!("{s}"); }
        }
    } else {
        println!("ok");
    }
}

/// Compact table for `status`.
fn print_status(data: &Value) {
    let empty = vec![];
    let workspaces = data.get("workspaces").and_then(|v| v.as_array()).unwrap_or(&empty);
    if workspaces.is_empty() {
        println!("(no workspaces)");
        return;
    }
    for w in workspaces {
        let name = w.get("name").and_then(|v| v.as_str()).unwrap_or("?");
        let id = w.get("id").and_then(|v| v.as_str()).unwrap_or("?");
        let unread = w.get("unread").and_then(|v| v.as_bool()).unwrap_or(false);
        println!("{} ({}){}", name, id, if unread { " *" } else { "" });
        if let Some(surfaces) = w.get("surfaces").and_then(|v| v.as_object()) {
            for (sid, sv) in surfaces {
                let running = sv.get("running").and_then(|v| v.as_bool()).unwrap_or(false);
                let state = sv.get("state").and_then(|v| v.as_str()).unwrap_or("idle");
                let agent = sv.get("spec").and_then(|s| s.get("agent_label")).and_then(|v| v.as_str()).unwrap_or("shell");
                let life = if running { "running" } else { "stopped" };
                println!("  {sid}  {agent:<8} {life:<8} {state}");
            }
        }
    }
}
```

- [ ] **Step 2: Build + manual smoke (optional)**

Run: `cargo build -p spacesh-cli`
Expected: PASS. Manual: `cargo run -p spacesh-cli -- completions zsh | head` prints a completion script (no daemon needed).

- [ ] **Step 3: Commit**

```bash
git add crates/spacesh-cli/src/output.rs
git commit -m "feat(cli): command dispatch, human/--json rendering, status table, completions"
```

---

### Task 5: CLI integration tests against a mock daemon

**Files:**
- Create: `crates/spacesh-cli/tests/integration.rs`

Because `spacesh-cli` exposes a `spacesh_cli` lib (Task 3), these tests call the REAL `client::request` / `client::notify` against a tiny in-test UDS server that speaks the framing protocol, isolated via a unique `SPACESH_SOCK` per test (so they run safely in parallel — no serial guard needed). Cross-crate spawning of the real `spaceshd` binary is intentionally avoided; the daemon's own integration tests + the manual check cover end-to-end.

- [ ] **Step 1: Write the integration tests**

Create `crates/spacesh-cli/tests/integration.rs`:
```rust
use std::path::PathBuf;
use spacesh_proto::codec::{read_frame, write_frame};
use spacesh_proto::{Cmd, Envelope, SurfaceId};
use spacesh_proto::status::SurfaceState;
use spacesh_cli::client;
use tokio::net::UnixListener;

// These tests mutate the process-global SPACESH_SOCK env var, so they must not
// run concurrently. Serialize them on a process-wide lock (poison-tolerant).
static SERIAL: std::sync::Mutex<()> = std::sync::Mutex::new(());
fn serial() -> std::sync::MutexGuard<'static, ()> {
    SERIAL.lock().unwrap_or_else(|e| e.into_inner())
}

fn tmp_sock(name: &str) -> PathBuf {
    let mut p = std::env::temp_dir();
    let n = std::time::SystemTime::now().duration_since(std::time::UNIX_EPOCH).unwrap().as_nanos();
    p.push(format!("spacesh-cli-{name}-{n}.sock"));
    p
}

/// One-shot mock daemon: accept one connection, read one request, send `reply`.
fn mock_daemon(sock: PathBuf, reply: Envelope) {
    let listener = UnixListener::bind(&sock).unwrap();
    tokio::spawn(async move {
        if let Ok((mut stream, _)) = listener.accept().await {
            if let Ok(Some(_req)) = read_frame(&mut stream).await {
                let _ = write_frame(&mut stream, &reply).await;
            }
        }
    });
}

#[tokio::test(flavor = "multi_thread", worker_threads = 2)]
async fn request_returns_data_from_daemon() {
    let _g = serial();
    let sock = tmp_sock("req");
    std::env::set_var("SPACESH_SOCK", &sock);
    mock_daemon(sock.clone(), Envelope::Res {
        id: 1, ok: true, data: serde_json::json!({ "workspace_id": "w_1" }), error: None,
    });
    tokio::time::sleep(std::time::Duration::from_millis(50)).await; // let the listener bind

    let data = client::request(Cmd::Open { path: "/tmp".into() }).await.unwrap();
    std::env::remove_var("SPACESH_SOCK");
    let _ = std::fs::remove_file(&sock);
    assert_eq!(data["workspace_id"], "w_1");
}

#[tokio::test(flavor = "multi_thread", worker_threads = 2)]
async fn request_surfaces_daemon_error() {
    let _g = serial();
    let sock = tmp_sock("err");
    std::env::set_var("SPACESH_SOCK", &sock);
    mock_daemon(sock.clone(), Envelope::Res {
        id: 1, ok: false, data: serde_json::Value::Null,
        error: Some(spacesh_proto::ErrorBody { code: "NOT_FOUND".into(), msg: "surface".into() }),
    });
    tokio::time::sleep(std::time::Duration::from_millis(50)).await;

    let res = client::request(Cmd::Close { surface_id: SurfaceId("s_x".into()) }).await;
    std::env::remove_var("SPACESH_SOCK");
    let _ = std::fs::remove_file(&sock);
    assert!(res.is_err());
    assert!(res.unwrap_err().to_string().contains("NOT_FOUND"));
}

#[tokio::test(flavor = "multi_thread", worker_threads = 2)]
async fn notify_with_no_daemon_is_silent_success() {
    let _g = serial();
    let sock = tmp_sock("nodaemon"); // never bound
    std::env::set_var("SPACESH_SOCK", &sock);
    let r = client::notify(Cmd::SetState { surface_id: SurfaceId("s_1".into()), state: SurfaceState::Done }).await;
    std::env::remove_var("SPACESH_SOCK");
    assert!(r.is_ok(), "notify must be a silent success when no daemon is listening");
}
```

Note: `mapping`/`output` are unit-tested in Task 3 (mapping) and Task 4; `client` is now exercised for real here.

- [ ] **Step 2: Run tests (3×) for non-flakiness**

Run: `cargo test --workspace > /tmp/m4b.log 2>&1; echo EXIT=$?` — three times, all 0.
Expected: all crates green including the CLI tests.

- [ ] **Step 3: Manual end-to-end (real daemon + CLI)**

Run:
```bash
cargo build
SOCK=$(mktemp -u /tmp/spacesh-e2e-XXXX.sock)
SPACESH_SOCK=$SOCK ./target/debug/spaceshd &
sleep 1
SPACESH_SOCK=$SOCK ./target/debug/spacesh open /tmp
SPACESH_SOCK=$SOCK ./target/debug/spacesh status
# grab a workspace id from status, create a surface, set state, observe in status:
# SPACESH_SOCK=$SOCK ./target/debug/spacesh new-surface <ws>
# SPACESH_SOCK=$SOCK ./target/debug/spacesh notify --surface <sid> --state work
# SPACESH_SOCK=$SOCK ./target/debug/spacesh status   # shows state=work
SPACESH_SOCK=$SOCK ./target/debug/spacesh shutdown
rm -f $SOCK
```
Expected: open prints a workspace id, status lists it, notify flips the surface state shown by a subsequent status.

- [ ] **Step 4: Commit**

```bash
git add crates/spacesh-cli/tests/integration.rs
git commit -m "test(cli): wire-level integration tests via SPACESH_SOCK mock daemon"
```

---

## Definition of Done

- [ ] `cargo test --workspace` — green & non-flaky across 3 consecutive runs.
- [ ] `cargo build` clean (CLI binary `spacesh` builds).
- [ ] **Manual** (Task 5 Step 3): real `spaceshd` + `spacesh` over `SPACESH_SOCK` — `open`/`status`/`new-surface`/`notify` work; `notify` with no daemon exits 0; `completions zsh` prints a script.

## Notes for the implementer

- **Tasks 1–2 compile together.** Adding `SurfaceView.state` and `Cmd::SetState` breaks the daemon until Task 2 updates `to_view` and the `match`. Verify proto alone after Task 1 (`cargo test -p spacesh-proto`); run the workspace suite after Task 2.
- **`Edge`/`SplitDir`/`PresetSlot`/`GroupId` live in `spacesh_proto::message` / `::ids`** (added in M2) — import paths in `mapping.rs` are exact; if a re-export is missing, use the full module path.
- **Status is ephemeral:** never add `state` to `PersistState`/`Workspace`. It lives only in the registry's in-memory `states` map and is dropped on `exit`.
- **notify is best-effort:** no lazy-start, swallow connect errors, always exit 0. Do not "improve" it to surface errors — a failing hook must not break the agent.
- **Out of slice:** status detection sources (Claude Code hook adapter, OSC 133, fallback patterns) and the status UI (rings/badges/Event Center, native notifications) are **M3**, built on this primitive and `spacesh notify`.
```