feat(vault): M5 slice 5 — CLI agent auto-spawn + headless feature gate

Close out M5 with its two non-TUI items.

Auto-spawn (PRD §7.3): any `vault` verb now starts `vault-agent` itself
when the socket is dead (missing file or stale connection-refused
socket; other errors, e.g. permissions, still surface directly). New
vault-cli/src/spawn.rs locates the agent via $VAULT_AGENT_BIN, then a
vault-agent sibling of the `vault` binary, then $PATH; starts it in its
own process group (--socket passed explicitly, stdin/stdout null,
stderr appended to agent.log beside the socket in the 0700 runtime
dir); and poll-connects until the agent accepts (2 s deadline, 25 ms
interval), reusing the first accepted stream. A new global
--no-auto-spawn flag opts out per call, and stop-agent never spawns —
stopping a dead agent must not start one. A small
Endpoint { socket, auto_spawn } context replaces the bare &Path through
the command handlers.

Headless gate (PRD G6): the `vault` bin now carries
required-features = ["cli"], making the documented server install
literal: cargo install --path crates/vault-cli --no-default-features
--features cli (pair with vault-agent --no-default-features to drop the
clipboard's X11/Wayland tree). A new CI `headless` job builds both
combos so the gate can't rot.

Docs trued up: README Status (was still "M0 scaffolding only") and the
headless install section; vault-agent's "run via nohup" module doc;
CLAUDE.md's agent/cli/tui bullets and milestone state.

Known limitation (tracked in CHANGELOG): two racing CLI invocations can
each spawn an agent; the second bind steals the socket path and the
first agent idles until its lock. Benign at single-user posture.

Tests: binary-resolution precedence (override > sibling > $PATH, empty
override ignored), dead-socket error classification, and poll-loop
behavior (picks up a late listener, gives up at the deadline). Verified
live end-to-end: spawn-on-first-verb, silent reuse, agent.log placement,
--no-auto-spawn, and stop-agent-never-spawns.

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

Author: UnbreakableMJ

.github/workflows/ci.yml

@@ -47,6 +47,19 @@ jobs:
       - run: cargo build --workspace --all-targets
       - run: cargo test --workspace --all-targets
 
+  headless:
+    name: headless build (no TUI / clipboard deps)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+      - uses: dtolnay/rust-toolchain@stable
+      - uses: Swatinem/rust-cache@v2
+      # PRD G6: the server install path must keep building — the CLI behind
+      # its `cli` feature gate, and the agent without the clipboard's
+      # X11/Wayland dependency tree.
+      - run: cargo build -p vault-cli --no-default-features --features cli
+      - run: cargo build -p vault-agent --no-default-features
+
   version-gate:
     name: vault --version emits §13.2 attribution
     runs-on: ubuntu-latest

CHANGELOG.md

@@ -10,6 +10,35 @@ range may break in any release.
 
 ### Added
 
+- **M5 (slice 5) — CLI agent auto-spawn + headless feature gate.** The two
+  non-TUI M5 items, closing out the milestone.
+  - **Auto-spawn (PRD §7.3).** Any `vault` verb now starts `vault-agent`
+    itself when the socket is dead (missing file or stale, connection-refused
+    socket — other errors, e.g. permissions, still surface directly). The CLI
+    locates the agent via `$VAULT_AGENT_BIN`, then a `vault-agent` sibling of
+    the `vault` binary, then `$PATH`; starts it in its own process group
+    (`--socket` passed explicitly, stdin/stdout null, stderr appended to
+    `agent.log` beside the socket in the 0700 runtime dir); and poll-connects
+    until the agent accepts (2 s deadline, 25 ms interval), reusing the first
+    accepted stream. Opt out per-call with the global `--no-auto-spawn`;
+    `stop-agent` never spawns (stopping a dead agent shouldn't start one).
+    New `vault-cli/src/spawn.rs` module; the old "start the daemon with
+    `vault-agent &`" hint remains only on the no-spawn paths.
+  - **Headless gate (PRD G6).** The `vault` bin now carries
+    `required-features = ["cli"]`, making the documented server install
+    literal: `cargo install --path crates/vault-cli --no-default-features
+    --features cli` (pair with `cargo install --path crates/vault-agent
+    --no-default-features` to drop the clipboard's X11/Wayland tree). A new
+    CI `headless` job builds both combos so the gate can't rot. README's
+    Status and headless sections updated to match reality.
+  - Known limitation: two racing CLI invocations can each spawn an agent; the
+    second bind steals the socket path (the listener removes a pre-existing
+    socket file) and the first agent is orphaned until its idle lock. Benign
+    for the single-user posture; a flock around spawn is a possible follow-up.
+  - Tests: binary-resolution precedence (override > sibling > `$PATH`,
+    empty override ignored), dead-socket error classification, and poll-loop
+    behavior (picks up a late listener; gives up at the deadline).
+
 - **M5 (slice 4) — TUI mutations: `a` add, `e` edit, `d` delete (confirm).**
   PRD §7.2's Mutation row goes live, completing the daily-driver loop (browse
   → search → reveal/copy → mutate) without falling back to the CLI. Pure TUI

Cargo.lock

@@ -15,9 +15,14 @@ The full product requirements live in [`PRD.md`](./PRD.md).
 
 ## Status
 
-Pre-alpha — M0 scaffolding only. The `vault` binary builds and emits the
-Standard §13.2 attribution block via `--version`; nothing else is wired up
-yet. See [PRD §12](./PRD.md#12-milestones) for the roadmap (M0 → v0.1).
+Pre-alpha, M5. The read and write paths are wired end-to-end against a live
+agent: `status` / `unlock` / `lock` / `sync` / `list` / `get` / `add` /
+`edit` / `remove` / `generate` / `stop-agent` on the CLI (with `--json`
+everywhere), and a three-pane `vault-tui` with search, reveal/copy
+(agent-side clipboard, 30 s auto-clear), a generator overlay, a `:` command
+line, and add/edit/delete. The CLI auto-starts the agent when needed. See
+[PRD §12](./PRD.md#12-milestones) for the roadmap (M0 → v0.1) and
+[`CHANGELOG.md`](./CHANGELOG.md) for per-slice detail.
 
 ## Build
 
@@ -26,12 +31,19 @@ cargo build --release
 ./target/release/vault --version
 ```
 
-Headless install (no TUI dependencies) — once the feature gate lands in M5:
+Headless install (no TUI dependencies; the agent additionally drops the
+clipboard's X11/Wayland tree):
 
 ```sh
 cargo install --path crates/vault-cli --no-default-features --features cli
+cargo install --path crates/vault-agent --no-default-features
 ```
 
+The CLI auto-starts `vault-agent` when the socket is dead: it looks for a
+sibling of the `vault` binary, then `$PATH` (override with
+`$VAULT_AGENT_BIN`; opt out per-call with `--no-auto-spawn`). A spawned
+agent logs to `agent.log` beside the socket.
+
 ## Repository layout
 
 ```

README.md

@@ -4,9 +4,10 @@
 //!
 //! Run with no arguments to bind the default socket
 //! (`$XDG_RUNTIME_DIR/vault/agent.sock`). Override with `--socket PATH` or
-//! `VAULT_AGENT_SOCK`. The agent does NOT yet daemonise itself — start it
-//! with `nohup vault-agent &` or run it under a systemd user unit. M5 adds
-//! auto-spawn from the CLI.
+//! `VAULT_AGENT_SOCK`. The agent does not daemonise itself: the normal start
+//! path is the CLI's auto-spawn — any `vault` verb starts it detached when
+//! the socket is dead, logging to `agent.log` beside the socket — and a
+//! systemd user unit works too.
 
 #![forbid(unsafe_code)]
 

crates/vault-agent/src/main.rs

@@ -16,6 +16,10 @@ readme.workspace = true
 [[bin]]
 name = "vault"
 path = "src/main.rs"
+# The headless gate (PRD G6): `cargo install --path crates/vault-cli
+# --no-default-features --features cli` is the supported server install;
+# with no features at all there is nothing to build.
+required-features = ["cli"]
 
 [lints]
 workspace = true
@@ -24,6 +28,9 @@ workspace = true
 default = ["cli"]
 cli = []
 
+[dev-dependencies]
+tempfile = { workspace = true }
+
 [dependencies]
 anyhow = { workspace = true }
 clap = { workspace = true }