[Node C] Sandbox, Infrastructure & Launch — Full 6-Month Track (B. Kataria)

[mohityadav8]

Owner: B. Kataria · Core Contributor / Infrastructure Lead
Hardware: RTX 4060 · 8GB VRAM (CPU-only workload — full VRAM reserved for Docker)
Scope: Docker sandboxing, git checkpoint/rollback engine, diff tooling, hybrid retrieval assembly, dashboard state management, CI/launch
Duration: 6 Phases / ~26 weeks
Labels: node-c, infrastructure, epic, sandbox, launch

---

🎯 Epic Goal

Own the execution environment the agent actually touches: the ephemeral Docker sandbox, the git-based checkpoint/rollback system that makes the Reaper Protocol's "undo and retry differently" possible, and the safety guardrails that stop the agent from running destructive commands. In later phases, own state management on the dashboard and the entire public launch (docs site, CI, community setup, launch posts).

📅 Timeline (6 Months)

gantt
    title Node C — B. Kataria — 6 Month Roadmap
    dateFormat  YYYY-MM-DD
    axisFormat  %b
    section Phase I - Single Node
    Docker Sandbox + Safety Guards         :p1, 2026-07-06, 21d
    section Phase II - Reaper Protocol
    Git Checkpoint + Rollback Engine       :p2, after p1, 21d
    section Phase III - AST Retrieval
    Hybrid Retrieval + Context Assembly    :p3, after p2, 21d
    section Phase IV - Three-Node Mesh
    gRPC SandboxService + Security         :p4, after p3, 21d
    section Phase V - War Room Dashboard
    Zustand State + Run Controls           :p5, after p4, 21d
    section Phase VI - Benchmark & Ship
    CI, Docs Site, Community, Launch       :p6, after p5, 21d

Loading

🧭 Definition of Done (Epic-level)

• All 6 phase demo milestones below are recorded and linked in this issue
• Sandbox never allows a destructive command to touch the host filesystem or network
• Rollback/checkpoint system never leaves a corrupted or partially-applied workspace
• Public docs site live, CONTRIBUTING.md published, launch posts drafted and reviewed

---

🟦 PHASE I — Single-Node Agent Loop

Demo Milestone: Record the Docker logs showing clean spin-up, execution, and teardown.

• 01. Write the base Dockerfile — Python 3.11-slim, pinned system deps, no root user, no host network access
  • Acceptance: docker run as non-root confirmed; container cannot reach the host network by default
• 02. Build SandboxManager — create container, mount repo slice, exec commands, capture stdout/stderr separately
  • Acceptance: stdout and stderr never interleaved/lost, both captured with correct exit codes
• 03. Implement command safety guard — block rm -rf /, chown, chmod 777, stray curl; log blocked attempts
  • Acceptance: a deny-list + pattern test suite covering at least 15 known-dangerous command patterns, all blocked with a logged reason
• 04. Build ResultParser — structured pass/fail/error signal from pytest/jest stdout
  • Acceptance: correctly parses both pytest and jest output formats into one common structured result shape
• 05. Implement container health check loop — confirm sandbox is live before routing commands to it
  • Acceptance: a not-yet-ready container never receives a command (race condition test included)
• 06. Build volume mount controller — mount only the relevant subdirectory, never the entire host filesystem
  • Acceptance: attempt to mount / or a parent directory outside the repo is explicitly rejected
• 07. Implement container teardown — stop, remove, prune volumes on success, failure, or crash
  • Acceptance: no orphaned containers/volumes left behind after 20 consecutive test runs (docker ps -a verified clean)
• 08. Build environment variable injection — pass API keys/config into the container without leaking to host logs
  • Acceptance: secrets never appear in plaintext in docker inspect output or container logs
• 09. Integration test — mount a toy repo, run pytest, assert ResultParser returns the right structure
  • Acceptance: test covers both a passing and a failing toy repo scenario
