Record working-set memory in resource history

[simple-agent-manager]

Summary

• Record cgroup v2 working-set memory as memory.current - inactive_file, clamped at zero, while retaining the cache-inclusive current and kernel peak values for historical comparison.
• Carry nullable working-set samples and mean/peak summaries through VM-agent upload, D1/R2 storage, HTTP and MCP reads, and the session resource drawer. Older agents remain unknown (null/—) and cannot overwrite known aggregates with zero.
• Label working set as Memory needed and raw current memory as Total RAM (incl. cache), with contiguous chart segments that preserve gaps in unknown legacy samples.

A cache-heavy staging workload demonstrated the sizing impact: 427 MB working-set peak versus 1.2 GB cache-inclusive sampled peak.

Validation

• pnpm lint (API and web; web has 3 existing warnings and 0 errors)
• pnpm typecheck (API and web)
• Focused tests: 16/16 API unit/integration tests, including HTTP → D1/R2 → read and both mixed old/new-agent upload orders
• VM-agent go test -race ./internal/resourcehistory, go vet, and gofmt passed before the final main rebase; the rebase did not change Go source
• pnpm quality:migration-safety — 205 relationships, 0 violations
• Full build/lint/typecheck gates passed locally; isolated infrastructure suite passed 68/68. Concurrent full-test fanout had unrelated infrastructure import timeouts; PR CI is the authoritative full run.
• Additional validation: 10/10 Playwright drawer scenarios at 375×667 and 1280×800, including populated, legacy unknown, empty, error, and 30-chunk states
• Candidate-selection budget: N/A; no sweep/cron/alarm candidate query changed

Staging Verification (REQUIRED for all code changes — merge-blocking)

• Staging deployment green — Deploy Staging run 36550714488 passed for working-set commit 8f07e3712
• Live app verified via Playwright — authenticated staging session exercised the resource drawer and core routes
• Existing workflows confirmed working — dashboard, projects, and settings loaded without an error boundary
• New feature/fix verified on staging — a fresh VM uploaded populated working-set samples and the deployed drawer rendered them
• Infrastructure verification completed — fresh node heartbeat, workspace access, final flush, and cleanup verified
• Mobile and desktop verification notes added for UI changes

Staging Verification Evidence

Fresh staging node 01M3P9M7KHACV1420HJEKEV82P ran a 128 MiB file-cache workload. The final flush retained 53 samples, including 24 known working-set values; every known value satisfied 0 <= working set <= memory.current. Mean working set was 293,991,082 bytes (280 MB), peak working set was 447,438,848 bytes (427 MB), and cache-inclusive current peak was 1,293,877,248 bytes (1.2 GB). The test session, workspace, and node were deleted; the staging node list was empty at handoff.

Evidence: captured summary, verification notes.

The final rebase integrated merged attribution PR #2181 and updated its SQLite fixtures; the working-set collector source verified on staging did not change.

UI Compliance Checklist (Required for UI changes)

• Mobile-first layout verified
• Accessibility checks completed
• Shared UI components used
• Playwright visual audit run locally across normal, legacy unknown, empty, error, and many-chunk states at mobile and desktop sizes; no horizontal overflow
• Desktop and mobile screenshots for every changed UI surface are posted in a PR comment and linked below
• Screenshots reviewed for layout, overflow, clipping, readability, and responsive behavior; no issues found

UI Screenshot Evidence

Surface: Session resource history drawer

• Desktop evidence: Playwright staging desktop capture
• Mobile evidence: Playwright staging mobile capture
• Screenshots were taken with Playwright.
• Mock/stress data used: populated, old-agent unknown, empty, error, and 30-chunk histories; staging captures use the real fresh-VM summary
• Screenshot quality review: desktop and mobile captures reviewed; labels, values, wrapping, spacing, and close control are readable with no clipping or overflow

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

• Data flow traced from collector to displayed result
• Capability test exercises the complete happy path across HTTP, D1, R2, and read route
• Existing behavior and nullable compatibility verified against code and mixed-version tests
• Manual staging verification covers the VM-agent and live UI boundary

Data Flow Trace

1. packages/vm-agent/internal/resourcehistory/collector.go: readCgroupCounters reads memory.current, memory.peak, and strict inactive_file; summarize emits known-only mean/peak/count.
2. apps/api/src/services/workspace-resource-history.ts: storeWorkspaceResourceChunk validates upload metadata, stores the compressed chunk in R2, and aggregates nullable summary fields in D1 without absence overwrites.
3. The same service's getWorkspaceResourceHistory returns nullable summary fields and downsampled detail samples through project HTTP routes.
4. apps/api/src/routes/mcp/session-tools.ts and apps/api/src/durable-objects/sam-session/tools/get-resource-history.ts expose the same result to both MCP implementations.
5. apps/web/src/lib/api/sessions.ts types the response; SessionResourceHistoryDrawer.tsx renders working set as memory needed and current memory as cache-inclusive total.

