Guard seam: one decision function for every privileged action (guarded-actions phase 2)

[moshe-nanoco]

Every privileged action crossing the container or channel boundary now passes one decision function — guard() in the new src/guard/ leaf — before it executes: allow | hold | deny.

The problem this solves

Gating was voluntary. Each call site decided inline whether to check anything — create-agent.ts's cli_scope === 'global' branch, dispatch's per-command access constants, router gates that default allow-all when the permissions module isn't loaded. Nothing guaranteed a privileged action passed any gate, and a new feature could ship ungated silently.

The fix is structural, not behavioral: today's checks stay the decision, verbatim — they move to one seam that the privileged entry points provably pass. This PR deliberately does not make policy data-driven; that is a separate problem, deferred (a generalized rules table can arrive later).

What ships

• src/guard/ domain-free leaf — guard(action, input) runs the action's decide (today's structural checks: allow | hold | deny) → grant check, fail-closed on throw. defineGuardedAction returns a branded value and consult sites carry the value, so a typo'd action or dropped module-edge import is a compile error, not a silent allow; a forged value denies at runtime.
• Module-edge decisions — guard.ts adapters define the domain entries: agents.create, a2a.send (destination ACL + agent_message_policies hold inside the decide), self_mod.*, senders.admit, channels.register.
• Keyed registries demand a guard at registration — every ncl command derives its guard from its own CommandDef inside register() (dotted action names stamped by registerResource); a delivery action registers with a guard spec or an explicit unguarded(<reason>) declaration — omission doesn't compile, grep "unguarded(" is the justified inventory, and re-registering a guarded action without a spec throws instead of silently disarming the guard. The consult pipeline (runGuarded, DeliveryGuardSpec) lives in src/delivery-guard.ts so delivery.ts keeps main's shape.
• Broadcast hooks stay plain registrations — response handlers and message interceptors are unchanged from main; the privileged click path (the channel-registration card handler) consults the guard inline, like the a2a route and the unknown-sender gate. The free-text name reply is deliberately not re-authorized — the click arms the capture and stands as the auth, exactly as on main.
• Grant-carrying replay — approved continuations re-enter their entry point with the verified approval row as the grant (ApprovalHandlerContext.approval); a grant satisfies a hold, never a deny (live-row + grantActionName + grantCoversRequest checks). The forgeable approved: true boolean is deleted — it was the same voluntary-gating hole on the replay path: any in-process caller passing it executed ungated.
• Conformance as a CI test — src/guard/conformance.test.ts walks the real registries: every holding action pairs with a registered approval handler, every mutating ncl command holds via cli_command, duplicate definitions throw. (No boot-time enforcement: at runtime a missing continuation already resolves loudly — the requester is told no handler is installed.)

Behavior deltas (deliberate, inherent to a non-vacuous gate on replays — also in CHANGELOG)

• a2a approve-then-revoke no longer delivers — the structural checks re-run live on replay. A grant that short-circuited the decision would be a second door.
• Forged / already-consumed / mismatched grants refuse instead of executing (previously any in-process caller passing approved: true executed).

Everything else is main's behavior verbatim: host trusted-caller, cli_scope enforcement, create_agent's scope branch, a2a check order, unconditional self-mod hold, unknown_sender_policy, channel click-auth (anchor-group approver included), click-armed name capture. Sender/channel holds stay on their own tables; holds map onto the existing requestApproval (approverUserId).

Deliberately NOT here

• The approval-contract work (approver rules/mayResolve, migration, sender fold) — separate PR.
• The D1/D2/D4 click-auth fixes from the defect inventory — a separate PR owns them (D2's ?? { caller: 'host' } replay fallback is preserved verbatim).
• Policy-as-data (a runtime rules table + ncl guard surface).
• Flagged fast-follows: commands.admin (chat slash-command gate in command-gate.ts), guard declarations on the router's single-slot gate setters (setAccessGate / setSenderScopeGate / setChannelRequestGate); credentials.use stays on the OneCLI gateway.
• Zero changes under container/.

Verification

pnpm test 773/773 (79 files) · pnpm run build clean — at 5a114b5 (current main merged in; the channel-defaults suites pass against the guard-consulting paths).

🤖 Generated with Claude Code