fix(agent): snapshot workflow runtime state without committing it

[simple-agent-manager]

Summary

• Make .workflow-state.md and .do-state.md visible to SAM sleep snapshots by removing their .gitignore entries.
• Add quality:runtime-state-files, reject root/nested state remaining in the Git index, allow corrective staged deletion, and run the guard in both check:fast and blocking CI lint.
• Fix Sonar S2871 and S4036 with an explicit comparator and a configurable absolute Git executable; add real-Git regressions and synchronize workflow instructions.

This fixes the failure mode where a parent workflow stored its durable wake state only in a gitignored local file, then lost that file after sleep/recovery/runtime replacement.

Release Status — merged after all gates passed

Final head: d67f1dd2922e01083ad4620168f453379df68ce5. All applicable checks passed, including CI37593529762, Code Quality Checks, Specialist Review Evidence, and SonarCloud Code Analysis. Sonar reports quality gate OK, zero bugs, zero vulnerabilities, and zero code smells for this exact commit. Verified2026-10-07 08:41Z. PR merged2026-10-07 08:42Z as 97f454fdcccc2a51d9a7521af7023336b2d316c8. SAM output branch also points to the validated final candidate. Post-merge main CI attempt1 failed only an unchanged RepoSelector UI test (repo-selector.test.tsx:73); all other jobs passed. The failed job was rerun once: attempt2 passed on the identical merge commit2026-10-07 09:09Z. No source change was needed; intermittent failure confirmed. Timing-race follow-up recorded as undispatched SAM idea 01M4ASCE5M2Y9ZMJTGAHCR4P5W. Main CI is green. Production deployment 37597095301 succeeded2026-10-07 09:12Z on descendant 294556e89346a33c1466361634f7e7584eae1d5d. Verified Git ancestry includes this PR’s merge 97f454fdcccc2a51d9a7521af7023336b2d316c8; GitHub production deployment marker 6906113501 reports success.

Fresh analysis cleared S2871 and exposed S4036 inherited PATH lookup. Both are fixed: explicit sort comparator and a configurable absolute Git executable with relative overrides rejected. Independent security/constitution/docs review passed; focused16tests and full49-file658-test quality suite passed. No suppression or gate waiver was used.

Automatic Analysis was already enabled; no global settings changed. Earlier same-SHA check suites were attributed to the separate SAM output branch. Unique commits pushed only to the PR branch received fresh analyses after a delay; branch attribution remains a possible contributor, not a proven service root cause.

CodeRabbit's trusted request was quota-limited. The original15-minute observation and final-fix incremental observation08:24Z–08:41Z completed with no review/findings; automatic incremental reviews reported disabled. No re-trigger loop or human waiver. Staging is unnecessary for repository-only changes.

Sonar PR result.

Validation

• Local pnpm typecheck: 19 tasks passed.
• Local pnpm build: 9 tasks passed.
• Quality-script suite: 49 files, 655 tests passed with two workers. Initial unconstrained run hit an unrelated 5s deployment-fixture timeout; isolated retry passed all 61 tests.
• Independent focused verification: 2 files, 13 tests passed.
• Existing Go snapshot regressions: go test ./internal/server -run 'Snapshot.*(WIP|Restore)|WIP.*Snapshot' -count=1 passed.
• pnpm quality:agent-context-budget measured after concise instruction wording updates; codex --cd /workspaces/sam-pr2227 debug prompt-input confirmed the target instruction context loads. No context limit increased.
• Local pnpm check:fast passed: format ratchet, Oxlint, ESLint (existing warnings only), type-boundary audit, and runtime-state guard.
• Earlier implementation CI 37505740686 passed on implementation commit 7734b3cc76e68e3417edadcdc35b33c3cf507189, including Code Quality Checks and Specialist Review Evidence.
• Earlier candidate 0384d2a1e473b75c53c29c8202a96ceae3f156ac: CI 37508045292 passed all applicable checks.
• S4036 follow-up: 16 focused tests and full49-file658-test quality suite passed; ESLint and runtime-state guard passed; independent security/constitution/docs review passed.
• Final candidate CI 37593529762 passed all applicable checks.
• SonarCloud Code Analysis passed on d67f1dd2922e01083ad4620168f453379df68ce5: gate OK, bugs0, vulnerabilities0, code smells0. Both S2871 and S4036 fixed without suppression.