Untested Gaps

N/A: automated tests cover each storage/read boundary; fresh-VM staging covers collector upload and the deployed UI.

Post-Mortem (Required for bug fix PRs)

What broke

Session RAM peaks treated reclaimable page cache as required memory, so file-heavy tasks appeared to need much larger VMs.

Root cause

The original resource-history implementation recorded only cgroup memory.current and memory.peak, both of which include reclaimable cache; it had no working-set signal.

Class of bug

Resource-accounting semantic mismatch between an observable kernel total and the sizing value consumers need.

Why it wasn't caught

Collector fixtures and end-to-end tests did not distinguish inactive file cache from non-reclaimable memory.

Process fix included in this PR

Realistic memory.stat fixtures, mixed-version aggregation tests, an HTTP/D1/R2 vertical slice, legacy UI cases, and fresh-VM cache-heavy staging evidence now enforce the distinction. Existing rule 73 already defines absence semantics, so no new standing rule was needed.

Post-mortem file

Task and findings

Specialist Review Evidence (Required for agent-authored PRs)

• All local reviewers completed and findings addressed before merge
• If any reviewer did NOT complete: needs-human-review label added and merge deferred to human — N/A; every reviewer completed

Reviewer	Status	Outcome
go-specialist	PASS	Collector/parser, optional JSON fields, and rollout compatibility passed
cloudflare-specialist	PASS	Nullable migration, D1 aggregation, routes, and rollback compatibility passed
ui-ux-specialist	ADDRESSED	Unknown-value chart gaps fixed; 10/10 responsive audit passed
test-engineer	ADDRESSED	Added HTTP vertical slice and both old/new upload orders
doc-sync-validator	PASS	Guide, API reference, and screenshots aligned
constitution-validator	PASS	No hardcoded-value or constitution findings
task-completion-validator	PASS	All acceptance criteria and staging evidence verified

CodeRabbit Review Evidence (Required for agent-authored PRs)

• coderabbit-review label applied after local review, staging, and CI gates passed
• All CodeRabbit findings implemented or explicitly reviewed and closed/resolved
• Incremental CodeRabbit review completed after final pushed fixes, or no fixes were needed
• Latest CodeRabbit review has no unresolved feedback

CodeRabbit Notes

The visible green CodeRabbit status is not usable review evidence. CodeRabbit edited its existing summary at 2026-09-29 12:40:54 UTC with the exact result: “Review skipped — Bot user detected” (run ID 0d55d980-fca5-42ac-bf2e-722c245b7d5c). GitHub shows zero submitted CodeRabbit reviews and zero review threads for the PR.

The repository-compliant trusted workflow run 36567341700 succeeded from main and posted an owner-authored @coderabbitai review command at 2026-09-29 12:19:48 UTC. CodeRabbit nevertheless classified that request as bot-authored and skipped it. Earlier owner-authored requests at 10:48 and 11:27 UTC also produced no review. This is the vendor-provided reason; no additional human-only or permissions explanation is inferred.

Per the repository /do merge gate, the trusted request did not produce usable review evidence. The needs-human-review label is applied and merge is deferred pending a PR-specific waiver or a real CodeRabbit review. The request is not being repeated again without a materially new ready state or a passed rate-limit window.

Exceptions (If any)

• Scope: none
• Rationale: N/A
• Expiration: N/A

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

No external API was changed. The implementation follows the established cAdvisor/kubelet working-set definition named in the task and repository guidance.

Codebase Impact Analysis

packages/vm-agent collection and upload schema; apps/api D1/R2 storage, HTTP, and MCP reads; apps/web types and drawer; apps/www guide/API docs; migration 0176.

Documentation & Specs

Updated apps/www/src/content/docs/docs/guides/session-resources.md, apps/www/src/content/docs/docs/reference/api.md, their screenshots, and the active task/evidence record.

Constitution & Risk Check

Checked nullable-field preservation, additive migration safety, bounded retention, no hardcoded configuration, privacy of retained payloads, and old/new agent rollout compatibility. The internal known-sample count prevents old-agent chunks from biasing the working-set mean.

[coderabbitai]

Important

Review skipped

Bot user detected.

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: 0d55d980-fca5-42ac-bf2e-722c245b7d5c

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

---

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.}

[simple-agent-manager]

UI evidence — Session resource history drawer

Exact deployed Pages bundle rendering the captured fresh-VM staging summary.

Desktop (1280×800)

Mobile (375×667)

Reviewed for hierarchy, wrapping, overflow, clipping, readability, and responsive behavior. No visual issues found. The displayed 427 MB peak, 280 MB mean, 1.2 GB cache-inclusive total, and 53 samples match the real-VM captured summary.

[raphaeltm]

@coderabbitai review

[sonarqubecloud]

Quality Gate passed

Issues
2 New issues
0 Accepted issues

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

See analysis details on SonarQube Cloud

[raphaeltm]

@coderabbitai review

[raphaeltm]

@coderabbitai review