daemon: hand an auto-spawned daemon to the systemd user manager #271

Merged

natsukium merged 6 commits from issue-261 into main 2026-09-13 11:13:53 +09:00

Conversation 0 Commits 6 Files changed 22 +1522 -60

natsukium commented 2026-09-13 01:53:38 +09:00

Owner

Copy link

Closes #261.

Implements the plan reviewed in #261 (comment) (rev 23, "Implementation scope" only).

What changes

• felis-daemon: sends READY=1 on $NOTIFY_SOCKET right after the socket is bound; NOTIFY_SOCKET joins ENV_DENYLIST so PTY children never inherit it; the relay's fork scrubs it too.
• felis-transport: a relative --socket / $FELIS_SOCKET is anchored to the current directory at resolution, so the path handed to the manager is absolute. Adds RetryPolicy::MANAGED_BOOT (15 s).
• felis-client-core: on Linux, when the launcher's own cgroup is under user@<uid>.service/, connect_or_spawn_daemon first asks the systemd user manager to run the sibling felis-daemon as a transient notify service (felis-daemon-<fnv1a64(socket)>, app.slice, OOMPolicy=continue, RefuseManualStop=yes, TimeoutStartSec=15s, --expand-environment=no on systemd ≥ 254). Helper calls are bounded (3 s probes, 20 s start) and kill_on_drop. A non-zero exit spends exactly one systemctl --user show -p ActiveState query: active/activating means a concurrent launcher won, so the loser waits for the socket instead of forking. Everything else falls back to today's detached fork (with NOTIFY_SOCKET removed) and one WARN line in client.log. Non-Linux, non-systemd, and session-scope launchers (SSH, tty) are unchanged.
• felis-cli: opt-in integration test (FELIS_SYSTEMD_TESTS=1) against a live user manager: hand-off placement read back from the unit, sessions spawn --format json output stays clean, concurrent launchers converge on one daemon; RAII cleanup of the transient unit.
• docs: cli.md Auto-spawning / --socket / Log files, decision record in session-lifecycle.md (rationale, rejected alternatives, deferred list as Revisit-if), non-goals.md platform shims, spec.md REQ-009a, testing.md, security-model.md, skills/felis/SKILL.md, CHANGELOG.

Deferred per the plan (recorded as Revisit-if triggers): relay hand-off, daemon status supervisor field, doctor detail, linger, cgroup v1.

Verification

• just check gates green on this host (fmt, clippy -D warnings, nextest 3523 passed / 16 skipped, deny, prose-check on the range, skill-check, proto-compat).
• FELIS_SYSTEMD_TESTS=1 cargo nextest run -p felis-cli --test cli_systemd_handoff --test-threads=1: 2 passed on systemd 261 (launcher cgroup …/[email protected]/session.slice/niri.service); no transient units left behind.
• Stub-based Linux unit tests cover the cgroup predicate, unit naming (published FNV-1a vector), argv / $ doubling / version gate, every ActiveState branch incl. the single-query invariant, the bounded-helper kill, and stdio isolation (test binary re-executed as a subprocess with noisy stubs).
• Reviewed by pi/sol: round 1 BLOCKED (unbounded helper calls) → fixed; round 2 PASS; the four round-2 non-blocking findings are also addressed.

