docs: make the auto-spawn contract per verb, not per carrier #161

Merged

natsukium merged 2 commits from fix/remote-autospawn-contract-141 into main 2026-09-06 12:55:21 +09:00

Conversation 0 Commits 2 Files changed 19 +367 -80

natsukium commented 2026-09-06 12:44:44 +09:00

Owner

Copy link

Fixes #141.

The remote auto-spawn contract was stated per carrier, which contradicted
what the code does per verb: only sessions spawn and window launches ask
for a daemon to be started, while daemon status, sessions list/info/…,
notifications subscribe, version, doctor, and bridge refuse to
auto-spawn on a cold socket and report unreachable instead. Each verb now
pins its own policy at the call site (RemoteSpawn threaded through
dial_launch / connect_carrier), so local and SSH landings agree, and the
docs describe the matrix per verb rather than per carrier.

Doc cascade: docs/reference/cli.md ("Auto-spawning"), docs/reference/ipc.md,
docs/explanation/architecture/control-surfaces.md, and 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

• #160 docs: update-felis.md's restart guidance overstates which commands auto-spawn

Deferred

• Making a retarget landing on a cold local socket spawn a daemon (today it fails, unlike the SSH landing). Reason: behavior change, not a doc fix; the plan excludes it from #141 and it is documented as the contract in cli.md and control-surfaces.md.
• just skill-check cannot run in this dev shell (yq: command not found). Reason: environment gap affecting every SKILL.md, unrelated to this issue.

Fixes #141. The remote auto-spawn contract was stated per carrier, which contradicted what the code does per verb: only `sessions spawn` and window launches ask for a daemon to be started, while `daemon status`, `sessions list/info/…`, `notifications subscribe`, `version`, `doctor`, and `bridge` refuse to auto-spawn on a cold socket and report unreachable instead. Each verb now pins its own policy at the call site (`RemoteSpawn` threaded through `dial_launch` / `connect_carrier`), so local and SSH landings agree, and the docs describe the matrix per verb rather than per carrier. Doc cascade: `docs/reference/cli.md` ("Auto-spawning"), `docs/reference/ipc.md`, `docs/explanation/architecture/control-surfaces.md`, and `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 - #160 docs: update-felis.md's restart guidance overstates which commands auto-spawn ## Deferred - Making a retarget landing on a cold local socket spawn a daemon (today it fails, unlike the SSH landing). Reason: behavior change, not a doc fix; the plan excludes it from #141 and it is documented as the contract in cli.md and control-surfaces.md. - `just skill-check` cannot run in this dev shell (yq: command not found). Reason: environment gap affecting every SKILL.md, unrelated to this issue.

natsukium added 2 commits 2026-09-06 12:44:44 +09:00

cli: pin each verb's remote auto-spawn policy ... 3806d33915

Whether a CLI verb may leave a daemon running is a side effect scripts
depend on, and it was decided in four places at once: `Dial`, three
bare `conn::dial` calls, and `dial_and_land`. Nothing tied them
together, so nothing would notice a verb drifting from the contract.

Each dial site now names its `RemoteSpawn` where it dials, and one
test walks the whole verb list over both carriers to assert what the
reference promises: intent decides, the carrier does not. The retarget
landing is the asymmetry the test pins deliberately: it spawns over
SSH and fails on a cold local socket, because `dial_and_land` opens
that socket directly. `--host` and `sessions spawn --help` state the
remote side effect, which a script author could not otherwise predict.

Refs #141

docs: make the auto-spawn contract per verb, not per carrier ... efbef9281e

The scripting contract promised that `--host` never spawns a remote
daemon, while the code, ipc.md and control-surfaces.md all say the
verb's intent decides and the carrier does not. Scripts read the
reference, so the promise was the bug: `--host … sessions spawn` has
always left a daemon on the remote host.

cli.md now carries the per-form matrix both carriers share, including
the two rows a retarget needs (its source dial drives, its landing on
the target host launches), and the twins point at it instead of
restating a partial list.

Refs #141

natsukium merged commit efbef9281e into main 2026-09-06 12:55:21 +09:00

natsukium deleted branch fix/remote-autospawn-contract-141 2026-09-06 12:55:21 +09:00

natsukium referenced this pull request 2026-09-08 01:39:59 +09:00

[v0.1/CLI Args Review] CLI 引数のリリース前設計レビュー #55

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

No description provided.