cli: record the frozen CLI and bridge surfaces, and close the gaps the audit found #346

Merged

natsukium merged 3 commits from issue-326-a into main 2026-09-22 19:11:07 +09:00

Conversation 0 Commits 3 Files changed 14 +493 -209

natsukium commented 2026-09-22 15:28:12 +09:00

Owner

Copy link

Part of #326: items 3, 4 and 5 of the final interface-freeze audit. Item 6 (the AttachFailure split, plus item 4's
ConnectError golden and exhaustive match) is PR B, which rebases on this branch.

Item 3 — the bridge is an explicitly smaller session-automation surface

The op set is closed to sessions.*, notifications.subscribe and cancel. That is surface policy, not a limit of the
wire, and it is now recorded as such; two things that were defects rather than policy are fixed.

• docs/reference/cli.md "felis bridge": the closed op set, the three CLI-only verb groups (operator verbs, window
  launches, shell plumbing) and how a bridge client reaches them, and the three ops that take less than their CLI verb
  with their reasons — sessions.send's required text and absent keys/wait (additive within v:1, filed as
  #344), notifications.subscribe without once/timeout, and sessions.switch's required from and its
  queued == 0 result.
• docs/explanation/architecture/control-surfaces.md: the rationale and the rejected complete mirror (process-lifecycle
  verbs behind a correlated stream, and a bridge twin for every operator verb).
• skills/felis/SKILL.md: the CLI-only groups in the bridge bullet.
• crates/felis-cli/src/cli_bridge.rs op_send: the comment claiming a chord needs client-side keyboard modes is
  false (the daemon encodes InputMsg::Key against the modes it owns) and is replaced by the policy.
• Fix: op_spawn now fills SpawnArgs.env_base for a local carrier (env_base::fill_for_carrier), as
  cli_sessions.rs does; a bridge-created child inherited the daemon's environment, against REQ-912a. Unit test: a
  local spawn carries a captured base, a relay spawn none.
• Fix: rows/cols parse at the wire's u32 width instead of u16, so a geometry past the REQ-605a bounds is the
  daemon's invalid_request on both surfaces rather than malformed_request on the bridge alone. The stale u16_opt
  comment (a terminal anchor failure OpsMsg::Spawn no longer has) is gone, felis-bridge-v1.schema.json is
  regenerated, the live-bridge test covers a value above u16::MAX, and the schema fixture moves to req-rows-above-u32.

Item 4 — one vocabulary, one error object, two transports: frozen

• docs/reference/cli.md "Machine output": what is frozen for the epoch (the two format words and their class binding,
  the error object shape, the kind spellings with their exit codes, the two transports) and the boundaries — framing
  begins after a successful parse, a clap rejection stays human on stderr at exit 2, bridge shape failures are
  correlated whenever a valid id was recovered. The exit-code table's felis bridge row gains the initial
  at_capacity dial refusal beside its own pipe failure.
• docs/explanation/architecture/control-surfaces.md "Frozen for v:1": why the transports follow from the process
  model, the rejected unification in both directions, and #23 / #29 / #145 cited once.
• Framing audit (code): every ? whose error reached main on a machine-formatted verb now goes through the verb's
  Reporter — resolve_config_source (usage), the dial (daemon_unreachable), build_runtime (internal), the
  verb bodies (internal), and sessions send ID -'s stdin read (input_failed). One verb_reporter now decides
  class and format for the whole invocation, which is also what makes Cli::machine_output() cover Cmd::Version.
  cli_sessions::plan no longer returns Result because nothing in it can escape unframed.
• Integration test (crates/felis-cli/tests/cli_sessions.rs): one JSON error object on stderr, no stdout, exit 2, for
  an unresolvable --config under --format json and for sessions send ID - --format json with an unreadable stdin.

Item 5 — sessions send stays one typed operation

• docs/explanation/architecture/control-surfaces.md: the decision, the wait race that rejects a separate wait verb,
  why a separate key verb has no race (and what keeps --key on send), and the rule that no new flag may depend on
  another — anything else is a new verb.
• docs/reference/cli.md "Verb details": the three constraints stated as the whole grammar, "at least one of TEXT /
  --key / --wait" included.
• crates/felis-cli/src/tests.rs: one parser table over all three constraints both ways (rejected bare send ID,
  --timeout without --wait, --raw without TEXT; accepted key-only, wait-only, --wait --timeout N, TEXT with
  --raw).

CHANGELOG.md carries the two bridge fixes and the framing fix.

Gates

Run on this branch (macOS, worktree under .claude/worktrees/):

• just fmt-check, just lint, just check-portable, just prose-check, just skill-check, just docs-links,
  just deny, just proto-compat, just proto-compat-test, just release-check-test: pass.
• just schema: no diff remains.
• cargo nextest run --workspace --all-features --no-fail-fast: 3407 passed, 5 failures, all pre-existing local
  environment failures from the socket path length in a deep worktree (verified against a clean tree):
  cli_bridge a_lost_daemon_answers_pending_point_requests_with_error_replies,
  cli_bridge a_relative_spawn_cwd_is_resolved_from_the_bridge_process,
  cli_bridge::tests::a_daemon_write_failure_fails_and_clears_the_link (timeout),
  felis-daemon agent::tests::a_racing_teardown_never_strands_a_live_registration,
  felis-daemon serve::tests::a_peer_that_hangs_up_while_parked_gives_its_connection_back.