• 10. Phase I demo — record Docker logs showing clean spin-up, execution, and teardown
  • Acceptance: video/log excerpt shows full container lifecycle with timestamps

---

🟥 PHASE II — The Reaper Protocol

Demo Milestone: Show the git log with per-attempt branches and rollback history.

• 01. Build WorkspaceCheckpointer — git branch per attempt (hydra/attempt-001, etc.), no raw --hard resets
  • Acceptance: branch creation is atomic; a crash mid-checkpoint never leaves an ambiguous git state
• 02. Build RollbackEngine — given a branch name, reset the working tree to that branch's HEAD cleanly
  • Acceptance: rollback verified byte-identical to the target branch state via checksum comparison
• 03. Build DiffCalculator — fast diff between two directory snapshots without calling git (for in-flight comparison)
  • Acceptance: benchmark shows this is faster than shelling out to git diff for the Reaper's real-time scoring needs
• 04. Build BranchCleaner — prune dead hydra/attempt-* branches after success, keep them on failure for audit
  • Acceptance: successful run leaves exactly one clean branch; failed run retains full audit trail
• 05. Implement TransactionWrapper — wrap all file writes in a commit-or-rollback unit; partial writes never leave a corrupted state
  • Acceptance: killing the process mid-write and restarting never leaves a half-written file (tested via fault injection)
• 06. Build sandbox reset on rollback — container torn down and re-spun from the checkpoint branch state
  • Acceptance: reset is verified to fully clear any stray processes/state from the previous attempt
• 07. Write CheckpointMetadata — record files changed, tests run, exit code at each checkpoint
  • Acceptance: metadata queryable and matches what's shown in the PostMortemReport (Y. Jangra's Phase II task 09)
• 08. Integration test — inject a bug requiring root-cause 2 files upstream; assert Reaper fires and final answer is correct
  • Acceptance: this is the canonical end-to-end Reaper test, run in CI on every PR to the reaper module
• 09. Implement filesystem-level cleanup between rollbacks — stale .pyc, __pycache__, node_modules/.cache removed automatically
  • Acceptance: verified no stale bytecode causes a false-pass/false-fail on the next attempt
• 10. Phase II demo — show the git log with per-attempt branches and rollback history
  • Acceptance: git log --graph --all output captured and linked in this issue

---

🟩 PHASE III — AST Graph Retrieval

Demo Milestone: Publish the recall comparison table — flat embeddings vs. graph walk, on 20 real bugs.

• 01. Build HybridSearchEngine — cosine similarity (pgvector) + BM25 keyword match + graph-neighbor expansion
  • Acceptance: each of the 3 signals independently unit-tested, then combined and ranked
• 02. Implement ParentChildExpander — when a function chunk matches, pull in its containing class and the file's import block
  • Acceptance: verified the model receives enough surrounding context to understand the match without excess noise
• 03. Build GraphHopRetriever — given a seed node, walk import/call graph up to depth N, collect reachable nodes
  • Acceptance: depth N configurable; test confirms depth-2 correctly finds the README's "3 hops upstream" example bug
• 04. Implement StructuralRanker — weight nodes higher if imported by many other files in the repo
  • Acceptance: ranking demonstrably surfaces "hub" files (e.g. shared schema/config) above leaf files, all else equal
• 05. Build ArtifactFilter — skip node_modules/, venv/, dist/, *.lock, *.pyc, __pycache__/ at index time
  • Acceptance: indexing a repo with these directories present shows zero wasted embedding calls on filtered paths
• 06. Build ContextAssembler — takes ranked CodeChunks, orders them logically, formats into a clean prompt block
  • Acceptance: output format is stable/parseable and reviewed for readability by a human, not just by the model
• 07. Build TokenBudgetConstraint — trim retrieved context to fit the model's context window without cutting mid-function
  • Acceptance: trimming always cuts at a function/class boundary, verified via AST-boundary-aware truncation tests
