cli: add felis daemon stop #153

Merged

natsukium merged 4 commits from feat/daemon-stop-25 into main 2026-09-06 03:39:32 +09:00

Conversation 0 Commits 4 Files changed 28 +1593 -94

natsukium commented 2026-09-06 03:22:38 +09:00

Owner

Copy link

Fixes #25.

Adds a portable way to stop a daemon and drain it, replacing the pkill
advice that only ever worked on Unix.

• protocol: a typed Ops::Stop / Ops::StopReply pair with a closed
  StopMode (if-empty, when-empty, force) and StopOutcome, a
  draining flag on Ops::StatusReply, and an AttachFailure::DaemonDraining
  so a client learns why a drained daemon refuses it.
• daemon: Ops::Stop flips the pool into draining, the accept loop stops
  admitting new sessions, and the shutdown fires only after the reply is
  written; the socket is unlinked on the way out.
• cli: felis daemon stop with the mode flags and machine output, plus the
  minor-version gate that refuses the verb against an older daemon.

Doc cascade: docs/reference/cli.md, docs/reference/ipc.md,
docs/reference/spec.md, docs/reference/control-surfaces.md,
docs/explanation/architecture/{control-surfaces,overview,session-lifecycle}.md,
docs/how-to/update-felis.md (the pkill step is now the stop verb),
CHANGELOG.md, and the product-shipped skills/felis/SKILL.md.

Verified: just check green (fmt, clippy, nextest, deny, proto-compat); reviewed
by pi luna + pi sol; docs proofread by Gemini gemini-3.8-flash-high

Follow-ups

• #152 test: add fuzz seeds for the Stop/StopReply IPC messages

Deferred

• A test that stops a remote daemon through the SSH relay (--host) — the
  relay proxies bytes to the real daemon socket, so the stop path is identical
  to the local one; the risk the plan flagged (the relay outliving the reply)
  is covered by the reply being written before the shutdown fires, and no relay
  integration harness exists to hang the test on.
• Clearing the agent link (AgentLink) on the way out, beside the socket
  unlink — a stale link costs the next daemon nothing (clear_stale runs after
  its bind), which is the same argument the existing code makes; a second
  cleanup path is unrelated to the acceptance criteria.
• Windows-gated tests for the stop path — the whole serve-test harness is
  #[cfg(unix)] (it needs POSIX shells and peer credentials); the accept loop's
  watch arm and the shutdown are platform-independent, and only the
  remove_file is cfg(unix).
• Old-daemon minor-gate coverage for daemon_stop — the version gate mirrors
  daemon_status's existing pattern and is implemented correctly; this asks for
  extra coverage of an already-correct compatibility check, not a fix.

Fixes #25. Adds a portable way to stop a daemon and drain it, replacing the `pkill` advice that only ever worked on Unix. - **protocol**: a typed `Ops::Stop` / `Ops::StopReply` pair with a closed `StopMode` (`if-empty`, `when-empty`, `force`) and `StopOutcome`, a `draining` flag on `Ops::StatusReply`, and an `AttachFailure::DaemonDraining` so a client learns why a drained daemon refuses it. - **daemon**: `Ops::Stop` flips the pool into draining, the accept loop stops admitting new sessions, and the shutdown fires only after the reply is written; the socket is unlinked on the way out. - **cli**: `felis daemon stop` with the mode flags and machine output, plus the minor-version gate that refuses the verb against an older daemon. Doc cascade: `docs/reference/cli.md`, `docs/reference/ipc.md`, `docs/reference/spec.md`, `docs/reference/control-surfaces.md`, `docs/explanation/architecture/{control-surfaces,overview,session-lifecycle}.md`, `docs/how-to/update-felis.md` (the `pkill` step is now the stop verb), `CHANGELOG.md`, and the product-shipped `skills/felis/SKILL.md`. Verified: just check green (fmt, clippy, nextest, deny, proto-compat); reviewed by pi luna + pi sol; docs proofread by Gemini gemini-3.8-flash-high ## Follow-ups - #152 test: add fuzz seeds for the Stop/StopReply IPC messages ## Deferred - A test that stops a remote daemon through the SSH relay (`--host`) — the relay proxies bytes to the real daemon socket, so the stop path is identical to the local one; the risk the plan flagged (the relay outliving the reply) is covered by the reply being written before the shutdown fires, and no relay integration harness exists to hang the test on. - Clearing the agent link (`AgentLink`) on the way out, beside the socket unlink — a stale link costs the next daemon nothing (`clear_stale` runs after its bind), which is the same argument the existing code makes; a second cleanup path is unrelated to the acceptance criteria. - Windows-gated tests for the stop path — the whole serve-test harness is `#[cfg(unix)]` (it needs POSIX shells and peer credentials); the accept loop's watch arm and the shutdown are platform-independent, and only the `remove_file` is `cfg(unix)`. - Old-daemon minor-gate coverage for `daemon_stop` — the version gate mirrors `daemon_status`'s existing pattern and is implemented correctly; this asks for extra coverage of an already-correct compatibility check, not a fix.