• just golden was not run (bridge fixtures pick up environment noise on this machine); no golden file needed a change.

Part of #326: items 3, 4 and 5 of the final interface-freeze audit. Item 6 (the `AttachFailure` split, plus item 4's `ConnectError` golden and exhaustive match) is PR B, which rebases on this branch. ## Item 3 — the bridge is an explicitly smaller session-automation surface The op set is closed to `sessions.*`, `notifications.subscribe` and `cancel`. That is surface policy, not a limit of the wire, and it is now recorded as such; two things that were defects rather than policy are fixed. - `docs/reference/cli.md` "`felis bridge`": the closed op set, the three CLI-only verb groups (operator verbs, window launches, shell plumbing) and how a bridge client reaches them, and the three ops that take less than their CLI verb with their reasons — `sessions.send`'s required `text` and absent `keys`/`wait` (additive within `v:1`, filed as #344), `notifications.subscribe` without `once`/`timeout`, and `sessions.switch`'s required `from` and its `queued == 0` result. - `docs/explanation/architecture/control-surfaces.md`: the rationale and the rejected complete mirror (process-lifecycle verbs behind a correlated stream, and a bridge twin for every operator verb). - `skills/felis/SKILL.md`: the CLI-only groups in the bridge bullet. - `crates/felis-cli/src/cli_bridge.rs` `op_send`: the comment claiming a chord needs client-side keyboard modes is false (the daemon encodes `InputMsg::Key` against the modes it owns) and is replaced by the policy. - **Fix**: `op_spawn` now fills `SpawnArgs.env_base` for a local carrier (`env_base::fill_for_carrier`), as `cli_sessions.rs` does; a bridge-created child inherited the daemon's environment, against REQ-912a. Unit test: a local spawn carries a captured base, a relay spawn none. - **Fix**: `rows`/`cols` parse at the wire's `u32` width instead of `u16`, so a geometry past the REQ-605a bounds is the daemon's `invalid_request` on both surfaces rather than `malformed_request` on the bridge alone. The stale `u16_opt` comment (a terminal anchor failure `OpsMsg::Spawn` no longer has) is gone, `felis-bridge-v1.schema.json` is regenerated, the live-bridge test covers a value above `u16::MAX`, and the schema fixture moves to `req-rows-above-u32`. ## Item 4 — one vocabulary, one error object, two transports: frozen - `docs/reference/cli.md` "Machine output": what is frozen for the epoch (the two format words and their class binding, the error object shape, the `kind` spellings with their exit codes, the two transports) and the boundaries — framing begins after a successful parse, a clap rejection stays human on stderr at exit `2`, bridge shape failures are correlated whenever a valid `id` was recovered. The exit-code table's `felis bridge` row gains the initial `at_capacity` dial refusal beside its own pipe failure. - `docs/explanation/architecture/control-surfaces.md` "Frozen for `v:1`": why the transports follow from the process model, the rejected unification in both directions, and #23 / #29 / #145 cited once. - **Framing audit (code)**: every `?` whose error reached `main` on a machine-formatted verb now goes through the verb's `Reporter` — `resolve_config_source` (`usage`), the dial (`daemon_unreachable`), `build_runtime` (`internal`), the verb bodies (`internal`), and `sessions send ID -`'s stdin read (`input_failed`). One `verb_reporter` now decides class and format for the whole invocation, which is also what makes `Cli::machine_output()` cover `Cmd::Version`. `cli_sessions::plan` no longer returns `Result` because nothing in it can escape unframed. - Integration test (`crates/felis-cli/tests/cli_sessions.rs`): one JSON error object on stderr, no stdout, exit `2`, for an unresolvable `--config` under `--format json` and for `sessions send ID - --format json` with an unreadable stdin. ## Item 5 — `sessions send` stays one typed operation - `docs/explanation/architecture/control-surfaces.md`: the decision, the wait race that rejects a separate `wait` verb, why a separate `key` verb has no race (and what keeps `--key` on `send`), and the rule that no new flag may depend on another — anything else is a new verb. - `docs/reference/cli.md` "Verb details": the three constraints stated as the whole grammar, "at least one of TEXT / `--key` / `--wait`" included. - `crates/felis-cli/src/tests.rs`: one parser table over all three constraints both ways (rejected bare `send ID`, `--timeout` without `--wait`, `--raw` without TEXT; accepted key-only, wait-only, `--wait --timeout N`, TEXT with `--raw`). `CHANGELOG.md` carries the two bridge fixes and the framing fix. ## Gates Run on this branch (macOS, worktree under `.claude/worktrees/`): - `just fmt-check`, `just lint`, `just check-portable`, `just prose-check`, `just skill-check`, `just docs-links`, `just deny`, `just proto-compat`, `just proto-compat-test`, `just release-check-test`: pass. - `just schema`: no diff remains. - `cargo nextest run --workspace --all-features --no-fail-fast`: 3407 passed, 5 failures, all pre-existing local environment failures from the socket path length in a deep worktree (verified against a clean tree): `cli_bridge a_lost_daemon_answers_pending_point_requests_with_error_replies`, `cli_bridge a_relative_spawn_cwd_is_resolved_from_the_bridge_process`, `cli_bridge::tests::a_daemon_write_failure_fails_and_clears_the_link` (timeout), `felis-daemon agent::tests::a_racing_teardown_never_strands_a_live_registration`, `felis-daemon serve::tests::a_peer_that_hangs_up_while_parked_gives_its_connection_back`. - `just golden` was not run (bridge fixtures pick up environment noise on this machine); no golden file needed a change.

