Scripts vs Services

HaltState supports both scheduled scripts and long-running services, but their retry and reporting patterns differ.

Scheduled scripts

A script should derive stable idempotency keys from the scheduled business unit, call the guard path, execute only when allowed, report success or error, and exit cleanly when approval is pending or denied. The next run can retry the same key and continue safely.

Long-running services

A service should keep the guard call near the tool boundary, use short timeouts, fail closed for high-risk actions, and keep local state transitions explicit. Services commonly need a post-action report path because execution can fail after a policy allow.

Worker-ledger pattern

The refund agent uses a server-side ledger because business actions need durable transitions. A row starts as NEW, moves through GUARDING, then becomes ALLOWED, APPROVAL_REQUIRED, DENIED, EXECUTED, or ERROR. That is safer than a browser-side simulation because the authority and execution record stay server-side.

Pattern table

Scenario	Pattern	Why
Cron jobs	Exit and retry	The scheduler naturally retries the same idempotency key.
CI/CD pipelines	Exit and retry	The pipeline can pause or rerun after approval.
Web servers	Callbacks or ledger state	The service is already long-running and can resume pending work.
Queue workers	Ledger state	Durable rows make claim, guard, execution, and report transitions testable.
CLI tools	Exit and retry	The user can rerun with the same key.

Service callback shape

def handle_approval(decision):
    if decision.approved:
        execute_pending_action(decision.request_id)
    else:
        mark_rejected(decision.request_id, decision.reason)

client.on_approval(handle_approval)

Callbacks are useful for always-on services, but high-risk actions still need durable local state so restarts do not lose pending work.

Implementation notes

Keep the HaltState call as close as possible to the side effect. The agent may plan and draft freely, but the wrapper around the actual action should be the place where authority is checked. That wrapper should send only the context required for policy evaluation: safe identifiers, normalized amounts, action names, risk flags, schedule windows, and redaction status. Raw customer payloads and secrets should stay in the business system or protected operator tooling.

Operational evidence

For each action, preserve the decision, the worker outcome, the idempotency key, safe resource references, latency, proof status, and redaction status. This evidence supports incident response and control narratives because it shows what the system did at runtime rather than only describing what the policy document intended. HaltState supports alignment work; it is not a substitute for legal advice or a compliance certification.