• 08. Build RelevanceFeedbackLoop — after a successful run, upweight nodes that appeared in the final fix for future similar-error queries
  • Acceptance: measurable ranking shift demonstrated on a repeat of the same bug category
• 09. Write RetrievalComparisonTest — same 20 bugs, flat-embedding retrieval vs. graph-walk retrieval, compare recall
  • Acceptance: results file committed, matches the format used in M. Yadav's RetrievalEval harness
• 10. Phase III demo — publish the recall comparison table on 20 real bugs
  • Acceptance: table committed to /benchmarks/ and linked in this issue

---

🟨 PHASE IV — Three-Node Mesh

Demo Milestone: Show the teardown — all three nodes clean up gracefully after the task completes.

• 01. Wrap Docker sandbox as a gRPC SandboxService server on Node C
  • Acceptance: implements the .proto contract exactly as defined by M. Yadav's track, no ad-hoc extensions
• 02. Build SecureTransfer — before sending a repo slice to Node C, tar only the relevant subdirectory, never the whole repo
  • Acceptance: verified a multi-GB repo only transfers the actually-needed slice, measured in bytes over the wire
• 03. Build the sandbox gRPC handler — receive a repo slice, materialize in a temp directory, execute, return structured results
  • Acceptance: temp directory always cleaned up post-execution, even on handler crash
• 04. Add basic auth to the gRPC server — mutual TLS + pre-shared service token; no untokened LAN device can connect
  • Acceptance: connection attempt without the token is rejected and logged as a security event
• 05. Implement sandbox isolation hardening — no outbound network from containers, cgroup limits on CPU/RAM
  • Acceptance: a container attempting an outbound network call is verified blocked at the network layer, not just "usually doesn't happen"
• 06. Build ContainerPooling — keep N warm empty containers ready to accept a job without cold-start overhead
  • Acceptance: measured cold-start vs. warm-pool latency difference documented
• 07. Build SandboxTelemetry — emit container CPU, RAM, disk I/O back to supervisor's ResourceMatrix
  • Acceptance: telemetry feed matches the schema expected by M. Yadav's ResourceMatrix without translation
• 08. Integration test — kill Node C mid-test, confirm the sandbox job is retried on restart
  • Acceptance: retry doesn't duplicate side effects (e.g. doesn't run destructive test twice with compounding state)