natsukium added 3 commits 2026-09-22 15:28:12 +09:00

cli: give the bridge's smaller surface a reason and a filled environment ... b9d8b3767c

The bridge exposes session automation and nothing else, and that was
readable only as an absence: the reference listed its ops without saying
the set was closed, and the one comment that explained a gap was wrong
(a chord needs no client-side keyboard modes, since the daemon encodes
`InputMsg::Key` against the modes it owns). Recording the policy is what
makes the two intra-op gaps reviewable instead of looking like arrears,
and `keys` / `wait` on `sessions.send` stay additive params (#344).

Two gaps were not policy. A bridge-created child inherited the daemon's
environment, which on a warm daemon is whatever it was started with,
because `op_spawn` never captured a base the way `sessions spawn` does
(REQ-912a). And the bridge narrowed `rows`/`cols` to `u16` while the CLI
sends the wire's `u32`, so one geometry was `malformed_request` on one
surface and `invalid_request` on the other; the comment justifying the
narrowing described a terminal anchor failure that `OpsMsg::Spawn` has
not had since it became a correlated reusable request. Admission is the
daemon's on both surfaces now, and the published grammar states the
wire's bound.

Part of #326.

Assisted-by: Claude Code

cli: frame every failure a machine verb reaches ... 7340ca747b

A verb that has chosen `json` owes a consumer an object for every
failure, and four escapes broke that on the way to the verb body: the
config-path resolution, the daemon target, the runtime build, and the
stdin read behind `sessions send <id> -` all reached `main` as `anyhow`
prose on stderr with exit `1`, a status the kind table never assigns.
Routing each through the verb's own reporter is what makes the promise
checkable, so one reporter now decides class and format for the whole
invocation instead of each refusal site building its own; `version` was
missing from the machine-output test as well, so a `--format json`
version report carried the console log.

The freeze statement lands with the fix rather than after it: the
epoch's words, error object, kind spellings with their exit codes, and
the two transports are what a consumer is now asked to build on, and
the bridge's exit `1` covers a refused first dial beside its own pipe
failure.

Part of #326.

Assisted-by: Claude Code

cli: freeze the send grammar at three constraints ... a53badd5ff

`sessions send` is one operation — deliver this input, then optionally
await the next prompt mark — and splitting it into `send` / `key` /
`wait` verbs is what the tests now rule out: a standalone `wait` races
the mark of a fast command, and a standalone `key` costs a second
resolution of the same target for an ordering one call already states.
Two of the three constraints had no parser test, so the grammar the
freeze names could have drifted silently; the rule that keeps it small
is that no new flag may depend on another, and anything else is a new
verb.

Part of #326.

Assisted-by: Claude Code

natsukium force-pushed issue-326-a from a53badd5ff to 81f5f613dc 2026-09-22 15:41:09 +09:00 Compare

natsukium force-pushed issue-326-a from 81f5f613dc to cbb992d4ea 2026-09-22 15:46:24 +09:00 Compare

natsukium force-pushed issue-326-a from cbb992d4ea to c037424102 2026-09-22 16:15:43 +09:00 Compare

natsukium force-pushed issue-326-a from c037424102 to 99be731feb 2026-09-22 16:45:37 +09:00 Compare

natsukium force-pushed issue-326-a from 99be731feb to 94b31a1e80 2026-09-22 17:36:42 +09:00 Compare

natsukium added 1 commit 2026-09-22 17:52:35 +09:00

ci: TEMPORARY clear the Windows build dir once and retry (drop before merge) ... 8d249a73f2

Assisted-by: Claude Code

natsukium force-pushed issue-326-a from 8d249a73f2 to 75a9cfc5bb 2026-09-22 18:22:03 +09:00 Compare

natsukium force-pushed issue-326-a from 75a9cfc5bb to 94b31a1e80 2026-09-22 18:48:17 +09:00 Compare

natsukium merged commit d50a6db746 into main 2026-09-22 19:11:07 +09:00

natsukium deleted branch issue-326-a 2026-09-22 19:11:07 +09:00

natsukium referenced this pull request from a commit 2026-09-22 19:11:08 +09:00

cli: record the frozen CLI and bridge surfaces, and close the gaps the audit found (#346)

natsukium referenced this pull request 2026-09-22 19:11:16 +09:00

[v0.1/P1] Final interface simplification audit before public freeze #326

Commenting is not possible because the repository is archived.

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

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

No description provided.