The Git regression uses the actual repository ignore policy, captures both local state files through a separate index, materializes them on restore, and verifies the real index remains untouched. Additional cases reject staged/committed root and nested state, allow corrective removal, and fail closed outside a Git repository.

Staging Verification

Not needed under this task's explicit condition: only repository Git policy, quality scripts, CI wiring, and workflow guidance changed. No deployed Worker, web, or VM-agent implementation changed. Local real-Git tests exercise the affected contract, existing Go snapshot tests pass, and an independent snapshot specialist traced both runtimes' capture/restore code. A staging app deployment would not exercise a different changed runtime path.

This is Git snapshot tree/materialization contract verification, not a live SAM sleep/R2 round trip. Existing size limits and degraded-snapshot behavior still apply.

UI Compliance Checklist (Required for UI changes)

• Mobile-first layout verified — N/A: no UI changes.
• Accessibility checks completed — N/A: no UI changes.
• Shared UI components used or exception documented — N/A: no UI changes.
• Playwright visual audit run locally — N/A: no UI changes.
• Desktop and mobile screenshots for every changed UI surface are posted in a PR comment and linked below — N/A: no UI changes.
• Agent/human reviewed the posted screenshots for quality control and found no visual issues, or fixed/documented every issue found — N/A: no UI changes.

UI Screenshot Evidence

N/A: no UI changes.

End-to-End Verification (Required for multi-component changes)

• Data flow traced from user input to final outcome with code path citations (see .claude/rules/10-e2e-verification.md)
• Capability test exercises the complete happy path across system boundaries
• All spec/doc assumptions about existing behavior verified against code (not just "read the code")
• If any gap exists between automated test coverage and full E2E, manual verification steps documented below

Data Flow Trace

• .gitignore: state is visible to Git's untracked-file collection.
• VM standalone capture (session_snapshot_wip.go) and container capture (session_snapshot_container_wip.go) use a temporary index and git add -A; restore materializes the worktree then restores the saved original index.
• check-runtime-state-files.ts: rejects root/nested runtime state remaining in the index; corrective staged deletions are allowed.
• package.json exposes the guard; check:fast and blocking CI lint both run it.

Untested Gaps

No live SAM sleep/R2 round trip; neither runtime implementation changed. Ordinary successful snapshots can preserve these files, while existing size budgets and degraded/fallback outcomes may still lose local state. The PR body remains the durable release/review record.

Post-Mortem (Required for bug fix PRs)

What broke

A parent workflow lost .workflow-state.md after sleep/recovery/runtime replacement, so it missed the visible final coordination summary even though child tasks completed successfully.

Root cause

.workflow-state.md was gitignored. That made sense for preventing commits, but it also meant snapshot behavior that excludes ignored files could omit the workflow state.

Class of bug

Runtime state durability mismatch: a file needed across sleep/recovery was treated as ordinary ignored scratch state.

Why it wasn't caught

The workflow guidance treated .workflow-state.md as durable enough for compaction, but did not account for snapshot exclusion of gitignored files.

Process fix included in this PR

• .gitignore comments now document that runtime workflow state is snapshot-visible.
• scripts/quality/check-runtime-state-files.ts prevents those files from being committed.
• check:fast runs the guard.

Post-mortem file

This PR is the post-mortem artifact for the observed parent workflow failure in task 01M4394VSQVE1XKVCW6DVM50Q3.

Specialist Review Evidence (Required for agent-authored PRs)

• All local reviewers completed and all findings addressed before readiness.

