Summary
When claw up generates a principals.json containing verbs the running claw-api image doesn't recognise (e.g. schedule.read, schedule.control), claw-api fails validation and crash-loops. It never starts, providing no API surface to the pod, and the only evidence is a repeating log line:
claw-api: validate claw-api principals "/claw/principals.json": principal "sentinel": unknown verb "schedule.read"
This happened on Tiverton when claw CLI v0.6.1 generated schedule.* verbs for sentinel's invoke schedule config, but the claw-api container image predates those verbs.
Expected behaviour
claw-api should not hard-fail on unknown verbs. It should log a warning (WARN: ignoring unknown verb "schedule.read" for principal "sentinel") and start normally, treating the unknown verb as a no-op.
claw up should detect version skew. If the CLI emits config the target image can't consume, it should warn at generate time (e.g. WARNING: claw-api image may not support verb "schedule.read" — consider rebuilding).
- Crash-loop without user-facing notice is a general anti-pattern. Any validation failure in a generated config file should surface clearly, not silently restart in a loop.
Reproduction
- Have
claw >= 0.6.1 with an agent using invoke: schedule:
- Have a
claw-api image that predates schedule.* verb support
claw up -d
claw-api enters crash-loop
Workaround
Manually edit .claw-runtime/claw-api/principals.json to remove the schedule.read / schedule.control verbs, then claw compose restart claw-api.
Impact
- Silent crash-loop took all agents offline (no governance API)
- Required manual investigation of container logs to diagnose
- Easy to miss in production since Docker shows the container as "Restarting" not "Error"
Summary
When
claw upgenerates aprincipals.jsoncontaining verbs the runningclaw-apiimage doesn't recognise (e.g.schedule.read,schedule.control),claw-apifails validation and crash-loops. It never starts, providing no API surface to the pod, and the only evidence is a repeating log line:This happened on Tiverton when
clawCLI v0.6.1 generatedschedule.*verbs for sentinel'sinvokeschedule config, but theclaw-apicontainer image predates those verbs.Expected behaviour
claw-apishould not hard-fail on unknown verbs. It should log a warning (WARN: ignoring unknown verb "schedule.read" for principal "sentinel") and start normally, treating the unknown verb as a no-op.claw upshould detect version skew. If the CLI emits config the target image can't consume, it should warn at generate time (e.g.WARNING: claw-api image may not support verb "schedule.read" — consider rebuilding).Reproduction
claw>= 0.6.1 with an agent usinginvoke: schedule:claw-apiimage that predatesschedule.*verb supportclaw up -dclaw-apienters crash-loopWorkaround
Manually edit
.claw-runtime/claw-api/principals.jsonto remove theschedule.read/schedule.controlverbs, thenclaw compose restart claw-api.Impact