Closes #261. Implements the plan reviewed in https://git.natsukium.com/natsukium/felis/issues/261#issuecomment-2622 (rev 23, "Implementation scope" only). ## What changes - **felis-daemon**: sends `READY=1` on `$NOTIFY_SOCKET` right after the socket is bound; `NOTIFY_SOCKET` joins `ENV_DENYLIST` so PTY children never inherit it; the relay's fork scrubs it too. - **felis-transport**: a relative `--socket` / `$FELIS_SOCKET` is anchored to the current directory at resolution, so the path handed to the manager is absolute. Adds `RetryPolicy::MANAGED_BOOT` (15 s). - **felis-client-core**: on Linux, when the launcher's own cgroup is under `user@<uid>.service/`, `connect_or_spawn_daemon` first asks the systemd user manager to run the sibling `felis-daemon` as a transient notify service (`felis-daemon-<fnv1a64(socket)>`, `app.slice`, `OOMPolicy=continue`, `RefuseManualStop=yes`, `TimeoutStartSec=15s`, `--expand-environment=no` on systemd ≥ 254). Helper calls are bounded (3 s probes, 20 s start) and `kill_on_drop`. A non-zero exit spends exactly one `systemctl --user show -p ActiveState` query: `active`/`activating` means a concurrent launcher won, so the loser waits for the socket instead of forking. Everything else falls back to today's detached fork (with `NOTIFY_SOCKET` removed) and one `WARN` line in `client.log`. Non-Linux, non-systemd, and session-scope launchers (SSH, tty) are unchanged. - **felis-cli**: opt-in integration test (`FELIS_SYSTEMD_TESTS=1`) against a live user manager: hand-off placement read back from the unit, `sessions spawn --format json` output stays clean, concurrent launchers converge on one daemon; RAII cleanup of the transient unit. - **docs**: `cli.md` Auto-spawning / `--socket` / Log files, decision record in `session-lifecycle.md` (rationale, rejected alternatives, deferred list as Revisit-if), `non-goals.md` platform shims, `spec.md` REQ-009a, `testing.md`, `security-model.md`, `skills/felis/SKILL.md`, CHANGELOG. Deferred per the plan (recorded as Revisit-if triggers): relay hand-off, `daemon status` supervisor field, doctor detail, linger, cgroup v1. ## Verification - `just check` gates green on this host (fmt, clippy `-D warnings`, nextest 3523 passed / 16 skipped, deny, prose-check on the range, skill-check, proto-compat). - `FELIS_SYSTEMD_TESTS=1 cargo nextest run -p felis-cli --test cli_systemd_handoff --test-threads=1`: 2 passed on systemd 261 (launcher cgroup `…/[email protected]/session.slice/niri.service`); no transient units left behind. - Stub-based Linux unit tests cover the cgroup predicate, unit naming (published FNV-1a vector), argv / `$` doubling / version gate, every `ActiveState` branch incl. the single-query invariant, the bounded-helper kill, and stdio isolation (test binary re-executed as a subprocess with noisy stubs). - Reviewed by pi/sol: round 1 BLOCKED (unbounded helper calls) → fixed; round 2 PASS; the four round-2 non-blocking findings are also addressed.

natsukium added 25 commits 2026-09-13 01:53:38 +09:00

scripts: exclude generated prost types from prose-check and add --all support ... 92cff8be3a

scripts/prose_check.py previously classified crates/felis-protocol/src/generated
as Rust, which failed comment-length checks on prost-generated code that is
wiped and regenerated by buf generate. It also failed to recognize .proto
files located under crates/felis-protocol/proto/.

Update classify() to ignore src/generated and recognize all .proto files,
default --all to git ls-files when no files are passed, and add a
prose-check-all recipe to justfile.

docs: eliminate em-dashes in session-lifecycle and AGENTS.md ... 11f0fd0f23

docs/explanation/architecture/session-lifecycle.md and AGENTS.md
carried em-dashes that violate the repository prose norms. Replace them
with colons, semicolons, or parentheses.

skills: eliminate em-dashes and history phrases across skills ... 433cf0d1fd

Markdown files under .agents/skills/ carried em-dashes and history
narration that violated repository prose norms. Replace them with
colons, semicolons, and parentheses, and rephrase history references
in the present tense.

protocol: eliminate em-dashes and trim comment lengths in felis.proto ... 62c8a4bf7c

crates/felis-protocol/proto/felis.proto carried em-dashes and comment
blocks longer than 5 lines that violated prose norms. Replace em-dashes
with colons, semicolons, and parentheses, trim comment blocks to <= 5
lines keeping invariants and why-nots, and regenerate prost wire types
with buf generate.

