Secret guard and template: cover the OpenHands runtime-worker session-key directory

[seathatflowsinourveins]

Scope

• What this PR changes: the Claude secret-path guard and the settings template now cover the OpenHands runtime-worker session-key directory, runtime-workers/openhands/secrets under the stack's state root.

  • PR Runtime worker: OpenHands on GPT-6 via OmniRoute (recipe, O1 isolation, reviewed repair round) #425's host driver writes each attempt's agent-server key there, to <run-id>-<arm>.server.env and <run-id>-<arm>.headers, at 0600 in a 0700 directory. The files are deleted once removal is confirmed.
  • Before this PR, only the .server.env file was caught, by the .env rule (dotenv_read). The .headers file, the directory and a glob in it were not.

• How: one alternative is added to HOME_CREDENTIAL_STORE. Only a reader, copy or search is blocked; ls, stat, chmod and docker run --env-file still pass. The template gains Read(~/.local/state/native-agent-stack/runtime-workers/openhands/secrets/**) plus its Read(**/...) twin.

• Deliberately not changed: OH_SESSION_API_KEYS_0 is not added to SECRET_NAMES.

  • The variable is never set on the host, so blocking $OH_SESSION_API_KEYS_0 protects nothing.
  • segment_reason would refuse ordinary code searches of that literal, which appears in Runtime worker: OpenHands on GPT-6 via OmniRoute (recipe, O1 isolation, reviewed repair round) #425's source and docs.
  • It would not cover the real vector either, because docker exec … printenv is not a reader.

  That vector is recorded as a named gap in docs/secret-storage.md.

• Lane: lane:foundation. manifests/evidence.json changes only by hash re-registration with host_receipts.register_file.

• Files:

  • scripts/hooks/secret_path_guard.py
  • adoption/templates/claude.settings.template.json
  • tests/test_secret_path_guard.py
  • docs/secret-storage.md: the coverage row, the 2026-09-27 store section and the recorded gaps
  • adoption/hooks/claude/SHA256SUMS: guard hash abf269ba…
  • manifests/evidence.json

SOTA sources

• Repository design this extends: docs/secret-storage.md, "Home and tool credential stores (2026-09-27)". Every template credential-store Read deny has a matching guard rule, and tests/test_secret_path_guard.py derives a reader from each deny and expects a block. The derived-reader test picked up the new deny without edits: red on cat, head -n 5, tail -n 3 and rtk read before the guard change, green after.
• Claude Code permission rules: code.claude.com/docs/en/permissions, read 2026-09-28. ~/ is home-relative, and a user-settings rule meant to apply in every project needs a ~/ or // anchor, hence the ~/… rule plus the **/… twin, matching the existing denies.
• Upstream behaviour it guards: Runtime worker: OpenHands on GPT-6 via OmniRoute (recipe, O1 isolation, reviewed repair round) #425's key files follow OpenHands agent-server OH_SESSION_API_KEYS_0 (OpenHands/software-agent-sdk@fcc102a, openhands-agent-server/openhands/agent_server/config.py:24, V1_SESSION_API_KEY_ENV = "OH_SESSION_API_KEYS_0").

Evidence

