SouveraineOS/docs/tasks/30-agent-reach-verb-tables.md

TASK 30 — Agent reach: verb tables across the surfaces

Status: half built 2026-07-26 (sessiond). Size: one session per surface. Repo: ~/Projects/souveraine (surfaces/quickshell).

Goal

The agent owns the device 60/40 (doctrine §13) and cannot currently compose a single intent across two surfaces. sessiond can now be enumerated and its refusals branched on; the shell's surfaces cannot. Until they can, "full phone control" is control of the device and not of the things on it.

What exists after 2026-07-26

sessiond has the pattern, working, in src/sessiond/protocol.rs:

• describe returns a verb table — every op, whether it mutates, the refusal codes it can return, and a request line that parses. Knowing an op exists is not enough to call it; a test round-trips every advertised example through the real parser, so a table that lies fails the build.
• Refusals carry a code beside the prose: unsupported_op, invalid_argument, refused_by_state, not_permitted, unavailable. Not-now, never, and wrong-arguments are three different next moves.
• Requests carry an optional intent, stamped onto every trail entry the request produces, so a chain's leaves join back to one decision.

What to build

The same three things on each shell surface, in this order — smallest blast radius first, which is the order the dock manifest work already argued for:

1. dock.* — the manifest exists; give it describe and coded refusals.
2. apps.* — app-inventory-manifest.md (archive/from-substrate) scoped the inventory; it is a read surface, so it is the cheapest to make legible.
3. shell.* — surfaces and state.
4. settings.* — the largest, and the one with a real policy layer: SETTINGS-AUTHORITY.md already specifies risk tiers and propose-vs-set. Its refusals map onto the same five codes; do not invent a sixth.

Quickshell drops var returns, so every result is a JSON string. That bug cost the {ok, reason} contract its first six months — every new surface inherits the convention or it cannot be chained.

Then: chaining itself

With the vocabulary in place, what remains is failure semantics. A chain that refuses at step three is not the same as one that never started, and whether the earlier steps roll back is per-chain and must be stated, not discovered. Decide it when the first real chain exists, not before.

Acceptance

• describe on every surface, with examples that parse, enforced by a test.
• Every refusal carries a code from the five; none carries only prose.
• A chain of four verbs across two surfaces records one intent in the trail, and reconstruction reads the decision rather than four orphans.
• A refusal mid-chain is legible enough for the agent to pick another path without being told what went wrong out of band.

Do not

• Build a new toolcall integration. Settled 2026-07-13: the agent reaches these through its existing harness.
• Let a surface invent its own refusal vocabulary.
• Inline the teaching. The surface exposes; the Souveraine School teaches.

Connects to

SESSION-AUTHORITY-DOCTRINE §13 (the mandate), SHELL-ECOSYSTEM.md (manifests + guarded methods), FIRST-CLASS-APPS.md §6/§7 (legibility and agency are two of the nine), SETTINGS-AUTHORITY.md, TASK-31 (the dial is the human rendering of the same vocabulary). souveraine-viewtop wire/verbs.rs is the compositor's table under this mandate (TASK-43); it gained pose (geometry, the agent's) and expose (legibility, gate-veiled) for scene composition on 2026-07-30 (61cf90a).