Agent policy legibility, plus the Windows stall bisect

[b-macker]

Summary

Three usability defects on the agent policy surface, all reported from real application use and each traced to a line and verified against the agent stub before being changed. Three follow-up commits then chased a CI stall that blocked the PR and ended up locating it.

1. The shell response scan claimed an execution that never happened

agent_impl.cpp gates a response content scan on shell_allowed — the same flag checkShellAllowed() (governance_engine.cpp:1870) uses for real execution — then reported Shell execution is blocked for this agent role. Nothing was executed. Reproduced against the stub with capabilities.shell.enabled: true globally and only the agent's shell_allowed: false.

The scan matches $ <command> lines, so the blast radius is wider than "shell". Measured:

response content	verdict
$ npm install express	BLOCKED
Python fence containing # sudo apt install	OK
prose: "you can use rm to remove files"	OK
pure prose	OK

An agent restricted from shell cannot write install instructions for any language — npm, pip, apt, curl, wget all sit in that pattern. The message now names what was matched and says plainly that nothing ran. Splitting the flag is a schema change and is not done here.

2. Per-agent policy refusals did not name the agent

All seven omitted it, while 30 of 111 Agent error: throws in the same file do format in config_name — including the response-scan errors three functions away. Two conventions; the refusals picked the wrong one. With 13 agents configured, Action matrix does not include AGENT_SEND is unattributable.

The agent.create refusal additionally says which sense of AGENT_SEND it means, because the permission is overloaded: at agentSend:1789 it grants "may be sent to", at agentCreate:1072 "may spawn children".

3. Nine environment state keys vanished instead of defaulting

dict.get() returns null for both "absent" and "zero". Adjacent keys disagreed: tool_integrity_count has an explicit zero on its else path, tool_calls_total simply disappeared when tools were off.

The defaults are deliberately not uniform:

keys	absent means	default	why
tool_calls_total, _blocked, _latency_ms	tools off	0	no calls were made — 0 is honest
lease_remaining, _seconds	no lease configured	-1	0 is what an expired lease reports
turns_remaining, tokens_remaining	no limit configured	-1	0 is what an exhausted budget reports
risk_budget_remaining	no budget configured	-1	same

Defaulting the lease and budget keys to 0 replaces a silent absence with a confident lie. -1 is the sentinel already used by escalation_turn (837) and tokens_remaining's own unlimited case (697).

4–6. The Windows stall, and what actually found it

build-windows had stalled four times inside CLI tests — shell suites: step in_progress ~47 minutes, runner killed service-side, log archive 404. timeout-minutes failed to fire on two of those, so the runner could not enforce its own step timeout — the cause could not be read out, only excluded.

Two wrong turns, recorded because they cost the most time:

• d05a65d hardened the stub launcher (port retry, longer readiness ceiling) after three Linux suites failed across two runs. It then stalled Windows, and a one-commit bisect (056e659 passed → d05a65d stalled, delta = launcher only) looked conclusive. It wasn't. 79a7f20 restored the Windows path to byte-equivalent prior behaviour and stalled anyway. The bisect was coincidence.
• The set of "9 stub suites" came from grepping one launcher idiom rather than for agent_stub.py. The real population is 29. Excluding 9 would have left 20 running and made a negative result uninterpretable.

The answer was already in the tree. test_absorption_degenerate.sh has carried this since before any of this work:

"Stub-backed HTTP tests hang on Windows/MSYS2 due to signal propagation and process cleanup issues. Skip entirely — Linux CI validates the behavior."

The diagnosis was made once and applied to one file out of 29. e5c6f00 applies it to all of them, and the result is unambiguous:

	CLI tests — shell suites
last two runs	in_progress 47 min → runner killed
last passing run (29 suites running)	4m04s
this run (29 excluded)	2m04s ✅

Coverage is not lost: build-linux and Build & Test run all 29 in full, and agent-governance semantics are platform-neutral. Reversible in one commit.

Retraction

An earlier revision of this description claimed a security gap: that agent.commit() re-checks lease and CRITICAL but not allowed_actions, so a proposal could be committed after AGENT_SEND was ratcheted away. That is wrong and the gap does not exist.

agentCommit already carries a reload-generation check (getReloadCount() != selected.reload_count) stamped at propose time. reload_count_++ fires only on an accepted reload (governance_config.cpp:3873), and allowed_actions is config-derived, so it cannot change without invalidating the proposal first. s_pending_proposals has exactly one insert — inside agentPropose, behind its own AGENT_SEND check — so a caller cannot supply a proposal either. Covered by test_propose_commit.sh H-01/H-02, which pass 25/25.

I missed it by grepping allowed_actions|AGENT_SEND|checkCriticalSuspension|leaseExpiredLocked|checkAdmission — reload_count was not in the pattern, so the guard was invisible. Same grep-shaped-model error as the 9-vs-29 count above.

Test Plan

• Ran bash run-all-tests.sh with no new failures — 441 tests, 0 unexpected failures
• bash tests/security/test_error_msg_leaks.sh — 874 checks, 0 failures (error text changed, so this one matters)
• Added/updated tests for new functionality — n/a for the fixes; the CI commits change test infrastructure only
• Tested manually in the REPL — n/a

Verified per fix against the agent stub, before and after:

fix	before	after
1	"contains shell commands / Shell execution is blocked"	"shell command syntax / nothing was executed", names the $ <cmd> pattern
2	Action matrix does not include AGENT_SEND	Agent 'deploy_lead' — action matrix does not include AGENT_SEND
3	3 keys missing on a no-tool no-lease agent	tool_calls_total=0, lease_remaining=-1, risk_budget_remaining=-1

All 29 guards were observed taking the skip under a simulated MINGW uname, not assumed to fire. A static coverage check flagged 4 as unguarded; that was a false positive matching a header comment above the guard, and the dynamic check settled it.

Follow-ups not in this PR

• The pending stall bisect comments in the 29 guards describe a hypothesis that is now resolved; they should be rewritten to state the finding and consolidated into a shared guard.
• Fixing the launcher's Windows signal/cleanup behaviour rather than excluding the suites, per the original diagnosis.
• AGENT_SEND and shell_allowed are both overloaded; splitting either is a govern.json schema break.
• Narrowing the $ <cmd> pattern is a behaviour change to a security check and needs a control proving real shell content still blocks.

---

Generated by Claude Code

[github-actions]

NAAb Governance Report

Metric	Count
Files checked	16
Passed	16
Failed	0

All governance checks passed!

_{Generated by NAAb Governance Engine v4.0}