Reviewer	Status	Outcome
go-specialist / snapshot runtime contract (local snapshot_review)	PASS	Both runtimes capture using a temporary index plus git add -A, and restore the original index independently. Removing ignore entries preserves normal-sized untracked workflow state. No deployed runtime implementation changes.
constitution-validator (local snapshot_review)	ADDRESSED	Absolute Git default with SAM_GIT_BINARY override preserves portability and removes inherited PATH lookup. Relative overrides fail closed. No deployment-specific limits, URLs, or identifiers added.
security-auditor / constitution-validator / doc-sync-validator (local git_execution_security)	PASS	Independently reviewed S4036 fix, absolute-path validation, override and PATH-shadow tests, and developer documentation on2026-10-07. No blockers.
task-completion-validator (local completion_docs_tests)	PASS	All implementation research/checklist findings map to changes and verification; downstream release gates remain tracked separately.
doc-sync-validator (local completion_docs_tests)	ADDRESSED	Updated seven workflow instruction sources that incorrectly described state as gitignored.
test-engineer (local completion_docs_tests)	PASS	Independently ran two focused suites, 13 tests passed. Real Git covers tree capture/materialization, preserved index, root/nested tracking rejection, staged deletion recovery, and Git failure.

Original independent reviews covered the full PR diff on2026-10-06; security/constitution/docs follow-up covered the final executable-selection fix on2026-10-07. No blocking findings remain.

CodeRabbit Review Evidence (Required for agent-authored PRs)

• CodeRabbit requested after local review and final CI passed; staging N/A.
• Waited about 15 minutes: 2026-10-06 18:19Z–18:34Z.
• No CodeRabbit review arrived; the quota-limit outcome is recorded below.

CodeRabbit Notes

Local review and final CI passed; PR is ready. Requested CodeRabbit once through coderabbit-review at 2026-10-06 18:19Z after final CI passed. Trusted workflow 37510365548 succeeded and posted the command as the maintainer. CodeRabbit replied with “Review rate limited” and “Review limit reached” (next included review in 37 minutes). No review/findings arrived. Completed the required ~15-minute observation window at 18:34Z. No review arrived, no review threads/findings exist, and no re-trigger was sent. After the final fix push, observed incremental review evidence from2026-10-07 08:24Z–08:41Z; no review arrived and the status reports automatic reviews disabled. No findings exist and no feedback is waived.

Exceptions

None. Staging is unnecessary for this repository-only change under the user’s explicit task condition. Final CI and local specialist review are green. CodeRabbit request/wait is complete with a quota-limit/no-review result under the best-effort policy. Final-head Sonar passed. No waiver requested.

Agent Preflight (Required)

• Preflight completed before code changes

Classification

• external-api-change
• cross-component-change
• business-logic-change
• public-surface-change
• docs-sync-change
• security-sensitive-change
• ui-change
• infra-change

External References

N/A: no external API behavior.

Codebase Impact Analysis

• .gitignore: runtime workflow state files are no longer ignored so SAM snapshots can include them.
• scripts/quality/check-runtime-state-files.ts: new commit guard.
• package.json and .github/workflows/ci.yml: guard script and matching local/CI integration.
• Quality regressions and workflow instructions: protect and document the state contract.

Documentation & Specs

Inline .gitignore comments and both Codex/Claude workflow instructions document local-only, snapshot-visible state. No public runtime interface changed.

Constitution & Risk Check

Checked Principle XI / hardcoded values risk: no environment-specific values added. Main risk is accidental commit of runtime state; mitigated by the new quality guard.

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

• Configuration used: Repository: raphaeltm/simple-agent-manager/.coderabbit.yaml
• Review profile: CHILL
• Plan: Advanced
• Run ID: c6197cdd-e2d1-420d-90ca-e9ec35fe64a7

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

• Autopilot · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[codspeed]

Merging this PR will not alter performance

✅ 6 untouched benchmarks

---

_{Comparing sam/whats-health-system-moment-tssfzg (d67f1dd) with main (6e9ce25)¹}

Footnotes

1. No successful run was found on main (2de93fe) during the generation of this report, so 6e9ce25 was used instead as the comparison base. There might be some changes unrelated to this pull request in this report. ↩

[raphaeltm]

@coderabbitai review

[coderabbitai]

⚠️ Action not completed

Review rate limited.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud