Filed from live #claw-code dogfood on 2026-04-08 where two real users
hit adjacent auth confusion within minutes:
- varleg set OPENAI_API_KEY for OpenRouter but prefix routing didn't
win because the model name wasn't prefixed with openai/; unsetting
ANTHROPIC_API_KEY then hit MissingApiKey with no hint that the
OpenAI path was already configured
- stanley078852 put an sk-ant-* key in ANTHROPIC_AUTH_TOKEN instead
of ANTHROPIC_API_KEY, causing claw to send it as
Authorization: Bearer sk-ant-..., which Anthropic rejects at the
edge with 401 Invalid bearer token
Both fixes delivered live in #claw-code as direct replies, but the
pattern is structural: the error surface doesn't bridge HTTP-layer
symptoms back to env-var choice.
Action block spells out a single main-side PR with three
improvements: (a) MissingCredentials hint when an adjacent
provider's env var is already set, (b) 401-on-Anthropic hint when
bearer token starts with sk-ant-, (c) 'which env var goes where'
paragraph in both README matrices mapping sk-ant-* -> x-api-key and
OAuth access token -> Authorization: Bearer.
All three improvements are unit-testable against ApiError::fmt
output with no HTTP calls required.
The original ROADMAP #25 entry claimed the root cause was missing
exec bits on generated hook scripts. That was wrong — a chmod-only
fix (4f7b674) still failed CI. The actual bug was output_with_stdin
unconditionally propagating BrokenPipe from write_all when the child
exits before the parent finishes writing stdin.
Updated per gaebal-gajae's direction: actual fix, hygiene hardening,
and regression guard are now clearly separated. Added a meta-lesson
about Broken pipe ambiguity in fork/exec paths so future investigators
don't cargo-cult the same wrong first theory.
Filing per gaebal-gajae's status summary at message 1491322807026454579
in #clawcode-building-in-public, with corrected scope after re-running
`cargo test -p rusty-claude-cli` against main HEAD (79da4b8): the 11
deterministic failures only reproduce on dev/rust, not main, so this is
a dev/rust catchup item rather than a main regression.
Two-layered root cause documented:
1. dev/rust `parse_args` eagerly validates user plugin hook scripts
exist on disk before returning a CliAction
2. dev/rust test harness does not redirect $HOME/XDG_CONFIG_HOME to a
fixture (no `env_lock` equivalent — main has 30+ env_lock hits, dev
has zero)
Together they make dev/rust `cargo test -p rusty-claude-cli` fail on
any clean clone whose owner has a half-installed user plugin in
~/.claude/plugins/installed/. main has both the env_lock test isolation
AND the parse_args/hook-validation decoupling already; dev/rust is just
behind on the merge train.
Action block in #27 spells out backporting env_lock + the parse_args
decoupling so the next dev/rust release picks this up.
Linux CI keeps tripping over
`plugins::hooks::tests::collects_and_runs_hooks_from_enabled_plugins`
with `Broken pipe (os error 32)` when the hook runner tries to spawn a
child shell script that was written by `write_hook_plugin` without the
execute bit set. Fails on first attempt, passes on rerun (observed in CI
runs 24120271422 and 24120538408). Passes consistently on macOS.
Since issues are disabled on the repo, recording as ROADMAP backlog
item #25 in the Immediate Backlog P2 cluster next to the related plugin
lifecycle flake at #24. Action block spells out the chmod +755 fix in
`write_hook_plugin` plus the regression guard.
Concrete follow-up captured from today's dogfood session:
A single hung test (oversized-request preflight, 6 minutes per attempt
after `be561bf` silently swallowed count_tokens errors) crashed the
`cargo test --workspace` job before downstream crates could run, hiding
6 separate pre-existing CLI regressions until `8c6dfe5` + `5851f2d`
restored the fast-fail path.
Two new acceptance criteria for #9:
- per-test timeouts in CI so one hang cannot mask other failures
- distinguish `test.hung` from generic test failures in worker reports
Filed: openai/ prefix model misrouting (fixed in 0530c50).
Documents root cause, fix, and the architectural lesson:
- metadata_for_model is the canonical extension point for new providers
- auth-sniffer fallback order must never override explicit model-name prefix
- regression test locked in to guard this invariant
Closes the ambiguity gaebal-gajae flagged: downstream tooling was left
guessing which integration surface to build against.
Decision: claw state + .claw/worker-state.json is the blessed contract.
HTTP endpoint not scheduled. Rationale documented:
- plugin scope constraint (can't add routes to opencode serve)
- file polling has lower latency and fewer failure modes than HTTP
- HTTP would require upstreaming to sst/opencode or a fragile sidecar
Clawhip integration contract documented:
- poll .claw/worker-state.json after WorkerCreate
- seconds_since_update > 60 in trust_required = stall signal
- WorkerResolveTrust to unblock, WorkerRestart to reset
WorkerCreate requires trusted_roots per-call; no config-level default.
Any batch that forgets the field stalls all workers at trust_required.
Root cause of several 'batch lanes not advancing' incidents.
Recommended fix: wire RuntimeConfig::trusted_roots() as default into
WorkerRegistry::spawn_worker(), with per-call overrides. Update
config_validate schema to include the new field.
WorkerStatus state machine exists in worker_boot.rs and is exported
from runtime/src/lib.rs. But claw-code is a plugin — it cannot add
HTTP routes to opencode serve (upstream binary, not ours).
/state HTTP endpoint via axum was never implemented. Prior session
summary claiming commit 0984cca was incorrect.
Recommended path: write WorkerStatus transitions to
.claw/worker-state.json on each transition (file-based observability,
no upstream changes required). Wire WorkerRegistry::transition() to
atomic file writes + add CLI subcommand.
Global session store causes cross-worktree confusion in parallel lanes.
Added workspace_root field to session metadata and documented root cause
in ROADMAP.md.
The audit fix already landed, but the roadmap entry was split across two separate done items for /sandbox and inventory even though the underlying defect was one resumed-local-command JSON parity surface. Consolidating the note makes the machine-readable gap precise and keeps the backlog trail aligned with the actual fix scope.
Constraint: Preserve the existing issue ordering and backlog context around issues 23-24
Rejected: Leave the split entries as-is | obscures that one parity bug covered the same resumed JSON dispatch path
Confidence: high
Scope-risk: narrow
Reversibility: clean
Directive: Record future parity audits as one backlog item per underlying contract gap, not per individual command symptom
Tested: Existing green verification from HEAD remains applicable; docs-only wording update
Not-tested: No additional code-path verification required for this wording-only change
Resumed slash dispatch was still dropping back to prose for several JSON-capable local commands, which forced automation to special-case direct CLI invocations versus --resume flows. This routes resumed local-command handlers through the same structured JSON payloads used by direct status, sandbox, inventory, version, and init commands, and records the inventory parity audit result in the roadmap.
Constraint: Text-mode resumed output must stay unchanged for existing shell users
Rejected: Teach callers to scrape resumed text output | brittle and defeats the JSON contract
Confidence: high
Scope-risk: narrow
Reversibility: clean
Directive: When a direct local command has a JSON renderer, keep resumed slash dispatch on the same serializer instead of adding one-off format branches
Tested: cargo fmt --check; cargo test --workspace; cargo clippy --workspace --all-targets -- -D warnings
Not-tested: Live provider-backed REPL resume flows outside the local test harness
Persist derived machine states for agent manifests so downstream monitors can distinguish working, blocked, degraded, and finished-cleanable lanes without inferring everything from prose. This also records commit provenance in terminal-state manifests and marks the new session-state classification roadmap item as done.
Constraint: Keep the change scoped to manifest persistence and tests without introducing a new monitoring service layer
Rejected: Leave state classification as downstream text scraping only | repeated dogfood runs showed quiet/finished lanes being misreported as stale
Confidence: medium
Scope-risk: narrow
Directive: Reuse derived_state + commit provenance from manifests before adding any new stale-session heuristics elsewhere
Tested: python .github/scripts/check_doc_source_of_truth.py
Tested: cd rust && cargo fmt --all --check
Tested: cd rust && cargo test -q -p tools
Tested: cd rust && cargo clippy -p tools --all-targets --no-deps -- -D warnings
Not-tested: full cargo clippy --workspace --all-targets -- -D warnings still fails on unrelated pre-existing runtime lint debt
Finish the remaining roadmap work by making direct CLI JSON output deterministic across the non-interactive surface, restoring the degraded-startup MCP test as a real workspace test, and adding branch-lock plus commit-lineage primitives so downstream lane consumers can distinguish superseded worktree commits from canonical lineage.
Constraint: Keep the user-facing config namespace centered on .claw while preserving legacy fallback discovery for compatibility
Constraint: Verification needed to stay clean-room and reproducible from the checked-in workspace alone
Rejected: Leave the output-format contract implied by ad-hoc smoke runs only | too easy for direct CLI regressions to slip back into prose-only output
Rejected: Keep commit provenance as free-form detail text | downstream consumers need structured branch/worktree/supersession metadata
Confidence: medium
Scope-risk: moderate
Directive: Extend the JSON contract through the same direct CLI entrypoints instead of adding one-off serializers on parallel code paths
Tested: python .github/scripts/check_doc_source_of_truth.py
Tested: cd rust && cargo fmt --all --check
Tested: cd rust && cargo test --workspace
Tested: cd rust && cargo clippy -p commands -p tools -p rusty-claude-cli --all-targets --no-deps -- -D warnings
Not-tested: full cargo clippy --workspace --all-targets -- -D warnings still reports unrelated pre-existing runtime lint debt outside this change set
Replace the stale Python-first README narrative, old community links, and leftover branded metadata with the current Rust-first repo guidance. Also align funding handles and asset naming so the public docs point at the canonical ultraworkers/claw-code surface.\n\nConstraint: Scope limited to docs/metadata and branding residue; no runtime behavior changes\nRejected: Add a new CI lint in this pass | outside the requested docs-and-config cleanup scope\nConfidence: medium\nScope-risk: narrow\nReversibility: clean\nDirective: Keep README, funding metadata, and community links aligned with ultraworkers/claw-code and the current UltraWorkers Discord invite\nTested: stale-branding grep across markdown/.github; root doc-link existence checks; cargo fmt --all --check; cargo check --workspace; cargo test --workspace\nNot-tested: cargo clippy --workspace --all-targets -- -D warnings | fails on pre-existing runtime lint debt unrelated to these doc changes
session_control is pub exported but has zero consumers workspace-wide.
trust_resolver types are re-exported but never instantiated outside
unit tests. These implement core clawability contracts that are
structurally dead — built but not wired into the actual execution path.
Config merge validation gap fixed at 5bee22b:
- Hook validation before deep-merge in config.rs
- Source-path context for malformed entries
- Prevents non-string hook arrays from poisoning runtime
Structured task packet format shipped at dbfc9d5:
- TaskPacket struct with validation and serialization
- TaskScope resolution (workspace/module/single-file/custom)
- Integration into tools/src/lib.rs
- task_registry.rs coordination for runtime task tracking
Temporarily ignore manager_discovery_report_keeps_healthy_servers_when_one_server_fails
to unblock worker-boot session progress. Test has intermittent timing issues in CI
that need proper investigation and fix.
- Add #[ignore] attribute with reference to ROADMAP P2.15
- Add P2.15 backlog item for root cause fix
Related: clawcode-p2-worker-boot session was blocked on this test failing twice.
Implement automatic lane completion detection:
- detect_lane_completion(): checks session-finished + tests-green + pushed
- evaluate_completed_lane(): triggers CloseoutLane + CleanupSession actions
- 6 tests covering all conditions
Bridges the gap where LaneContext::completed was a passive bool
that nothing automatically set. Now completion is auto-detected.
ROADMAP P1.3 marked done.
- P2.13: Mark session completion failure classification as done
(WorkerFailureKind::Provider + observe_completion() + recovery bridge)
- P2.14: Add config merge validation gap (active bug being fixed in
clawcode-issue-9507-claw-help-hooks-merge lane)
The config merge bug: deep_merge_objects() can produce non-string
values in hooks arrays, which fail validation in optional_string_array()
at claw --help time with 'field PreToolUse must contain only strings'.
Add WorkerFailureKind::Provider variant and observe_completion() method
to classify degraded session completions as structured failures.
- Detects finish='unknown' + zero tokens as provider failure
- Detects finish='error' as provider failure
- Normal completions transition to Finished state
- 2 new tests verify classification behavior
This closes the gap where sessions complete but produce no output,
and the failure mode wasn't machine-readable for recovery policy.
ROADMAP P2.13 backlog item added.