felis-shaping: trim comment lengths and eliminate em-dashes ... 2876bb2337

Prune comments longer than 5 lines to concise invariants and why-nots,
and replace em-dashes with colons or parentheses per repository prose
norms.

felis-vt: trim comment lengths and eliminate em-dashes ... e811d506d9

Prune comments longer than 5 lines to concise invariants and why-nots,
and replace em-dashes with colons or parentheses per repository prose
norms.

felis-transport: trim comment lengths and eliminate em-dashes ... 7daaeace40

Prune comments longer than 5 lines to concise invariants and why-nots,
and replace em-dashes with colons or parentheses per repository prose
norms.

felis-render-wgpu: trim comment lengths and eliminate em-dashes ... 0f84115adc

Prune comments longer than 5 lines to concise invariants and why-nots,
and replace em-dashes with colons or parentheses per repository prose
norms.

felis-protocol: trim comment lengths and eliminate em-dashes ... df14f1cba8

Prune comments longer than 5 lines to concise invariants and why-nots,
condense module-level doc essays, and replace em-dashes with colons or
parentheses per repository prose norms.

felis-pty: trim comment lengths and eliminate em-dashes ... 880407d45f

Prune comments longer than 5 lines to concise invariants and why-nots,
and replace em-dashes with colons or parentheses per repository prose
norms.

felis-client: trim comment lengths and eliminate em-dashes ... c7a4b625ec

Prune comments longer than 5 lines to concise invariants and why-nots,
and replace em-dashes with colons or parentheses per repository prose
norms.

felis-client-core: trim comment lengths and eliminate em-dashes ... 27e04a059d

Prune comments longer than 5 lines to concise invariants and why-nots,
and replace em-dashes with colons or parentheses per repository prose
norms.

felis-cli: trim comment lengths and eliminate em-dashes ... 645ad52dbb

Prune comments longer than 5 lines to concise invariants and why-nots,
and replace em-dashes with colons, semicolons, or parentheses per
repository prose norms.

felis-client-core: separate doc comment from implementation comment in map.rs ... 579af3fda6

Separate the doc comment from the implementation comment with a blank
line to avoid exceeding comment block length limits.

felis-grid: trim comment lengths and eliminate em-dashes ... b5ef9825f3

Prune comments longer than 5 lines to concise invariants and why-nots,
and replace em-dashes with colons, semicolons, or parentheses per
repository prose norms.

felis-daemon: trim comment lengths and eliminate em-dashes ... 7621d1c4cf

Prune comments longer than 5 lines to concise invariants and why-nots,
and replace em-dashes with colons, semicolons, or parentheses per
repository prose norms.

treefmt: format markdown and rust sources ... d81855c3fc

Run treefmt across modified files to align wrapping and trailing
whitespace with repository formatter settings.

felis-pty: drop unfulfilled doc_lazy_continuation lint expectation ... 776cb26ae5

Shortening the module doc comment removed the list-like syntax that
originally triggered clippy::doc_lazy_continuation, leaving the lint
expectation unfulfilled under clippy -D warnings.

felis-client-core: regenerate json schema after doc comment revisions ... 09bcd0e72a

Doc comments on config structs serve as descriptions in the generated
JSON schema; regenerate felis-config.schema.json to match the revised
comments.

felis-cli: update help page snapshots after doc comment revisions ... ce1e891d95

Updating doc comments on CLI flags and subcommands changed clap's
generated --help output; accept the updated help page snapshot.

felis-daemon: answer a systemd user manager's readiness protocol ... f2bb3976f2

An auto-spawned daemon inherits the cgroup of whichever client first
found a cold socket, so a compositor unit's OOMPolicy=stop ends the
whole graphical session when one shell child is OOM-killed. Handing the
daemon to the systemd user manager instead needs the manager to know
when the daemon is up, and Type=notify is the only start type that
reports a bind rather than a fork.

A failed send fails startup: a daemon the manager never hears from is
torn down at the start timeout anyway, and serving a socket in that
window would strand the sessions created into it.