Claim	Evidence class	Command / result
The new rules block readers, copies and searches of the directory, its files and a glob in it	integration test	Red with the new tests only: FAILED (failures=49), covering plain commands, rtk proxy and keyring exec forms. Red plus the template deny: failures=52. Green: CI=true python3 -m unittest tests.test_secret_path_guard, Ran 16 tests, OK (skipped=1)
ls, stat, chmod, docker run --env-file, sibling runs/ reads and code searches of the variable name still pass	integration test	the same suite's allowed cases
No existing verdict changed in the replayed corpus	local replay (builder-run; not independently reproduced)	Base and new guard compared over 5,917 command lines from 616 Markdown files (the repo plus #425 at e45c3cd1) and #425's 81 recorded commands: 0 verdict changes. Outside that corpus, rg --fixed-strings 'runtime-workers/openhands/secrets' docs changes from pass to block (see Residuals)
The paper lane's keyring wrapper forms still pass	integration test	sh …/paperkeys.sh run 1 -- echo ok, kernel_keyring.py status, kernel_keyring.py exec --help added to ALLOWED, and pass on base and head
Template consumers are unaffected	integration test	tests.test_workflow_hardening 74 OK (2 skipped); the profile, apply-settings and render-config suites: 110 OK
Repository integrity	local check	python3 scripts/validate.py → "status": "passed" (7927 hashed files); sha256sum -c in adoption/hooks/claude: 9 OK; git diff --check rc 0

test_host_profile_copy_is_verbatim fails on a host until the installed guard copy is refreshed with python3 tools/adoption/install_claude_profile.py --only guard. It is skipped under CI=true, as documented.

Review

GPT-6 cross-family review (Codex CLI 0.157.1, gpt-6-astra, effort max, read-only) of 3a4fdbae: approve. It blocked all 462 of its direct reader, copy and search cases. The template forms were confirmed against the Claude permissions docs, and the 49/52 red counts were reproduced. There were four low/info amends, each replayed in-process against the base and head guards:

• path matching is literal;
• inherited pipeline and relative-path gaps;
• the --fixed-strings/-e false positive;
• an overstated variable-name rationale.

One repair round, 012f548f (docs only), records them. The raw verdict is posted as a PR comment.

Rollout

• The project hook runs the checkout's own scripts/hooks/secret_path_guard.py, so the rule is live for every session on a checkout as soon as it moves to this commit.
• The user-level hook copy and the settings template's Read denies take effect only after the profile installer and the template are applied on each host.
• The live paper-lane session is told before merge.

Residuals

• Matching is on the literal path: ./ or an interior //, a path relative to a parent, and pipeline-fed readers (find -print0 | xargs -0 cat, find -exec rtk read) pass. The same holds for older stores on the base guard.

• A search whose pattern goes through -e or an unmodelled long option (rg --fixed-strings 'runtime-workers/openhands/secrets' docs) is now blocked. This is the parser's existing behaviour for every store; a positional pattern passes.

• docker exec <server> printenv/env/a shell in the container, and a full docker inspect of the agent-server, still show the key. The guard does not model docker subcommands.

• A search or copy of the parent runtime-workers/openhands, a relative read after cd, and a key file copied outside the directory are not caught.

• The template deny names the default state root only. The guard matches the directory under any root.

🤖 Generated with Claude Code

[seathatflowsinourveins]

GPT-6 cross-family review of 3a4fdbae

Codex CLI codex-cli 0.157.1, model gpt-6-astra, effort max, read-only sandbox, via tools/sota-convergence/landscape-sweep/codex_call.sh. Overall: approve

id	verdict	severity	location	reason (condensed)
coverage	amend	low	scripts/hooks/secret_path_guard.py:117	All 462 direct reader, copy and search cases blocked, including trailing slashes, globs, quotes, HOME/XDG spellings and RTK wrappers. Matching is literal, though: rtk read …/openhands/./secrets/F and an interior // pass. The base guard behaves the same way (cat ~/.config/./omniroute/gateway.sqlite). Qualify the coverage claim.
inherited-reader-gaps	amend	info	scripts/hooks/secret_path_guard.py:555	find DIR -print0 | xargs -0 cat, find DIR -exec rtk read {} +, and paths relative to the state root (tar -cf - runtime-workers/openhands/secrets, < runtime-workers/openhands/secrets/F cat) pass. Equivalent gaps exist for older stores, but these forms are not listed.
false-positives	amend	low	scripts/hooks/secret_path_guard.py:548	rg --fixed-strings 'runtime-workers/openhands/secrets' docs changes from allowed to credential_file_read, because the parser treats an unrecognised long option's pattern as a path, and -e does the same. Plain -n searches, repository reads, sibling runs/ reads, ls, stat, chmod and docker run --env-file all pass. Scope the zero-change replay to its corpus.
template	confirm	info	adoption/templates/claude.settings.template.json:81	Both forms are valid per Claude permissions. The derived-reader tests block cat, head, tail and rtk read.
secret-name-rationale	amend	low	docs/secret-storage.md:1051	Omitting the name is defensible. However, listing it would also stop explicit lookups inside docker exec (python3 -c calling os.getenv(...)), not only a shell. Replace "never on the host" with the driver-specific statement.
evidence	confirm	info	tests/test_secret_path_guard.py:777	The 49/52 red counts, 16 tests OK with 1 skip, validate.py passing, 9 SHA256SUMS OK and diff --check were all reproduced independently. The 5,917-command replay and the consumer-suite counts were not.

Overall (verbatim): "approve — The intended literal-path protection works, the template syntax is correct, and the principal test and integrity claims are corroborated. The remaining bypasses inherit existing parser limitations rather than weaken prior protection. Two low-severity qualifications deserve follow-up: legitimate long-option searches can now be blocked, and the variable-name rationale understates protection of explicit lookups. Approval is for the documented accidental-exposure heuristic, not comprehensive credential isolation."

Disposition: each example command was replayed in-process through both the base and head guards, and all reproduced. 012f548f (docs only) records the literal-path, pipeline and relative-path gaps, the -e/long-option behaviour, and the narrowed variable-name rationale. The PR body now scopes the replay claim to its corpus and lists these as residuals. The decision not to list the name stands.

🤖 Generated with Claude Code