local_exec

Module: local_exec

Contents

Modules

• handler - Local-exec governance request handler.
• token_store - Approval token state machine for HITL local-exec governance.

---

Module: handler

Local-exec governance request handler.

[LocalExecHandler::decide] is the entry point for governance decisions:

• Fresh request (no approval_token): apply the configured [DefaultAction] and, when the action is PendingHitl, issue a new approval token in TokenState::Pending state bound to the request context.
• Retry with token (approval_token present): validate the token against the store. [TokenValidationResult::Valid] produces allow; [TokenValidationResult::Pending] produces pending_hitl (keep polling); every other state is a fail-closed deny.

[LocalExecHandler::decide_management] handles operator approval and revocation commands over the same UDS endpoint:

• local.exec.approve — transitions a Pending token to Approved, making it consumable by the next firma-run retry.
• local.exec.revoke — transitions a Pending or Approved token to Revoked, permanently blocking the corresponding execution.

All deny paths include a human-readable reason string so operators can diagnose why a launch was blocked.

Module: token_store

Approval token state machine for HITL local-exec governance.

The [TokenStore] trait defines the contract. Tokens go through:

Pending  → Approved   (operator explicitly approves via management API)
Pending  → Revoked    (operator explicitly revokes via management API)
Pending  → Expired    (TTL elapsed before operator decision)
Approved → Consumed   (single successful validate_and_consume call)
Approved → Expired    (TTL elapsed before firma-run retried after approval)

Every property listed in the architecture spec is enforced:

• Short-lived: tokens carry an absolute expiry.
• Single-use: the Consumed transition is atomic; a second call returns [TokenValidationResult::AlreadyConsumed].
• Server-side tracked: state lives in the store, never on the wire.
• Context-bound: each token is bound to the fingerprint, session_id, sandbox_id, and optionally agent_id that were present at issuance. Any mismatch returns [TokenValidationResult::ContextMismatch] or [TokenValidationResult::FingerprintMismatch].
• Operator-gated: Pending tokens return [TokenValidationResult::Pending] on retry until an operator explicitly approves them. Only [TokenState::Approved] tokens are consumable.

The default implementation is [InMemoryTokenStore]. Alternative backends (Redis, distributed stores, test doubles) implement [TokenStore] and are passed to [super::handler::LocalExecHandler] via [super::handler::LocalExecHandler::with_store].