natsukium added 4 commits 2026-09-06 03:22:38 +09:00

protocol: add a typed daemon stop and draining state ... 4c33370dd1

The update procedure relied on `pkill felis-daemon`: unavailable on
Windows, unable to refuse, and racing whoever creates a session between
the operator's check and the signal. A stop that can be refused and can
report why has to be a message, so minor 10 adds the Ops verb, the
status field that makes the state observable, and the refusal a create
meets while a daemon drains.

`StopMode` and `StopOutcome` are closed unions rather than flag pairs:
"destroy everything" and "wait for everything" are opposite postures, so
no request or reply can name two at once.

The pair is admitted in the setup phase alone, unlike every other Ops
arm. The reply is the last frame its connection writes, and only the
setup phase writes a reply inline; an attached connection queues through
an outbox that an exiting process would not drain.

Refs #25

daemon: stop and drain on Ops::Stop ... 8a236f1e60

The emptiness decision and the refusal of new creates have to be one
critical section, or a create that reserves after a stop was answered
outlives the daemon that answered it. The drain flag therefore lives
inside `try_reserve`, beside the count it decides with, and a
reservation that has not resolved holds a drain open: a create between
its slot and its registration is a session that does not exist yet.

The accept loop selects on a watch the verb fires, so the reply is
written before the listener drops, and the socket path is unlinked on
the way out, an exit path the process never had.

A forced stop waits for each session task's command receiver to close
rather than for the pool count alone: the count falls when the handles
are taken, while the child is reaped by the task that owns it.

A session also leaves the pool before its child is hung up, and on the
panic path that teardown runs from a task outliving the session's own,
so the pool counts what it is still reaping: a stop that read the
admitted count alone could fire the shutdown mid-hangup and let the
process exit over a child it still owns.

Refs #25

cli: add felis daemon stop ... 80c53c274c

Stopping the daemon ends every session it holds, so the bare verb is the
non-destructive one: it refuses while anything is admitted and reports
the count a caller decides `--force` against. The count rides in the
error object rather than only in the message, so a script does not have
to parse prose to find it.

The mode is reported beside the outcome in both framings: "stopping"
alone cannot tell a stop that destroyed sessions from one that found
none, and that difference is the whole risk of the verb.

`daemon status` gains the draining line so the state between a
`--when-empty` and the exit is observable, printed on every status
rather than only a draining one: a reader who must notice an absent
line has been given a trap.

Refs #25

docs: replace the pkill update step with the stop verb ... 9948c38784

The update guide taught a stop that does not exist on Windows and that
races session creation, and said felis had no quiesce mode; the drain is
now the documented step, so the guide teaches the operation the daemon
actually supports.

The explanation records why the stop is a verb rather than a signal, why
its bare form refuses, and why the drain flag sits inside the admission
lock. The idle-daemon revisit narrows accordingly: the exit half exists,
and what is still missing is a trigger nobody asked for.

Refs #25

natsukium merged commit 9948c38784 into main 2026-09-06 03:39:32 +09:00

natsukium deleted branch feat/daemon-stop-25 2026-09-06 03:39:32 +09:00

Sign in to join this conversation.

Reviewers

No reviewers

Labels

Clear labels   

priority/P0

Must be resolved before the v0.1.0 tag

  

priority/P1

Must be settled before the first public contract freezes

  

priority/P2

Explicitly deferred until after v0.1.0

  

release/v0.1.0

Work tracked for the first tagged release

  

status/blocked

Cannot start now: waits on an upstream release, another issue, or a recorded revisit trigger

  

status/planned

Triaged with a source-grounded plan and a passed pi review; ready to implement

  

type/bug

Shipped behavior that contradicts the docs or the code's own intent; needs a product code change

  

type/design

An open scope or trade-off question; needs a recorded decision in the owning explanation doc before code

  

type/test-gap

Documented or reviewed behavior that no test pins; usually split from a review finding, needs no product code change

  

type/tracker

Parent issue that tracks child work

No labels

priority/P0

priority/P1

priority/P2

release/v0.1.0

status/blocked

status/planned

type/bug

type/design

type/test-gap

type/tracker

Milestone

Clear milestone

No items

No milestone

Projects

Clear projects

No items

No project

Assignees

Clear assignees

No assignees

1 participant

Notifications

Subscribe

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference

natsukium/felis!153

No description provided.