• 09. Document the exact WiFi setup (channel, band, AP distance) used in the network load test
  • Acceptance: documented for reproducibility, included in Phase IV network load test report (M. Yadav's track)
• 10. Phase IV demo — show the teardown: all three nodes clean up gracefully after the task completes
  • Acceptance: recording shows docker ps -a, process list, and network connections all clean post-run

---

🟪 PHASE V — War Room Dashboard

Demo Milestone: Show the human override in action — type a correction mid-run, watch the agent change direction.

• 01. Build the Zustand store — normalize incoming WebSocket events into currentRun, nodes, genealogy, logs slices
  • Acceptance: store shape documented; no component directly mutates state outside defined actions
• 02. Build WebSocketClient — auto-reconnects on drop, shows DISCONNECTED banner, resumes stream on reconnect
  • Acceptance: simulated network drop test confirms clean reconnect without duplicate/missing events
• 03. Build RunControlPanel — Pause → sends PAUSE; Abort → sends ABORT; Resume → sends RESUME to supervisor
  • Acceptance: each control verified to actually change agent behavior mid-run, not just update UI state
• 04. Build HumanGateModal — on AWAITING_APPROVAL, UI blocks and shows the proposed change for human sign-off
  • Acceptance: agent execution genuinely halts server-side until approval is received, not just visually blocked client-side
• 05. Build OverridePromptBox — text field injecting a human instruction into the current REFLECT step mid-run
  • Acceptance: injected instruction is verifiably included in the next model prompt (visible in logs)
• 06. Build SessionReplayViewer — for any past run, step through events one at a time like a video scrubber
  • Acceptance: replay is deterministic — same run replayed twice shows identical event sequence and timing display
• 07. Build AlertSystem — toast notifications for REAPER_FIRED, NODE_LOST, TEST_PASSED, RUN_COMPLETE, distinct style per type
  • Acceptance: all 4+ toast types visually distinguishable at a glance (color + icon, not just text)
• 08. Build ThemeToggle — light/dark mode without a page reload
  • Acceptance: preference persists across a session (in-memory state acceptable per no-localStorage constraint in artifacts, but real app can use it)
• 09. Write BundleAudit — next build output must stay under 300kB JS per route, enforced via CI check
  • Acceptance: CI fails the build if the budget is exceeded, not just a warning
• 10. Phase V demo — show the human override in action, type a correction mid-run, watch the agent change direction
  • Acceptance: recorded clip showing the override text box, the injected instruction, and the resulting behavior change

---

🟧 PHASE VI — Benchmark, Harden, Ship

Demo Milestone: Ship on Hacker News, r/LocalLLaMA, r/MachineLearning — 7:00 AM PST on a Tuesday.

• 01. Rewrite README intro — now that there's a real demo, replace every claim with a link to evidence
  • Acceptance: every bold claim in the README has a corresponding linked demo video or benchmark file
• 02. Record the final demo video — unscripted, 2–3 minutes, War Room Mode on a real bug, raw over produced
  • Acceptance: video is unedited/lightly edited, shows a real unseeded bug if possible
• 03. Write CONTRIBUTING.md — dev environment setup, running tests, PR standards, commit convention
  • Acceptance: a first-time contributor can follow it cold and get a passing local test run
• 04. Set up issue templates — Bug Report, Feature Request, Question, with enough structure for first-time contributors
  • Acceptance: templates tested by filing one real issue of each type
• 05. Set up GitHub Actions — lint-and-test.yml on every PR, benchmark-nightly.yml weekly on the 50-issue suite
  • Acceptance: both workflows green on the default branch before v0.1.0 tag
• 06. Build static documentation site — /docs via Docusaurus, hosted on GitHub Pages
  • Acceptance: site live at a public URL, includes architecture, getting-started, and model-selection docs
• 07. Draft the Hacker News launch post — lead with benchmark numbers and the Genealogy View, not the marketing pitch
  • Acceptance: draft reviewed by both other team members before posting
• 08. Draft the r/LocalLLaMA post — hardware requirements, model choices, honest expectations
  • Acceptance: explicitly states what HydraNet is NOT trying to be (per README's "What this project is not" section)
• 09. Final launch checklist — verify all links, demo videos, and benchmark files referenced in launch posts are live and correct
  • Acceptance: dry-run click-through of every link in both draft posts, zero 404s
• 10. Ship — post to Hacker News, r/LocalLLaMA, r/MachineLearning at 7:00 AM PST on a Tuesday
  • Acceptance: posts live, linked back to this issue for the post-mortem

---

🔗 Dependencies

• Phase II Reaper rollback engine is a hard blocker for M. Yadav's Phase II task 06 (ReaperHook) — rollback must exist before the hook can safely fire
• Phase III HybridSearchEngine depends on M. Yadav's pgvector schema (Node A Phase III task 02) being finalized first
• Phase IV gRPC SandboxService must conform exactly to the .proto contract owned by M. Yadav's track
• Phase VI launch is the final gate — depends on Y. Jangra's benchmark numbers (Node B Phase VI) being published first

⚠️ Risks

• Sandbox network isolation is a hard security requirement, not a nice-to-have — a single escape defeats the "safe to run locally" pitch; budget extra review time in Phase IV task 05
• Docker on WSL2 (likely environment for at least one teammate) has known quirks with networking/volumes — test explicitly, don't assume parity with native Linux Docker