NOTIFY_SOCKET joins the denylist, and the relay's fork clears it, for
the mirror reason: a child holding the endpoint can report its parent's
unit ready, or stopped, in the daemon's place.

felis-transport: anchor a relative socket path at resolution ... 61970e19e5

A `--socket` or FELIS_SOCKET path was carried as typed, which is fine
while the only process that resolves it is the one that typed it. The
systemd hand-off gives the path to the user manager, whose working
directory is the user's home, so a relative path would name a different
socket there than the client dials, and the unit name derived from it
would differ per caller directory.

Lexical, never canonicalized: the daemon stamps the path as
FELIS_SOCKET, and a resolved symlink would hand children a name the
user never typed.

felis-client-core: hand a cold-socket daemon to the systemd user manager ... 96468c3fa3

cgroup membership is inherited at fork and survives reparenting, so the
daemon and every PTY child live for the daemon's lifetime in the cgroup
of whichever client first found a cold socket. Under the systemd user
manager that cgroup belongs to a unit: a compositor's OOMPolicy=stop
turns an OOM kill of one shell child into the end of the graphical
session, and which unit a daemon lands in is decided by a race.

The launcher now asks the manager to run its own felis-daemon binary on
its own socket as a transient service in app.slice with
OOMPolicy=continue. Best effort: a hand-off that fails for any reason
forks exactly as every felis release so far has, leaving one warning
line in the client log, so no new failure mode is introduced on hosts
where systemd-run, the manager, or D-Bus is not what the launcher
assumed. Only the positive case is guaranteed, and Type=notify is what
guarantees it: exit 0 means that binary bound that socket.

A non-zero exit is checked against the unit's ActiveState before
forking. Without it two windows opened together would have the loser
fork a daemon into its own cgroup, which is the placement this change
exists to avoid.

Both stdio streams are captured: systemd-run's progress line on the
stdout of `sessions spawn --format json` would break the one-result
output contract.

Every call to the manager is bounded and its child killed on drop: a
wedged user bus would otherwise hold a cold window open with no
deadline of its own, since TimeoutStartSec bounds only a service the
manager did manage to create. A breached bound is classified as a
failed attempt rather than an absent manager, so it still spends its
one ActiveState query before falling back.

felis-cli: cover the systemd hand-off against a real user manager ... 4712b80352

The hand-off's unit tests reach only its pure parts: whether a launcher
sits under the user manager, the unit name, the argv. What the change
is actually for — the daemon landing in app.slice with
OOMPolicy=continue, two launchers on one cold socket ending on one
daemon, and systemd-run's output staying off a JSON verb's stdout —
needs a live manager, which CI runners do not have. Hence opt-in
through FELIS_SYSTEMD_TESTS=1, with a unique socket path per test so
the units never collide with the developer's own daemon.

docs: record how an auto-spawned daemon reaches its cgroup ... cef0d815d5

The auto-spawn contract is unchanged, but where a cold daemon lands now
depends on the launcher's own placement, which every page that claimed
an unconditional fork got wrong. The decision record carries the
rationale, the rejected alternatives (socket activation, a shipped unit
file, refusing to fork past a present manager), and the deferred list as
its revisit triggers.

The `systemctl --user stop` refusal is the change a user is most likely
to meet first, so it appears wherever a stop is documented: the CLI
reference, the update guide, and the shipped skill.

natsukium force-pushed issue-261 from cef0d815d5 to b5316411b4 2026-09-13 02:10:03 +09:00 Compare

natsukium added 1 commit 2026-09-13 10:14:11 +09:00

windows: fix clippy 63de43fa60

natsukium merged commit dc09f8e4e3 into main 2026-09-13 11:13:53 +09:00

natsukium deleted branch issue-261 2026-09-13 11:13:53 +09:00

natsukium referenced this pull request from a commit 2026-09-13 11:13:53 +09:00

daemon: hand an auto-spawned daemon to the systemd user manager (#271)

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!271

No description provided.