timeouts

Overview ¶

Package timeouts owns the ordered timeout hierarchy shared by SQLite, lifecycle ingress, slice workflows, and callers that wait for a whole workflow to finish.

A Profile holds one tier per waiting layer. A SQLite lock wait must end before either caller window can expire, and both of those must end before the caller stops waiting for the whole workflow. Ingress and StartSlice are siblings: neither is inside the other:

Tier           Field           Production   Bounds
innermost      SQLiteBusy      500ms        one SQLite lock wait, set as the
                                            DSN busy_timeout
caller window  Ingress         1s           one lifecycle receipt append,
                                            including its lock retries
caller window  StartSlice      2s           how long a slice sub-workflow
                                            waits for its start_slice signal
host window    HookInvocation  5s           how long one whole lifecycle hook
                                            invocation may take before it
                                            reports a fault to its host
outermost      WorkflowResult  30s          how long a caller waits for a
                                            whole workflow to report a result

HookInvocation sits below the smallest host budget this tree has evidence for, with headroom for process start. On Claude Code that budget is the 10s that hooks/hooks.json sets on every pasture lifecycle row ("timeout": 10). It is a value this tree configures per row and not the host's own default: a row without a timeout runs on that default, which this tree does not measure. The OpenCode plugin awaits the child process with no timeout of its own, and this tree carries no measurement of the Codex hook budget, so the tier is sized against the Claude rows; TestProductionHookInvocationSitsBelowTheSmallestHostBudget holds every lifecycle row of hooks/hooks.json to that value. A hook that outruns the host budget freezes the session, so pasture stops first and reports a fault, which fails open by default.

TestProfile (500ms / 2s / 3s / 6s / 30s) and DeadlineTestProfile (25ms / 250ms / 500ms / 1s / 2s) keep the same ordering with different budgets. New rejects any profile that inverts it.

An OPERATOR may tune three of the production tiers at run time, and the lifecycle hook reads them from its process environment: the hook-invocation deadline (PASTURE_HOOK_INVOCATION_TIMEOUT), the ingress window (PASTURE_INGRESS_TIMEOUT) and the start-slice window (PASTURE_START_SLICE_TIMEOUT). Each takes a Go duration; an unset or empty variable keeps the production value. The values are collected into an Override and applied with Profile.WithOverride, which re-runs New, so the ordering invariant above is preserved and an inverted combination is refused with the same error New returns rather than clamped.

The environment parser lives with the hook's other knobs in cmd/pasture/hook_environment.go; this package owns the values and the invariant, not the transport. The lifecycle command consumes HookInvocation (its work deadline) and Ingress (the receipt appender's deadline); StartSlice is the slice sub-workflow's signal wait, which the hook never reaches, and it is read and validated with its siblings so the invariant still covers it. The trade-off the operator owns: LOWERING the hook-invocation deadline makes a slow store fail fast — the hook abandons the work, reports a fault and answers the host fail-open, so the gate is left unevaluated while the host stops waiting at once instead of stalling for the whole window; RAISING it only helps on a fast store, because a hook that outruns the host's own budget freezes the session it was meant to protect.

Production code must read these values from an injected Profile and must not write a duration or a busy_timeout DSN literal of its own.

guard.CheckTimeoutSource enforces a narrow part of that rule: over the files listed in internal/lifecycle/guard/timeouts_test.go (eight today) it reports use of the retired DefaultIngressDeadline identifier and a string literal carrying the retired five-second busy_timeout pragma, and nothing else.

Two bootstrap retry ceilings live outside this profile on purpose, because they bound a retry loop rather than a single wait: busyRetryCeiling in internal/audit/migrate.go and dbosRaceRetryCeiling in internal/engine/dbosinit.go, both 30s. The forensic writer's private policy in internal/audit/write_retry.go instead derives one 30s operation context (or the earlier caller deadline), including pool acquisition, every transaction attempt and backoff. These retry/backoff and bounded cleanup policies are not replacements for the configured tiers.

The durable schema gate in internal/engine/schema_gate.go waits on two tiers of this profile when it finds a layout below the floor it reads: SQLiteBusy between looks at the recorded layout version, and WorkflowResult in total. No tier is defined for waiting out another process's whole bootstrap; WorkflowResult is the closest, as the outermost whole-operation wait.