[Kyzcreig]

Summary

Closes the three backlog residuals logged by #80 (the F2 authoritative breadcrumb). Spec: 2026-06-22_f2-breadcrumb-backlog-cleanup.md (2× Opus spec review + 2× Opus diff review, both APPROVE).

Zero behavior change to the shipped #80 detection path — this is config + tests + docs, guarded by a source-guard test.

Item 3 — restart_* config family consistency

• Surface the whole family in DEFAULT_CONFIG["agent"] with doc comments: restart_loop_threshold: 3, restart_loop_window_secs: 300, restart_initiated_ttl_secs: 600 (== the live helper fallbacks).
• Add the missing restart_initiated_ttl_secs config→env bridge.
• Refactor: extracted the inline agent-config bridge block into _bridge_agent_config_to_env + _AGENT_CONFIG_ENV_BRIDGE (single-sourced, unit-testable). Behavior-neutral for all 8 existing knobs (a reviewer executed the equivalence proof over 8 input cases). config.yaml unconditionally wins over a pre-set env var, matching the shipped siblings (PR fix(auxiliary): strip trailing /v1 for OpenCode Zen/Go Anthropic bases NousResearch/hermes-agent#18413).
• Ride-along (not a behavior change): restart_loop_threshold/window_secs were already bridged but never in DEFAULT_CONFIG — they only worked if hand-added; now properly defaulted. The helpers already defaulted to 3/300 when unset.

Item 2 — breadcrumb contract drift insurance

• A # F2 BREADCRUMB CONTRACT block in gateway/run.py as the single documented source of truth.
• An always-on frozen-literal conformance test over a key vector (empty/4KB/unicode/slash). The skill (safe-restart.py, in ANG-Ventures/hermes-home) has a mirror test asserting the same literals — so drift in either repo reddens that repo's own CI, with no cross-repo skip-no-op.

Item 1 — watcher guardrail (skill side, lands in hermes-home)

• The watcher does a boot-matched breadcrumb check at kickstart and logs loudly when no current-boot crumb exists (a direct-watcher invocation that bypassed safe-restart.py). It can't write one (post-quiescence + wrong-boot), so it reads-only. + a SKILL.md "always use safe-restart.py" contract.

Testing

• 53 cascade tests (9 new) + 246 blast-radius (cascade + status + session-hygiene + config) green; ruff clean.
• RED-proven: bridge wire-up, config-wins precedence, conformance gate (dirname + hash skew), source-guard, watcher boot-match (presence-only would break it).
• Skill side: 59/59 green (mirror conformance + boot-matched guardrail RED-proven).

🤖 Generated with Apollo (Hermes agent)

[github-actions]

🔎 Lint report: fix/f2-breadcrumb-backlog vs origin/main

ruff

Total: 0 on HEAD, 0 on base (➖ 0)

🆕 New issues: none

✅ Fixed issues: none

Unchanged: 0 pre-existing issues carried over.

ty (type checker)

Total: 11345 on HEAD, 11328 on base (🆕 +17)

🆕 New issues (13):

Rule	Count
invalid-argument-type	9
unresolved-attribute	2
not-subscriptable	2

First entries

tests/gateway/test_restart_cascade.py:1066: [invalid-argument-type] invalid-argument-type: Method `__getitem__` of type `Overload[(i: SupportsIndex, /) -> str, (s: slice[SupportsIndex | None, SupportsIndex | None, SupportsIndex | None], /) -> list[str]]` cannot be called with key of type `Literal["restart_loop_window_secs"]` on object of type `list[str]`
tests/run_agent/test_credits_notices_toggle.py:76: [unresolved-attribute] unresolved-attribute: Unresolved attribute `_credits_session_start_micros` on type `AIAgent`
tests/gateway/test_restart_cascade.py:1065: [invalid-argument-type] invalid-argument-type: Method `__getitem__` of type `Overload[(i: SupportsIndex, /) -> str, (s: slice[SupportsIndex | None, SupportsIndex | None, SupportsIndex | None], /) -> list[str]]` cannot be called with key of type `Literal["restart_loop_threshold"]` on object of type `list[str]`
run_agent.py:2940: [unresolved-attribute] unresolved-attribute: Object of type `Self@get_credits_spent_micros` has no attribute `_credits_session_start_micros`
tests/gateway/test_restart_cascade.py:1067: [not-subscriptable] not-subscriptable: Cannot subscript object of type `None` with no `__getitem__` method
tests/gateway/test_restart_cascade.py:1065: [invalid-argument-type] invalid-argument-type: Method `__getitem__` of type `Overload[(i: SupportsIndex, /) -> Unknown, (s: slice[SupportsIndex | None, SupportsIndex | None, SupportsIndex | None], /) -> list[Unknown]]` cannot be called with key of type `Literal["restart_loop_threshold"]` on object of type `list[Unknown]`
tests/gateway/test_restart_cascade.py:1066: [invalid-argument-type] invalid-argument-type: Method `__getitem__` of type `bound method str.__getitem__(key: SupportsIndex | slice[SupportsIndex | None, SupportsIndex | None, SupportsIndex | None], /) -> str` cannot be called with key of type `Literal["restart_loop_window_secs"]` on object of type `str`
tests/gateway/test_restart_cascade.py:1066: [invalid-argument-type] invalid-argument-type: Method `__getitem__` of type `Overload[(i: SupportsIndex, /) -> Unknown, (s: slice[SupportsIndex | None, SupportsIndex | None, SupportsIndex | None], /) -> list[Unknown]]` cannot be called with key of type `Literal["restart_loop_window_secs"]` on object of type `list[Unknown]`
tests/gateway/test_restart_cascade.py:1067: [invalid-argument-type] invalid-argument-type: Method `__getitem__` of type `bound method str.__getitem__(key: SupportsIndex | slice[SupportsIndex | None, SupportsIndex | None, SupportsIndex | None], /) -> str` cannot be called with key of type `Literal["restart_initiated_ttl_secs"]` on object of type `str`
tests/gateway/test_restart_cascade.py:1067: [invalid-argument-type] invalid-argument-type: Method `__getitem__` of type `Overload[(i: SupportsIndex, /) -> str, (s: slice[SupportsIndex | None, SupportsIndex | None, SupportsIndex | None], /) -> list[str]]` cannot be called with key of type `Literal["restart_initiated_ttl_secs"]` on object of type `list[str]`
tests/gateway/test_restart_cascade.py:1065: [invalid-argument-type] invalid-argument-type: Method `__getitem__` of type `bound method str.__getitem__(key: SupportsIndex | slice[SupportsIndex | None, SupportsIndex | None, SupportsIndex | None], /) -> str` cannot be called with key of type `Literal["restart_loop_threshold"]` on object of type `str`
tests/gateway/test_restart_cascade.py:1067: [not-subscriptable] not-subscriptable: Cannot subscript object of type `int` with no `__getitem__` method
tests/gateway/test_restart_cascade.py:1067: [invalid-argument-type] invalid-argument-type: Method `__getitem__` of type `Overload[(i: SupportsIndex, /) -> Unknown, (s: slice[SupportsIndex | None, SupportsIndex | None, SupportsIndex | None], /) -> list[Unknown]]` cannot be called with key of type `Literal["restart_initiated_ttl_secs"]` on object of type `list[Unknown]`

✅ Fixed issues (1):

Rule	Count
invalid-assignment	1

First entries

tests/run_agent/test_credits_notices_toggle.py:76: [invalid-assignment] invalid-assignment: Object of type `None` is not assignable to attribute `_credits_session_start_micros` of type `int`

Unchanged: 5922 pre-existing issues carried over.

Diagnostics are surfaced as warnings — this check never fails the build.

[greptile-apps]

Greptile Summary

This PR closes three backlog items from the F2 authoritative-breadcrumb work (#80): it refactors the inline agent-config→env bridge into a single-sourced _AGENT_CONFIG_ENV_BRIDGE dict + _bridge_agent_config_to_env function, surfaces the full restart_* config family in DEFAULT_CONFIG, and adds a frozen-literal conformance gate for the cross-repo breadcrumb contract. There are no behavior changes to the shipped F2 detection path.

• Config bridge refactor (gateway/run.py): The 8-key inline block is replaced by _bridge_agent_config_to_env. The new function is unit-testable and the mapping is single-sourced; the new restart_initiated_ttl_secs key and its env-var bridge are added alongside the existing knobs.
• DEFAULT_CONFIG additions (hermes_cli/config.py): restart_loop_threshold: 3, restart_loop_window_secs: 300, and restart_initiated_ttl_secs: 600 are now documented defaults that match the live helper fallbacks.
• Test coverage (test_restart_cascade.py): Nine new tests covering bridge-map membership, precedence semantics, absent-key passthrough, clamp bounds, non-dict defensiveness, frozen-contract conformance, and a source-guard for the fix(gateway): authoritative restart-initiator breadcrumb for F2 breaker #80 detection path.

Confidence Score: 5/5

Safe to merge — config/docs/tests addition with a provably behavior-neutral refactor of the agent-config bridge.

The bridge refactor is equivalent to the old inline block for every input shape, and 9 new tests RED-prove the key invariants. The DEFAULT_CONFIG additions surface values that were already the effective runtime defaults.

No files require special attention.

Important Files Changed

Filename	Overview
gateway/run.py	Extracts inline agent-config→env bridge into _AGENT_CONFIG_ENV_BRIDGE dict + _bridge_agent_config_to_env function; behavior-neutral for all pre-existing knobs.
hermes_cli/config.py	Adds restart_loop_threshold, restart_loop_window_secs, restart_initiated_ttl_secs to DEFAULT_CONFIG with doc comments; values match live helper fallbacks.
tests/gateway/test_restart_cascade.py	Adds 9 new tests covering bridge map correctness, TTL clamping, precedence, absent-key passthrough, non-dict no-op, frozen-contract conformance, and a source-guard for the shipped #80 detection path.

_{Reviews (2): Last reviewed commit: "test: address Greptile review — drop dup..." | Re-trigger Greptile}