feat: HTTPS proxy sidecar with SSL bump and upstream chaining

[thejoeejoee]

Enforce all container egress traffic through a managed HTTPS proxy with TLS interception (SSL bump). This provides a single enforcement point for traffic policy, with extension points for credential injection (#93) and PII masking (#94).

Problem

Currently, jailoc uses iptables rules in entrypoint.sh to restrict outbound traffic by destination IP/host. This has limitations:

1. No content inspection — can't inspect HTTPS payloads
2. DNS-based bypass — iptables rules resolve hostnames at setup time; DNS changes can bypass them
3. No HTTP-level policy — can't enforce per-domain HTTP method restrictions (e.g. allow GET but deny POST)
4. No traffic logging — no visibility into what the agent sends/receives

Goal

All container egress flows through a preconfigured Squid forward proxy with:

• SSL bump (TLS interception) via per-workspace ephemeral CA
• Domain + HTTP method allowlisting at the proxy level (replaces iptables host restrictions)
• Request/response logging (optional, for audit)
• Upstream chaining to a corporate/shared proxy via Squid cache_peer

Architecture: sidecar is always present

The sidecar proxy is always the agent's proxy. The agent always sees a simple HTTP_PROXY=http://proxy:8080. Upstream chaining is transparent to the agent.

Mode A: Direct egress (default)

┌─────────────────────────────────────────────────┐
│  Docker network (workspace)                      │
│                                                  │
│  ┌──────────┐    ┌──────────┐    ┌───────────┐  │
│  │ opencode │───▶│  squid   │───▶│ internet  │  │
│  │          │    │ (sidecar)│    │           │  │
│  └──────────┘    └──────────┘    └───────────┘  │
│       │                                          │
│       │          ┌─────────┐                     │
│       └─────────▶│  dind   │                     │
│                  └─────────┘                     │
└─────────────────────────────────────────────────┘

Squid does SSL bump, enforces domain + method allowlists, optionally logs — then forwards directly to the internet.

Mode B: Upstream chaining

The sidecar Squid chains to an external upstream proxy via cache_peer. The agent still only talks to the sidecar:

┌──────────────────────────────────────────────────────────────────┐
│  Docker network (workspace)                                      │
│                                                                  │
│  ┌──────────┐    ┌──────────┐    ┌───────────┐    ┌───────────┐ │
│  │ opencode │───▶│  squid   │───▶│ upstream  │───▶│ internet  │ │
│  │          │    │ (sidecar)│    │  proxy    │    │           │ │
│  └──────────┘    └──────────┘    └───────────┘    └───────────┘ │
│       │                                                          │
│       │          ┌─────────┐                                     │
│       └─────────▶│  dind   │                                     │
│                  └─────────┘                                     │
└──────────────────────────────────────────────────────────────────┘

Upstream chaining is a standard Squid feature (cache_peer). Auth to the upstream proxy is the upstream proxy's concern — not solved at the sidecar level.

Agent-facing env vars

HTTP_PROXY=http://proxy:8080
HTTPS_PROXY=http://proxy:8080
http_proxy=http://proxy:8080
https_proxy=http://proxy:8080
NO_PROXY=localhost,127.0.0.1,dind

All four proxy vars set (uppercase + lowercase). NO_PROXY includes dind so Docker-in-Docker traffic stays local.

Squid configuration concepts

SSL bump

Squid intercepts TLS connections using a jailoc-generated ephemeral CA:

http_port 8080 ssl-bump \
  cert=/etc/squid/ssl/ca.pem \
  key=/etc/squid/ssl/ca.key \
  generate-host-certificates=on \
  dynamic_cert_mem_cache_size=4MB

sslcrtd_program /usr/lib/squid/security_file_certgen -s /var/lib/squid/ssl_db -M 4MB

ssl_bump peek step1
ssl_bump bump all

Domain + HTTP method allowlisting

Proven pattern: ACL rules that combine destination domain with HTTP method restrictions.

# Domain allowlists
acl allowed_domains dstdomain .api.openai.com
acl allowed_domains dstdomain .api.anthropic.com
acl allowed_domains dstdomain .googleapis.com

# HTTP method restrictions
acl safe_methods method GET HEAD OPTIONS
acl write_methods method POST PUT PATCH DELETE

# Allow API domains (all methods)
http_access allow allowed_domains

# Default: deny everything else
http_access deny all

jailoc generates these ACLs from config.toml allowed_hosts at workspace start. More granular per-domain method restrictions can be added later.

Upstream chaining via cache_peer

# Chain all traffic to upstream proxy
cache_peer upstream-proxy.corp.example.com parent 3128 0 \
  no-query \
  default \
  name=upstream

# Force all requests through the upstream peer
never_direct allow all

This is standard Squid cache_peer configuration. The sidecar simply forwards everything to the upstream — no auth logic in the sidecar itself.

iptables enforcement

The opencode container's iptables rules must block direct outbound — only allow traffic to the sidecar proxy + dind. This prevents the agent from bypassing the proxy entirely.

Possible config

[defaults.proxy]
enabled = true
log_traffic = false                      # audit logging

# --- Upstream chaining (Mode B) ---
# upstream = "upstream-proxy.corp.example.com:3128"
# upstream_ca_cert = "/path/to/upstream-ca.pem"   # if upstream does its own SSL bump

[defaults.proxy.limits]
bandwidth = "10MB/s"
requests_per_minute = 300

Implementation notes

• Squid is the recommended proxy — battle-tested forward proxy with native SSL bump, cache_peer upstream chaining, and ACL system
• Ephemeral CA: jailoc generates per-workspace CA cert/key, injects into both Squid config and opencode trust store
• ACL generation: jailoc compiles allowed_hosts + allowed_networks from config.toml into Squid ACL includes at workspace start
• Container: squid-openssl package (Debian/Ubuntu) provides SSL bump support

Relationship to other issues

• feat: credential proxy — agent uses API keys without seeing them #93 — Credential proxy: future extension point — sidecar proxy is the natural place for credential injection
• feat: PII/secret masking in LLM traffic #94 — PII masking: future extension point — Squid supports ICAP for content filtering
• This issue is the transport layer that feat: credential proxy — agent uses API keys without seeing them #93 and feat: PII/secret masking in LLM traffic #94 can plug into later

OpenCode compatibility

OpenCode respects HTTP_PROXY/HTTPS_PROXY env vars (source). All outbound fetch() calls route through the proxy automatically.

[thejoeejoee]

Research: OpenCode ↔ proxy integration

Analysis of how a proxy sidecar (credential injection #93, PII masking #94, traffic enforcement #95) would integrate with OpenCode — the agent running inside jailoc containers.

Source: opencode-ai/opencode@c57c531 (Apr 17, 2026)

---

OpenCode LLM communication architecture

OpenCode is a TypeScript/Bun application that uses Vercel AI SDK with 20+ bundled provider adapters (@ai-sdk/anthropic, @ai-sdk/openai, @ai-sdk/google, etc.). All LLM HTTP requests go through a single fetch wrapper (provider.ts:1427-1464) — making proxy interception straightforward.

Key env vars for API keys: ANTHROPIC_API_KEY, OPENAI_API_KEY, GEMINI_API_KEY, GROQ_API_KEY, OPENROUTER_API_KEY, XAI_API_KEY, AZURE_OPENAI_API_KEY, GITLAB_TOKEN, AWS_*, etc.

Credentials storage: ~/.local/share/opencode/auth.json (when added via /connect command) or environment variables.

---

Three integration approaches (from easiest to most comprehensive)

1. baseURL override (config-level, no code changes)

Every provider supports a baseURL option in opencode.json:

// opencode.json mounted into the container
{
  "provider": {
    "anthropic": {
      "options": {
        "baseURL": "http://proxy:8080/v1"  // PII masking proxy
      }
    },
    "openai": {
      "options": {
        "baseURL": "http://proxy:8080/v1"
      }
    }
  }
}

How it works: OpenCode sends all LLM requests to the proxy instead of the real API. The proxy:

1. Receives the request with placeholder API key (jailoc-managed)
2. Scans request body for PII/secrets → replaces with placeholders
3. Injects the real API key from host config
4. Forwards to the actual provider endpoint
5. On response, reverses PII placeholders before returning to the agent

Pros: Zero changes to OpenCode, works with any provider, jailoc controls the config file.
Cons: Requires per-provider config; the proxy must route to the correct upstream based on path or header.

2. HTTP_PROXY / HTTPS_PROXY env vars (transparent, zero config)

OpenCode explicitly detects and respects standard proxy env vars:

HTTP_PROXY=http://proxy:8080
HTTPS_PROXY=http://proxy:8080

How it works: Bun's native fetch() routes all HTTPS traffic through the proxy. The proxy acts as a MITM:

1. Intercepts TLS connections using a per-workspace ephemeral CA (injected into the container's trust store)
2. Decrypts request → scans for PII/secrets → masks → injects real credentials → re-encrypts → forwards
3. On response, reverses PII placeholders

Pros: Completely transparent — works for all providers without any OpenCode config changes, catches ALL outbound HTTP (including MCP servers, tool calls, etc.).
Cons: Requires TLS interception (ephemeral CA), slightly more complex proxy setup.

3. Hybrid: baseURL for LLM + HTTPS_PROXY for everything else

Use baseURL for known LLM providers (avoids TLS interception for LLM traffic) and HTTPS_PROXY for catching any other outbound traffic that might leak credentials.

---

Compatibility with specific proxy candidates

Proxy	Integration method	Notes
CloakPipe (Rust)	baseURL override	OpenAI-compatible endpoint; needs one proxy instance per provider or path-based routing
PasteGuard (TS/Bun)	baseURL override	Native OpenAI + Anthropic support; proxy routes by provider path
mirage-proxy (Rust)	HTTPS_PROXY	Transparent MITM proxy; works with all providers automatically
LiteLLM + Presidio	baseURL override	Multi-provider routing built-in; single endpoint for all providers
LLM Guard (Python)	baseURL override	Input/output scanners; not reversible (can't unmask in responses)
AegisGate (Python)	baseURL override	PII + prompt injection + response sanitization
Custom Go proxy	Either	jailoc-native sidecar, maximum control

---

jailoc integration points

Currently, jailoc's compose template generates two containers (opencode + dind). The proxy would be a third sidecar container on the same Docker network:

1. proxy container: Runs the PII masking proxy, listens on :8080
2. OpenCode config: jailoc generates an opencode.json with baseURL pointing to http://proxy:8080/v1
3. Credential injection: Proxy reads real API keys from a mounted secrets file (never exposed to the opencode container)
4. PII masking: Proxy scans request/response bodies — replaces secrets/PII with reversible placeholders
5. Network enforcement: Existing iptables rules in entrypoint.sh already restrict outbound traffic; proxy container would be in the allow list

Env var flow:

# In the opencode container:
ANTHROPIC_API_KEY=jailoc-managed          # Placeholder — agent can't use this directly
OPENAI_API_KEY=jailoc-managed             # Placeholder
# (or no API key env vars at all — proxy handles auth)

# In the proxy container:
REAL_ANTHROPIC_API_KEY=sk-ant-...         # Mounted from host
REAL_OPENAI_API_KEY=sk-...               # Mounted from host

Config generation: jailoc already generates docker-compose.yml from a Go template (internal/compose/). Extending it to:

• Add a proxy service
• Generate opencode.json with baseURL overrides
• Mount a secrets config for the proxy

---

Recommendation

Start with approach 1 (baseURL override) — it's the simplest, requires no TLS interception, and works with most proxy candidates out of the box. The proxy sidecar routes requests to the correct upstream provider based on the URL path.

For maximum coverage (catching non-LLM traffic too), layer on approach 2 (HTTPS_PROXY) later with an ephemeral CA.

Top proxy candidate for jailoc: CloakPipe (Rust, MIT, 3.2ms latency, reversible masking, streaming support) or a custom Go proxy (native to the jailoc ecosystem, maximum control over credential injection + PII masking).

[thejoeejoee]

Application-layer policy enforcement via ICAP

The current design uses Squid ACLs for domain + HTTP method allowlisting. This covers the transport layer well, but can't inspect request/response bodies — which matters for credential injection (#93), PII masking (#94), and finer-grained API policy enforcement (e.g. restricting which GraphQL mutations an agent can call, not just which hosts it can reach).

ICAP (RFC 3507)

Squid natively supports ICAP — a protocol for delegating request/response inspection to an external service. The flow:

Agent → Squid (SSL bump, domain ACLs) → ICAP server → Squid → Internet

Squid sends intercepted HTTP traffic to the ICAP server, which can:

• REQMOD: inspect/modify the request before it leaves (credential injection, PII masking, API policy checks)
• RESPMOD: inspect/modify the response before the agent sees it (reverse PII placeholders)
• Block requests entirely (return 403)

Why this matters for jailoc

A lightweight Go ICAP sidecar alongside Squid gives us a clean separation:

Layer	Responsibility	Implementation
Transport	TLS termination, domain ACLs, upstream chaining, logging	Squid (config-only)
Application	Credential injection, PII masking, HTTP method+path policy, GraphQL field enforcement	Go ICAP server (custom logic)

Squid stays config-driven (no custom modules). All jailoc-specific logic lives in a Go service we control and can test independently.

What the ICAP server could enforce

HTTP-level policies — per-host method + path matching with glob patterns:

[defaults.proxy.policies."api.github.com"]
allow = [
  "GET /repos/*/pulls",         # read PRs
  "POST /repos/*/pulls",        # create PRs
  "GET /repos/*/issues/**",     # read issues + comments
]
# everything else to api.github.com → 403

Glob semantics: * matches a single path segment, ** matches the rest of the path.

GraphQL-aware enforcement — for GraphQL APIs (GitHub, GitLab), checking the operationName field is insufficient because it's client-controlled and spoofable. The ICAP server could parse the actual GraphQL query AST from the request body and check which fields/mutations are accessed:

[defaults.proxy.policies."api.github.com".graphql]
allow_mutations = ["createPullRequest", "addComment", "createIssue"]
# blocks: deleteRepository, transferRepository, etc.

This is defense-in-depth — even if the agent crafts a request with operationName: "createPullRequest" but the actual query contains deleteRepository, the AST check catches it.

Architecture

┌─────────────────────────────────────────────────────┐
│  Docker network (workspace)                          │
│                                                      │
│  ┌──────────┐    ┌──────────┐    ┌──────────┐       │
│  │ opencode │───▶│  squid   │───▶│ internet │       │
│  │          │    │ SSL bump │    │          │       │
│  └──────────┘    └────┬─────┘    └──────────┘       │
│                       │                              │
│                  ICAP (1344)                          │
│                       │                              │
│                  ┌────▼─────┐                        │
│                  │  policy  │                        │
│                  │ (Go svc) │                        │
│                  └──────────┘                        │
└─────────────────────────────────────────────────────┘

The policy sidecar is a single Go binary (~300 lines for ICAP + policy evaluation), running unprivileged, no volumes needed — it reads policy config from environment or a mounted TOML snippet generated by jailoc.

Squid ICAP config

icap_enable on
icap_service req_mod reqmod_precache icap://policy:1344/request
adaptation_access req_mod allow all

# optional: response modification for PII reversal
icap_service resp_mod respmod_precache icap://policy:1344/response
adaptation_access resp_mod allow all

Phasing

1. Phase 1 (this issue): Squid sidecar with domain + method ACLs — no ICAP yet
2. Phase 2 (feat: credential proxy — agent uses API keys without seeing them #93): Add ICAP server for credential injection (REQMOD — inject Authorization headers)
3. Phase 3 (feat: PII/secret masking in LLM traffic #94): Extend ICAP server with PII masking (REQMOD + RESPMOD)
4. Phase 4: HTTP path policies + GraphQL AST enforcement in the ICAP server

Each phase is independently useful. The ICAP server grows incrementally — same binary, new handlers.

Go ICAP libraries

• go-icap/icap — net/http-style API, lightweight
• Alternatively, ICAP is simple enough to implement from scratch (HTTP-like protocol with REQMOD/RESPMOD methods)

[thejoeejoee]

Configurable DinD (Docker-in-Docker) Toggle

TL;DR

Quick Summary: Add a [defaults.dind] / [workspaces.X.dind] config section with enabled = true (default), mirroring the existing proxy toggle pattern, so workspaces that don't need Docker can disable the DinD sidecar entirely.

Deliverables:

• DindConfig struct with Enabled *bool field in config package
• DindEnabled resolution in workspace package (default: true)
• DindEnabled field in ComposeParams and conditional template rendering
• Guarded entrypoint.sh (skip dind iptables rule when disabled)
• Guarded writeDindEntrypoint() call in up.go and add.go
• Dynamic NO_PROXY (exclude "dind" when dind disabled)
• Updated defaultConfigContent with commented [defaults.dind] section
• Full test coverage for all 4 proxy/dind combinations
• Documentation updates (reference, explanation, how-to)

Estimated Effort: Medium
Parallel Execution: YES - 3 waves
Critical Path: Task 1 → Task 3 → Task 4 → Task 2 → Task 5 → Task 7 → F1-F4

---

Context

Original Request

Add a configurable toggle to enable/disable the DinD (Docker-in-Docker) sidecar container per workspace, mirroring the existing proxy.enabled pattern.

Interview Summary

Key Discussions:

• Config structure: [defaults.dind] section with enabled = true, per-workspace override — mirrors proxy pattern exactly
• DinD disabled means no Docker access at all (intentional for non-Docker workspaces)
• All 4 combinations valid: proxy+dind, proxy-only, dind-only, neither — no restrictions

Research Findings:

• Proxy toggle pattern is well-established: ProxyConfig{Enabled *bool} → resolveProxyEnabled() → Resolved.ProxyEnabled → {{if .ProxyEnabled}} template guards → PROXY_ENABLED env var → entrypoint.sh conditional
• DinD is currently unconditional across 6 touch points: compose template (4 sections), entrypoint.sh (1 rule), up.go/add.go (2 write calls)
• defaultConfigContent is a Go string constant at config.go:20-65, NOT a separate file

Metis Review

Identified Gaps (addressed):

• entrypoint.sh line 27 will crash on DNS failure when dind container absent — guarded with DIND_ENABLED env var check
• All 29 existing compose tests will silently break (Go zero-value false for new DindEnabled field) — fix test baseline FIRST
• NO_PROXY hard-codes "dind" — made dynamic with template conditional
• writeDindEntrypoint() called unconditionally in both up.go and add.go — both guarded
• Empty volumes: YAML section when all dind volumes removed — template handles gracefully

---

Work Objectives

Core Objective

Make the DinD sidecar conditionally rendered based on a per-workspace config toggle, defaulting to enabled, following the exact same pattern as the existing proxy toggle.

Concrete Deliverables

• internal/config/config.go: DindConfig struct, fields on Defaults/Workspace, validation, defaultConfigContent update
• internal/workspace/workspace.go: DindEnabled on Resolved, resolveDindEnabled() function
• internal/compose/compose.go: DindEnabled field on ComposeParams
• internal/embed/assets/docker-compose.yml.tmpl: 4 conditional guards + dynamic NO_PROXY
• internal/embed/assets/entrypoint.sh: guarded dind iptables rule
• internal/cmd/up.go: guarded writeDindEntrypoint(), DindEnabled in ComposeParams
• internal/cmd/add.go: guarded writeDindEntrypoint(), DindEnabled in ComposeParams
• internal/compose/compose_test.go: baseline fix + new dind-specific tests
• internal/config/config_test.go: DindConfig parsing and validation tests
• internal/workspace/workspace_test.go: DindEnabled resolution tests
• docs/reference/configuration.md, docs/explanation/container-architecture.md, docs/how-to/workspace-configuration.md: updated

Definition of Done

• go build ./... succeeds
• go test ./... passes (all existing + new tests)
• go vet ./... clean
• golangci-lint run clean
• All 4 proxy/dind combinations produce valid docker-compose.yml
• DinD-disabled compose has NO dind service, NO dind volumes, NO DOCKER_* env vars
• DinD-enabled compose is identical to current output (backward compatible)

Must Have

• Default true for dind.enabled (backward compatible)
• Per-workspace override of defaults
• DindConfig struct with only Enabled *bool field
• DIND_ENABLED env var on opencode container (conditional)
• Dynamic NO_PROXY excluding "dind" when dind disabled
• Guarded entrypoint.sh dind iptables rule
• All existing tests pass unchanged (after baseline fix)

Must NOT Have (Guardrails)

• No changes to reservedEnvKeys — DOCKER_* stay reserved even when dind disabled
• No DindConfig fields beyond Enabled *bool
• No config_cmd.go changes
• No validation preventing both proxy and dind disabled simultaneously
• No dind-entrypoint.sh content changes
• No custom error types — use fmt.Errorf wrapping only
• No drive-by refactors of existing proxy code
• No changes to integration tests

---

Verification Strategy

ZERO HUMAN INTERVENTION - ALL verification is agent-executed. No exceptions.

Test Decision

• Infrastructure exists: YES (Go testing with go test, table-driven tests, custom assertContains helper)
• Automated tests: YES (Tests-after, matching project convention)
• Framework: go test with stdlib testing package + custom helpers (no testify)
• Pattern: Table-driven tests with t.Run, t.Parallel() where safe

QA Policy

Every task MUST include agent-executed QA scenarios.
Evidence saved to .sisyphus/evidence/task-{N}-{scenario-slug}.{ext}.

• Config/Workspace/Compose: Use Bash — go test ./internal/... with specific test names
• Template output: Use Bash — generate compose YAML via test, grep for expected/absent content
• Entrypoint: Use Bash — grep for conditional guard pattern in entrypoint.sh
• Full build: Use Bash — go build ./... && go test ./... && go vet ./... && golangci-lint run

---

Execution Strategy

Parallel Execution Waves

Wave 1 (Foundation — start immediately):
├── Task 1: Config struct + parsing + validation + defaults [quick]

Wave 2 (Core logic + test baseline — after Wave 1):
├── Task 3: Workspace resolution (DindEnabled) [quick]
├── Task 4: ComposeParams + up.go/add.go wiring [quick]
├── Task 2: Fix existing compose test baseline (add DindEnabled: true) [quick]
│   └── NOTE: T2 requires T4's ComposeParams.DindEnabled field to compile
├── Task 5: Compose template conditionals [deep]
├── Task 6: Entrypoint.sh dind guard [quick]

Wave 3 (Tests + Docs — after Wave 2):
├── Task 7: New dind-specific compose tests [deep]
├── Task 8: Config + workspace unit tests [quick]
├── Task 9: Documentation updates [writing]

Wave FINAL (After ALL tasks — 4 parallel reviews):
├── Task F1: Plan compliance audit (oracle)
├── Task F2: Code quality review (unspecified-high)
├── Task F3: Real manual QA (unspecified-high)
└── Task F4: Scope fidelity check (deep)
-> Present results -> Get explicit user okay

Dependency Matrix

Task	Depends On	Blocks	Wave
1	—	3, 4, 8	1
3	1	4, 8	2
4	1, 3	2, 5, 6, 7	2
2	4	5, 7	2
5	2, 4	7	2
6	4	7	2
7	2, 5, 6	—	3
8	1, 3	—	3
9	5, 6	—	3

Critical Path: Task 1 → Task 3 → Task 4 → Task 2 → Task 5 → Task 7 → F1-F4

Agent Dispatch Summary

• Wave 1: 1 task — T1 → quick
• Wave 2: 5 tasks — T3 → quick, T4 → quick, T2 → quick (after T4), T5 → deep, T6 → quick
• Wave 3: 3 tasks — T7 → deep, T8 → quick, T9 → writing
• FINAL: 4 tasks — F1 → oracle, F2 → unspecified-high, F3 → unspecified-high, F4 → deep

---

TODOs

• 1. Add DindConfig struct, wire into Config, update defaults

  What to do:

  • Create DindConfig struct in internal/config/config.go with single field Enabled *bool (TOML tag enabled), placed directly after ProxyConfig struct (after line 213)
  • Add Dind *DindConfig field to Defaults struct (after Proxy at line 186) with TOML tag dind
  • Add Dind *DindConfig field to Workspace struct (after Proxy at line 204) with TOML tag dind
  • Add validation in Validate(): mirror proxy validation pattern at lines 621-625 (defaults) and 725-729 (workspace). DindConfig only has Enabled *bool so validation is minimal — just ensure the section is parsed without error
  • Update defaultConfigContent constant (lines 20-65): add a commented [defaults.dind] section after the [defaults.proxy] section (after line 48), matching the proxy comment style:

    # [defaults.dind]
    # enabled = true
    

  Must NOT do:

  • Do NOT add any fields to DindConfig beyond Enabled *bool
  • Do NOT modify reservedEnvKeys
  • Do NOT modify ProxyConfig or any proxy-related code
  • Do NOT add custom error types

  Recommended Agent Profile:

  • Category: quick
    • Reason: Single-file change, straightforward struct addition mirroring existing pattern
  • Skills: [golang-code-style, golang-structs-interfaces]
    • golang-code-style: Ensures Go formatting and comment conventions match project style
    • golang-structs-interfaces: Struct design with proper TOML tags and pointer semantics
  • Skills Evaluated but Omitted:
    • golang-error-handling: Not needed — no new error types, just fmt.Errorf wrapping if any
    • golang-testing: Tests are a separate task (T8)

  Parallelization:

  • Can Run In Parallel: YES
  • Parallel Group: Wave 1 (with Task 2)
  • Blocks: Tasks 3, 4, 8
  • Blocked By: None (can start immediately)

  References:

  Pattern References (existing code to follow):

  • internal/config/config.go:208-213 — ProxyConfig struct definition: mirror this exact pattern for DindConfig (pointer bool field, TOML tags)
  • internal/config/config.go:186 — Proxy *ProxyConfig on Defaults: add Dind *DindConfig immediately after
  • internal/config/config.go:204 — Proxy *ProxyConfig on Workspace: add Dind *DindConfig immediately after
  • internal/config/config.go:621-625 — proxy validation in Validate() for defaults: mirror for dind
  • internal/config/config.go:725-729 — proxy validation in Validate() for workspace: mirror for dind
  • internal/config/config.go:43-48 — [defaults.proxy] commented section in defaultConfigContent: mirror for dind

  Acceptance Criteria:

  • go build ./... succeeds
  • go vet ./... clean
  • DindConfig struct exists with Enabled *bool field
  • Defaults.Dind and Workspace.Dind fields exist
  • defaultConfigContent contains commented [defaults.dind] section
  • TOML parsing works: enabled = true and enabled = false both parse correctly

  QA Scenarios:

  Scenario: DindConfig struct compiles and is accessible
    Tool: Bash
    Preconditions: Task 1 changes applied
    Steps:
      1. Run `go build ./...`
      2. Run `go vet ./...`
    Expected Result: Both exit 0 with no output
    Failure Indicators: Compilation errors mentioning DindConfig, Dind field, or type mismatches
    Evidence: .sisyphus/evidence/task-1-build-vet.txt
  
  Scenario: defaultConfigContent includes dind section
    Tool: Bash
    Preconditions: Task 1 changes applied
    Steps:
      1. Run `grep -n 'dind' internal/config/config.go | head -20`
      2. Verify output contains commented `[defaults.dind]` and `enabled = true` lines
    Expected Result: grep finds dind references in defaultConfigContent constant
    Failure Indicators: No grep matches, or dind section missing from defaultConfigContent
    Evidence: .sisyphus/evidence/task-1-default-config.txt
  

  Commit: YES (standalone — Commit 1)

  • Message: feat(config): add DindConfig struct with enabled toggle
  • Files: internal/config/config.go
  • Pre-commit: go build ./... && go vet ./...

• 2. Fix existing compose test baseline — add DindEnabled: true to all ComposeParams

  What to do:

  • CRITICAL: This task MUST complete before any template changes (Task 5). The Go zero-value for bool is false, so once DindEnabled is added to ComposeParams (Task 4), all existing tests that don't set it will get false — meaning dind sections vanish from their expected output.
  • Add DindEnabled: true to EVERY ComposeParams{} literal in internal/compose/compose_test.go (all 29 test functions)
  • This is a mechanical change: find every ComposeParams{ and add DindEnabled: true, to the field list
  • Do NOT change any expected outputs or assertions — all tests must pass identically before and after
  • This task depends on Task 4 (which adds the DindEnabled field to ComposeParams). Task 4 MUST complete first so the field exists for the test file to compile.

  Must NOT do:

  • Do NOT change any test assertions or expected values
  • Do NOT add new test functions (that's Task 7)
  • Do NOT modify compose.go (that's Task 4)
  • Do NOT refactor test structure or helpers

  Recommended Agent Profile:

  • Category: quick
    • Reason: Mechanical field addition across test file, no logic changes
  • Skills: [golang-testing]
    • golang-testing: Ensures test conventions are followed when modifying test params
  • Skills Evaluated but Omitted:
    • golang-code-style: Not needed for adding a single field to struct literals

  Parallelization:

  • Can Run In Parallel: NO (requires T4's ComposeParams.DindEnabled field to compile)
  • Parallel Group: Wave 2 (after Task 4)
  • Blocks: Tasks 5, 7
  • Blocked By: Task 4

  References:

  Pattern References (existing code to follow):

  • internal/compose/compose_test.go — All 29 test functions construct ComposeParams{}. Search for ComposeParams{ to find every instance.
  • internal/compose/compose_test.go:824 — TestComposeWithProxyEnabled: example of a test with ProxyEnabled: true set — mirror this pattern for DindEnabled: true
  • internal/compose/compose_test.go:863 — TestComposeWithProxyDisabled: example where proxy fields are deliberately omitted (defaults to false) — this test still needs DindEnabled: true

  Acceptance Criteria:

  • Every ComposeParams{ in compose_test.go has DindEnabled: true
  • No test assertions are modified
  • grep -c 'DindEnabled' internal/compose/compose_test.go returns count ≥ 29

  QA Scenarios:

  Scenario: All ComposeParams literals include DindEnabled
    Tool: Bash
    Preconditions: Task 2 changes applied
    Steps:
      1. Run `grep -c 'DindEnabled: true' internal/compose/compose_test.go`
      2. Run `grep -c 'ComposeParams{' internal/compose/compose_test.go`
      3. Compare: DindEnabled count should be ≥ ComposeParams count
    Expected Result: Every ComposeParams literal has DindEnabled: true
    Failure Indicators: DindEnabled count < ComposeParams count
    Evidence: .sisyphus/evidence/task-2-baseline-count.txt
  
  Scenario: No test assertions were modified
    Tool: Bash
    Preconditions: Task 2 changes applied, git diff available
    Steps:
      1. Run `git diff internal/compose/compose_test.go | grep '^[+-]' | grep -v 'DindEnabled' | grep -v '^[+-][+-][+-]' | grep -v '^[+-]$'`
      2. Verify the only non-DindEnabled changes are empty (whitespace) or none
    Expected Result: Only DindEnabled additions appear in diff
    Failure Indicators: Other lines modified beyond DindEnabled field additions
    Evidence: .sisyphus/evidence/task-2-diff-check.txt
  

  Commit: YES (groups with T3, T4 — Commit 2)

  • Message: feat(workspace): add DindEnabled resolution, wiring, and test baseline
  • Files: internal/compose/compose_test.go
  • Pre-commit: go test ./internal/compose/... ./internal/workspace/...

• 3. Add DindEnabled to Resolved struct and resolveDindEnabled() function

  What to do:

  • Add DindEnabled bool field to Resolved struct in internal/workspace/workspace.go (after ProxyEnabled at line 39)
  • Create resolveDindEnabled() function mirroring resolveProxyEnabled() (lines 304-313):
    • Extract *bool from cfg.Defaults.Dind.Enabled (nil-safe: check cfg.Defaults.Dind != nil)
    • Extract *bool from ws.Dind.Enabled (nil-safe: check ws.Dind != nil)
    • Call boolPtrWithDefault(defaultEnabled, wsEnabled, true) — default to true
  • Call resolveDindEnabled() in Resolve() function and assign to Resolved.DindEnabled (after ProxyEnabled assignment at line 129)

  Must NOT do:

  • Do NOT modify resolveProxyEnabled() or any proxy resolution logic
  • Do NOT add any fields beyond DindEnabled to Resolved
  • Do NOT change the boolPtrWithDefault helper function

  Recommended Agent Profile:

  • Category: quick
    • Reason: Single-file change, direct mirror of existing proxy pattern
  • Skills: [golang-code-style, golang-safety]
    • golang-code-style: Consistent naming and formatting
    • golang-safety: Nil-safe pointer dereferencing for *DindConfig and *bool
  • Skills Evaluated but Omitted:
    • golang-structs-interfaces: Simple field addition, not complex design

  Parallelization:

  • Can Run In Parallel: NO (depends on T1 for DindConfig type)
  • Parallel Group: Wave 2
  • Blocks: Tasks 4, 8
  • Blocked By: Task 1

  References:

  Pattern References (existing code to follow):

  • internal/workspace/workspace.go:304-313 — resolveProxyEnabled(): exact pattern to mirror for resolveDindEnabled()
  • internal/workspace/workspace.go:39 — ProxyEnabled bool on Resolved: add DindEnabled bool after this
  • internal/workspace/workspace.go:129 — ProxyEnabled: resolveProxyEnabled(...) in Resolve(): add DindEnabled assignment after
  • internal/workspace/workspace.go:274 — boolPtrWithDefault(): reuse this helper (do not duplicate)

  API/Type References:

  • internal/config/config.go — DindConfig struct (from Task 1): the source of Enabled *bool
  • internal/config/config.go — Defaults.Dind and Workspace.Dind fields (from Task 1)

  Acceptance Criteria:

  • go build ./... succeeds
  • Resolved.DindEnabled field exists
  • resolveDindEnabled() function exists and mirrors resolveProxyEnabled()
  • Default value is true when no config specified

  QA Scenarios:

  Scenario: DindEnabled resolution compiles
    Tool: Bash
    Preconditions: Tasks 1 and 3 applied
    Steps:
      1. Run `go build ./...`
      2. Run `go vet ./...`
    Expected Result: Both exit 0
    Failure Indicators: Compilation errors in workspace.go
    Evidence: .sisyphus/evidence/task-3-build.txt
  
  Scenario: resolveDindEnabled function exists with correct signature
    Tool: Bash
    Preconditions: Task 3 applied
    Steps:
      1. Run `grep -n 'func resolveDindEnabled' internal/workspace/workspace.go`
      2. Verify function exists and takes same parameters as resolveProxyEnabled
    Expected Result: Function found with correct signature
    Failure Indicators: No match or wrong parameter types
    Evidence: .sisyphus/evidence/task-3-func-check.txt
  

  Commit: YES (groups with T4, T2 — Commit 2)

  • Message: feat(workspace): add DindEnabled resolution, wiring, and test baseline
  • Files: internal/workspace/workspace.go
  • Pre-commit: go build ./... && go vet ./...

• 4. Add DindEnabled to ComposeParams and wire in up.go/add.go

  What to do:

  • Add DindEnabled bool field to ComposeParams struct in internal/compose/compose.go (after ProxyEnabled at line 31)
  • In internal/cmd/up.go:
    • Guard writeDindEntrypoint(cacheDir) call (line 139) with if ws.DindEnabled { ... }
    • Add DindEnabled: ws.DindEnabled to ComposeParams construction (after ProxyEnabled at line 216)
  • In internal/cmd/add.go:
    • Guard writeDindEntrypoint(cacheDir) call with if ws.DindEnabled { ... } (find the unconditional call)
    • Add DindEnabled: ws.DindEnabled to ComposeParams construction (lines 129-146)

  Must NOT do:

  • Do NOT modify any proxy-related wiring
  • Do NOT change writeEntrypoint() (only guard writeDindEntrypoint())
  • Do NOT add other fields to ComposeParams
  • Do NOT modify docker/docker.go

  Recommended Agent Profile:

  • Category: quick
    • Reason: 3 files, each with small mechanical additions mirroring proxy pattern
  • Skills: [golang-code-style]
    • golang-code-style: Consistent field ordering and conditional patterns
  • Skills Evaluated but Omitted:
    • golang-cli: Not CLI command structure changes, just wiring logic

  Parallelization:

  • Can Run In Parallel: NO (depends on T1 for DindConfig, T3 for Resolved.DindEnabled)
  • Parallel Group: Wave 2 (after T1, T3)
  • Blocks: Tasks 2, 5, 6, 7
  • Blocked By: Tasks 1, 3

  References:

  Pattern References (existing code to follow):

  • internal/compose/compose.go:31 — ProxyEnabled bool on ComposeParams: add DindEnabled bool after
  • internal/cmd/up.go:150 — if ws.ProxyEnabled { ... }: mirror this guard pattern for ws.DindEnabled around writeDindEntrypoint
  • internal/cmd/up.go:216 — ProxyEnabled: ws.ProxyEnabled in ComposeParams: add DindEnabled after
  • internal/cmd/up.go:139 — writeDindEntrypoint(cacheDir) unconditional call: wrap with if ws.DindEnabled
  • internal/cmd/add.go:129-146 — ComposeParams construction: add DindEnabled field

  API/Type References:

  • internal/workspace/workspace.go — Resolved.DindEnabled (from Task 3): the source value
  • internal/compose/compose.go — ComposeParams.DindEnabled (added in this task): consumed by template

  Acceptance Criteria:

  • go build ./... succeeds
  • ComposeParams.DindEnabled field exists
  • writeDindEntrypoint() is guarded by if ws.DindEnabled in both up.go and add.go
  • DindEnabled is passed to ComposeParams in both up.go and add.go

  QA Scenarios:

  Scenario: ComposeParams has DindEnabled field and builds clean
    Tool: Bash
    Preconditions: Tasks 1-4 applied
    Steps:
      1. Run `go build ./...`
      2. Run `grep 'DindEnabled' internal/compose/compose.go`
      3. Run `grep 'DindEnabled' internal/cmd/up.go`
      4. Run `grep 'DindEnabled' internal/cmd/add.go`
    Expected Result: Build succeeds, DindEnabled found in all 3 files
    Failure Indicators: Build failure or missing DindEnabled in any file
    Evidence: .sisyphus/evidence/task-4-wiring-check.txt
  
  Scenario: writeDindEntrypoint is conditional in both commands
    Tool: Bash
    Preconditions: Task 4 applied
    Steps:
      1. Run `grep -B1 'writeDindEntrypoint' internal/cmd/up.go`
      2. Run `grep -B1 'writeDindEntrypoint' internal/cmd/add.go`
      3. Verify both are preceded by `if ws.DindEnabled` guard
    Expected Result: Both calls wrapped in DindEnabled conditional
    Failure Indicators: writeDindEntrypoint called without guard
    Evidence: .sisyphus/evidence/task-4-guard-check.txt
  

  Commit: YES (groups with T3, T2 — Commit 2)

  • Message: feat(workspace): add DindEnabled resolution, wiring, and test baseline
  • Files: internal/compose/compose.go, internal/cmd/up.go, internal/cmd/add.go
  • Pre-commit: go build ./... && go vet ./...

• 5. Add conditional DinD rendering to compose template

  What to do:
  Apply 6 changes to internal/embed/assets/docker-compose.yml.tmpl:

  1. opencode env: Add DIND_ENABLED env var (conditional, like PROXY_ENABLED):
     • After the existing env vars section (around line 41), add:

       {{if .DindEnabled}}
           DIND_ENABLED: "true"
       {{end}}
       

  2. opencode env: Guard DOCKER_ env vars* (lines 42-45):
     • Wrap DOCKER_HOST, DOCKER_TLS_CERTDIR, DOCKER_CERT_PATH, DOCKER_TLS_VERIFY in {{if .DindEnabled}}...{{end}}
  3. opencode volumes: Guard dind-certs-client mount (line 26):
     • Wrap - dind-certs-client:/certs/client:ro in {{if .DindEnabled}}...{{end}}
  4. NO_PROXY: Make "dind" dynamic (line 57):
     • Change NO_PROXY=localhost,127.0.0.1,dind to NO_PROXY=localhost,127.0.0.1{{if .DindEnabled}},dind{{end}}
     • This ensures "dind" is only in NO_PROXY when dind is actually running
  5. Guard entire dind service block (lines 97-128):
     • Wrap the entire dind: service definition in {{if .DindEnabled}}...{{end}}
  6. Guard dind volume declarations (lines 159-161):
     • Wrap dind-certs-ca:, dind-certs-client:, dind-data: in {{if .DindEnabled}}...{{end}}
     • Edge case: Ensure no empty volumes: key remains when both dind volumes and all other conditional volumes are absent. The template already has unconditional volumes (like proxy CA), so the volumes: key should always have at least the network-related entries. Verify this.

  Also guard opencode depends_on for dind: If depends_on: dind exists in the template for the opencode service, wrap it in {{if .DindEnabled}}...{{end}}.

  Must NOT do:

  • Do NOT modify proxy-related template conditionals
  • Do NOT change indentation style or template formatting beyond the guards
  • Do NOT modify the dind service content (just wrap it)
  • Do NOT change entrypoint.sh (that's Task 6)

  Recommended Agent Profile:

  • Category: deep
    • Reason: Template changes across 6 locations with YAML validity concerns and edge cases
  • Skills: [golang-code-style]
    • golang-code-style: Go template syntax conventions
  • Skills Evaluated but Omitted:
    • golang-testing: Template testing is Task 7

  Parallelization:

  • Can Run In Parallel: YES (with Task 6, after T2 and T4)
  • Parallel Group: Wave 2
  • Blocks: Task 7
  • Blocked By: Tasks 2, 4

  References:

  Pattern References (existing code to follow):

  • internal/embed/assets/docker-compose.yml.tmpl:52-60 — {{if .ProxyEnabled}} guards on proxy env vars: exact pattern to mirror for dind guards
  • internal/embed/assets/docker-compose.yml.tmpl:85-96 — {{if .ProxyEnabled}} guards on proxy service block: mirror for dind service
  • internal/embed/assets/docker-compose.yml.tmpl:57 — NO_PROXY=localhost,127.0.0.1,dind: make dind portion dynamic
  • internal/embed/assets/docker-compose.yml.tmpl:42-45 — DOCKER_HOST/TLS env vars (unconditional): wrap in dind guard
  • internal/embed/assets/docker-compose.yml.tmpl:26 — dind-certs-client volume mount (unconditional): wrap in dind guard
  • internal/embed/assets/docker-compose.yml.tmpl:97-128 — entire dind service block: wrap in dind guard
  • internal/embed/assets/docker-compose.yml.tmpl:159-161 — dind volume declarations: wrap in dind guard

  Acceptance Criteria:

  • Template renders valid YAML when DindEnabled=true (identical to current output)
  • Template renders valid YAML when DindEnabled=false (no dind service, no dind volumes, no DOCKER_* env)
  • NO_PROXY excludes "dind" when DindEnabled=false
  • DIND_ENABLED: "true" env var present only when DindEnabled=true
  • No empty volumes: YAML key when dind disabled

  QA Scenarios:

  Scenario: Template renders valid YAML with dind enabled (backward compat)
    Tool: Bash
    Preconditions: Tasks 1-5 applied
    Steps:
      1. Run `go test -run TestCompose -count=1 ./internal/compose/...` (existing tests with DindEnabled: true from T2)
      2. All existing tests must pass — output identical to before
    Expected Result: All tests PASS
    Failure Indicators: Any test failure, YAML parse error, missing dind sections
    Evidence: .sisyphus/evidence/task-5-enabled-tests.txt
  
  Scenario: NO_PROXY excludes dind when disabled
    Tool: Bash
    Preconditions: Tasks 1-5 applied
    Steps:
      1. Search template for NO_PROXY line
      2. Verify it contains `{{if .DindEnabled}},dind{{end}}` conditional
    Expected Result: NO_PROXY dynamically includes/excludes dind
    Failure Indicators: Hard-coded "dind" still present in NO_PROXY
    Evidence: .sisyphus/evidence/task-5-no-proxy-check.txt
  
  Scenario: DIND_ENABLED env var conditionally rendered
    Tool: Bash
    Preconditions: Tasks 1-5 applied
    Steps:
      1. Search template for `DIND_ENABLED` string
      2. Verify it's inside `{{if .DindEnabled}}` block
    Expected Result: DIND_ENABLED env var only appears when dind enabled
    Failure Indicators: DIND_ENABLED unconditional or missing
    Evidence: .sisyphus/evidence/task-5-env-var-check.txt
  

  Commit: YES (groups with T6)

  • Message: feat(compose): conditionally render dind service and entrypoint guard
  • Files: internal/embed/assets/docker-compose.yml.tmpl
  • Pre-commit: go test ./internal/compose/...

• 6. Guard dind iptables rule in entrypoint.sh

  What to do:

  • In internal/embed/assets/entrypoint.sh, line 27: $IPT -I OUTPUT -d dind -j ACCEPT
  • Wrap this line in a conditional check for the DIND_ENABLED env var:

    if [ "${DIND_ENABLED:-}" = "true" ]; then
        $IPT -I OUTPUT -d dind -j ACCEPT
    fi

  • This prevents DNS resolution failure when the dind container doesn't exist
  • Pattern mirrors the existing proxy guard at lines 42-56: if [ "${PROXY_ENABLED:-}" = "true" ]; then

  Must NOT do:

  • Do NOT modify any other iptables rules in entrypoint.sh
  • Do NOT change the proxy conditional section
  • Do NOT modify dind-entrypoint.sh
  • Do NOT change the privilege-dropping logic

  Recommended Agent Profile:

  • Category: quick
    • Reason: Single line wrapped in a conditional, direct pattern copy from proxy guard
  • Skills: []
    • No Go skills needed — this is a bash script change
  • Skills Evaluated but Omitted:
    • golang-code-style: Not applicable to shell scripts

  Parallelization:

  • Can Run In Parallel: YES (with Task 5, after T4)
  • Parallel Group: Wave 2
  • Blocks: Task 7
  • Blocked By: Task 4

  References:

  Pattern References (existing code to follow):

  • internal/embed/assets/entrypoint.sh:42-56 — Proxy conditional block: if [ "${PROXY_ENABLED:-}" = "true" ]; then — exact pattern to mirror for DIND_ENABLED
  • internal/embed/assets/entrypoint.sh:27 — The unconditional dind rule to wrap: $IPT -I OUTPUT -d dind -j ACCEPT

  Acceptance Criteria:

  • Line 27 (dind iptables rule) wrapped in DIND_ENABLED conditional
  • Guard uses [ "${DIND_ENABLED:-}" = "true" ] pattern (with :- default to prevent unset variable error)
  • No other lines in entrypoint.sh modified

  QA Scenarios:

  Scenario: DinD iptables rule is conditionally guarded
    Tool: Bash
    Preconditions: Task 6 applied
    Steps:
      1. Run `grep -A2 'DIND_ENABLED' internal/embed/assets/entrypoint.sh`
      2. Verify output shows: if [ "${DIND_ENABLED:-}" = "true" ]; then ... $IPT -I OUTPUT -d dind -j ACCEPT ... fi
    Expected Result: Guard exists with correct env var check pattern
    Failure Indicators: No DIND_ENABLED guard, or bare $IPT rule without conditional
    Evidence: .sisyphus/evidence/task-6-entrypoint-guard.txt
  
  Scenario: No unrelated entrypoint changes
    Tool: Bash
    Preconditions: Task 6 applied
    Steps:
      1. Run `git diff internal/embed/assets/entrypoint.sh | grep '^[+-]' | grep -v DIND_ENABLED | grep -v 'dind -j ACCEPT' | grep -v '^[+-][+-]' | grep -v 'then\|fi\|if \[' | grep -v '^[+-]$'`
      2. Verify no unexpected lines changed
    Expected Result: Only dind guard lines appear in diff
    Failure Indicators: Other entrypoint logic modified
    Evidence: .sisyphus/evidence/task-6-scope-check.txt
  

  Commit: YES (groups with T5)

  • Message: feat(compose): conditionally render dind service and entrypoint guard
  • Files: internal/embed/assets/entrypoint.sh
  • Pre-commit: go build ./...

• 7. Add dind-specific compose tests (enabled/disabled/combinations)

  What to do:
  Add new test functions to internal/compose/compose_test.go:

  1. TestComposeWithDindEnabled: ComposeParams with DindEnabled: true — assert:

     • dind service block present (contains image: docker:dind)
     • DOCKER_HOST, DOCKER_TLS_VERIFY env vars present on opencode
     • dind-certs-client volume mount present on opencode
     • dind-certs-ca, dind-certs-client, dind-data volume declarations present
     • DIND_ENABLED: "true" env var present on opencode
     • NO_PROXY contains "dind"

  2. TestComposeWithDindDisabled: ComposeParams with DindEnabled: false — assert:

     • dind service block ABSENT (does not contain image: docker:dind)
     • DOCKER_HOST, DOCKER_TLS_VERIFY, DOCKER_TLS_CERTDIR, DOCKER_CERT_PATH env vars ABSENT
     • dind-certs-client volume mount ABSENT on opencode
     • dind-certs-ca, dind-certs-client, dind-data volume declarations ABSENT
     • DIND_ENABLED env var ABSENT
     • NO_PROXY does NOT contain "dind"
     • Generated YAML is valid (no empty sections, proper structure)

  3. TestComposeProxyEnabledDindDisabled: Both proxy on, dind off — assert:

     • Proxy service present, dind service absent
     • NO_PROXY present (for proxy) but without "dind"
     • DOCKER_* env vars absent, proxy env vars present

  4. TestComposeProxyDisabledDindDisabled: Both off — assert:

     • Neither proxy nor dind service present
     • No proxy env vars, no DOCKER_* env vars
     • Minimal valid compose YAML
  • Use t.Parallel() on all test functions
  • Use project's assertContains / assertNotContains helpers (or strings.Contains with t.Errorf)
  • Follow existing test patterns: generate compose output, then assert on string content

  Must NOT do:

  • Do NOT modify existing test functions (already fixed in T2)
  • Do NOT use testify — project uses stdlib testing
  • Do NOT add test helpers to other files

  Recommended Agent Profile:

  • Category: deep
    • Reason: Multiple test functions with comprehensive assertions across 4 proxy/dind combinations
  • Skills: [golang-testing, golang-code-style]
    • golang-testing: Test structure, table-driven patterns, parallel test conventions
    • golang-code-style: Consistent naming and formatting
  • Skills Evaluated but Omitted:
    • golang-stretchr-testify: Project does NOT use testify

  Parallelization:

  • Can Run In Parallel: YES (with Tasks 8, 9)
  • Parallel Group: Wave 3
  • Blocks: None
  • Blocked By: Tasks 2, 5, 6

  References:

  Pattern References (existing code to follow):

  • internal/compose/compose_test.go:824-861 — TestComposeWithProxyEnabled: exact pattern to mirror for dind enabled test (ComposeParams construction, generate, assert)
  • internal/compose/compose_test.go:863-900 — TestComposeWithProxyDisabled: exact pattern to mirror for dind disabled test (assert absence of sections)
  • internal/compose/compose_test.go:902-931 — TestComposeBackwardCompat: example of combination test
  • internal/compose/compose_test.go — assertContains helper (search for func assertContains): the custom assertion helper to use

  Acceptance Criteria:

  • go test -run TestComposeWithDind -count=1 -v ./internal/compose/... — all new tests pass
  • All 4 proxy/dind combinations tested
  • Assertions cover: service presence/absence, env vars, volumes, NO_PROXY content

  QA Scenarios:

  Scenario: All new dind compose tests pass
    Tool: Bash
    Preconditions: Tasks 1-7 applied
    Steps:
      1. Run `go test -run 'TestComposeWithDind|TestComposeProxyEnabledDind|TestComposeProxyDisabledDind' -count=1 -v ./internal/compose/...`
      2. Verify all tests PASS
    Expected Result: 4 new test functions, all PASS
    Failure Indicators: Any test FAIL, compilation error, missing assertions
    Evidence: .sisyphus/evidence/task-7-dind-tests.txt
  
  Scenario: All existing compose tests still pass (regression)
    Tool: Bash
    Preconditions: Tasks 1-7 applied
    Steps:
      1. Run `go test -count=1 ./internal/compose/...`
      2. Verify ALL tests pass (existing + new)
    Expected Result: 0 failures
    Failure Indicators: Any existing test regressed
    Evidence: .sisyphus/evidence/task-7-regression.txt
  

  Commit: YES (groups with T8)

  • Message: test(dind): add dind toggle tests for compose, config, and workspace
  • Files: internal/compose/compose_test.go
  • Pre-commit: go test ./internal/compose/...

• 8. Add config and workspace unit tests for DinD toggle

  What to do:

  In internal/config/config_test.go — add test functions:

  1. TestDindConfigParsing: Table-driven test with cases:

     • TOML with [defaults.dind] / enabled = true → cfg.Defaults.Dind.Enabled is *bool(true)
     • TOML with [defaults.dind] / enabled = false → cfg.Defaults.Dind.Enabled is *bool(false)
     • TOML without [defaults.dind] section → cfg.Defaults.Dind is nil
     • TOML with per-workspace [workspaces.test.dind] / enabled = false → cfg.Workspaces["test"].Dind.Enabled is *bool(false)

  2. TestDindConfigValidation: Verify Validate() passes for valid dind configs (minimal — DindConfig has no complex validation rules)

  In internal/workspace/workspace_test.go — add test functions:

  3. TestResolveDindEnabled: Table-driven test with cases:
     • No dind config anywhere → DindEnabled is true (default)
     • defaults.dind.enabled = false → DindEnabled is false
     • defaults.dind.enabled = false, workspace.dind.enabled = true → DindEnabled is true (workspace overrides)
     • defaults.dind.enabled = true, workspace.dind.enabled = false → DindEnabled is false (workspace overrides)
  • Use t.Parallel(), t.Run() for subtests
  • Match existing test patterns in each file

  Must NOT do:

  • Do NOT modify existing tests
  • Do NOT use testify
  • Do NOT add integration tests

  Recommended Agent Profile:

  • Category: quick
    • Reason: Standard table-driven tests mirroring existing proxy test patterns
  • Skills: [golang-testing, golang-code-style]
    • golang-testing: Table-driven test patterns, t.Parallel conventions
    • golang-code-style: Consistent naming
  • Skills Evaluated but Omitted:
    • golang-stretchr-testify: Project uses stdlib testing, not testify

  Parallelization:

  • Can Run In Parallel: YES (with Tasks 7, 9)
  • Parallel Group: Wave 3
  • Blocks: None
  • Blocked By: Tasks 1, 3

  References:

  Pattern References (existing code to follow):

  • internal/config/config_test.go — Search for TestProxy or proxy-related tests: mirror pattern for dind config parsing tests
  • internal/workspace/workspace_test.go — Search for TestResolve or proxy resolution tests: mirror for dind resolution tests
  • internal/workspace/workspace.go:304-313 — resolveProxyEnabled(): the function being mirrored, understanding test inputs

  API/Type References:

  • internal/config/config.go — DindConfig, Defaults.Dind, Workspace.Dind (from Task 1)
  • internal/workspace/workspace.go — Resolved.DindEnabled, resolveDindEnabled() (from Task 3)

  Acceptance Criteria:

  • go test -run 'TestDindConfig|TestResolveDind' -count=1 -v ./internal/config/... ./internal/workspace/... — all pass
  • Config parsing covers: true, false, nil (absent section), per-workspace override
  • Resolution covers: default true, override false, workspace overrides defaults

  QA Scenarios:

  Scenario: Config and workspace dind tests pass
    Tool: Bash
    Preconditions: Tasks 1, 3, 8 applied
    Steps:
      1. Run `go test -run 'TestDindConfig|TestResolveDind' -count=1 -v ./internal/config/... ./internal/workspace/...`
      2. Verify all tests PASS
    Expected Result: All new config and workspace tests pass
    Failure Indicators: Any test failure
    Evidence: .sisyphus/evidence/task-8-unit-tests.txt
  
  Scenario: No regression in existing config/workspace tests
    Tool: Bash
    Preconditions: Tasks 1, 3, 8 applied
    Steps:
      1. Run `go test -count=1 ./internal/config/... ./internal/workspace/...`
    Expected Result: 0 failures
    Failure Indicators: Any existing test regressed
    Evidence: .sisyphus/evidence/task-8-regression.txt
  

  Commit: YES (groups with T7)

  • Message: test(dind): add dind toggle tests for compose, config, and workspace
  • Files: internal/config/config_test.go, internal/workspace/workspace_test.go
  • Pre-commit: go test ./internal/config/... ./internal/workspace/...

• 9. Update documentation for configurable DinD toggle

  What to do:
  Update 3 documentation files:

  1. docs/reference/configuration.md:

     • Add [defaults.dind] section documenting the enabled field (type: boolean, default: true)
     • Add per-workspace [workspaces.X.dind] override documentation
     • Follow existing proxy documentation pattern/structure

  2. docs/explanation/container-architecture.md:

     • Update the section explaining the two-container model (opencode + dind) to note dind is optional
     • Add a brief note about what changes when dind is disabled (no Docker access, no sidecar, no dind volumes)
     • Mention that orphaned dind volumes may persist on host after disabling dind for a workspace (Docker's default behavior, user can docker volume prune)

  3. docs/how-to/workspace-configuration.md:

     • Add a section on disabling DinD for workspaces that don't need Docker
     • Show example TOML config snippet:

       [workspaces.my-workspace.dind]
       enabled = false

     • Explain when to disable: workspaces focused on code editing, documentation, or non-Docker workflows

  4. docs/llms.txt: Check if any new page was added (none should be — only updating existing pages). If existing page descriptions need updating, update them.

  Must NOT do:

  • Do NOT create new documentation pages
  • Do NOT restructure existing documentation
  • Do NOT modify documentation for unrelated features

  Recommended Agent Profile:

  • Category: writing
    • Reason: Documentation updates following Diátaxis framework
  • Skills: [documentation-writer]
    • documentation-writer: Diátaxis framework expertise for correct documentation category placement
  • Skills Evaluated but Omitted:
    • golang-documentation: For godoc comments, not user-facing docs

  Parallelization:

  • Can Run In Parallel: YES (with Tasks 7, 8)
  • Parallel Group: Wave 3
  • Blocks: None
  • Blocked By: Tasks 5, 6

  References:

  Pattern References (existing code to follow):

  • docs/reference/configuration.md — Search for proxy section: mirror documentation structure for dind
  • docs/explanation/container-architecture.md — Current two-container explanation: update to note optional dind
  • docs/how-to/workspace-configuration.md — Existing workspace config examples: add dind toggle example
  • docs/AGENTS.md — Documentation conventions (Diátaxis framework)

  Acceptance Criteria:

  • docs/reference/configuration.md documents [defaults.dind] and per-workspace override
  • docs/explanation/container-architecture.md explains optional dind
  • docs/how-to/workspace-configuration.md shows how to disable dind
  • docs/llms.txt is up to date (no changes needed if no new pages)
  • No new documentation pages created

  QA Scenarios:

  Scenario: Configuration reference documents dind section
    Tool: Bash
    Preconditions: Task 9 applied
    Steps:
      1. Run `grep -c 'dind' docs/reference/configuration.md`
      2. Run `grep 'enabled' docs/reference/configuration.md | grep -i dind`
    Expected Result: Multiple dind references, enabled field documented
    Failure Indicators: No dind documentation found
    Evidence: .sisyphus/evidence/task-9-reference-check.txt
  
  Scenario: How-to guide shows dind disable example
    Tool: Bash
    Preconditions: Task 9 applied
    Steps:
      1. Run `grep -A5 'dind' docs/how-to/workspace-configuration.md`
    Expected Result: TOML example showing enabled = false
    Failure Indicators: No dind disable example
    Evidence: .sisyphus/evidence/task-9-howto-check.txt
  
  Scenario: No new documentation pages created
    Tool: Bash
    Preconditions: Task 9 applied
    Steps:
      1. Run `git diff --name-status docs/`
      2. Verify only M (modified) status, no A (added) files
    Expected Result: Only existing files modified
    Failure Indicators: New files created in docs/
    Evidence: .sisyphus/evidence/task-9-scope-check.txt
  

  Commit: YES (standalone)

  • Message: docs(dind): document configurable dind toggle
  • Files: docs/reference/configuration.md, docs/explanation/container-architecture.md, docs/how-to/workspace-configuration.md
  • Pre-commit: —

---

Final Verification Wave (MANDATORY — after ALL implementation tasks)

4 review agents run in PARALLEL. ALL must APPROVE. Present consolidated results to user and get explicit "okay" before completing.

• F1. Plan Compliance Audit — oracle
  Read .sisyphus/plans/configurable-dind.md end-to-end. For each "Must Have": verify implementation exists (read file, run command). For each "Must NOT Have": search codebase for forbidden patterns — reject with file:line if found. Check evidence files exist in .sisyphus/evidence/. Compare deliverables against plan.
  Output: Must Have [N/N] | Must NOT Have [N/N] | Tasks [N/N] | VERDICT: APPROVE/REJECT

• F2. Code Quality Review — unspecified-high
  Run go build ./... && go vet ./... && golangci-lint run && go test ./.... Review all changed files for: bare error returns without wrapping, unused variables, dead code, inconsistent naming. Check for AI slop: excessive comments, over-abstraction, drive-by refactors outside scope.
  Output: Build [PASS/FAIL] | Vet [PASS/FAIL] | Lint [PASS/FAIL] | Tests [N pass/N fail] | VERDICT

• F3. Real Manual QA — unspecified-high
  Execute EVERY QA scenario from EVERY task. Verify: go test ./... all pass, template output for all 4 proxy/dind combos produces valid YAML, entrypoint.sh has correct conditional guards, defaultConfigContent includes dind section. Save evidence to .sisyphus/evidence/final-qa/.
  Output: Scenarios [N/N pass] | Integration [N/N] | Edge Cases [N tested] | VERDICT

• F4. Scope Fidelity Check — deep
  For each task: read "What to do", read actual diff. Verify 1:1 — everything in spec was built, nothing beyond spec. Check "Must NOT do" items: no reservedEnvKeys changes, no config_cmd.go changes, no dind-entrypoint.sh changes, no custom error types. Flag unaccounted files.
  Output: Tasks [N/N compliant] | Scope [CLEAN/N issues] | Unaccounted [CLEAN/N files] | VERDICT

---

Commit Strategy

Commit	Tasks	Message	Files	Pre-commit
1	T1	feat(config): add DindConfig struct with enabled toggle	internal/config/config.go	go build ./... && go vet ./...
2	T3, T4, T2	feat(workspace): add DindEnabled resolution, wiring, and test baseline	internal/workspace/workspace.go, internal/compose/compose.go, internal/cmd/up.go, internal/cmd/add.go, internal/compose/compose_test.go	go test ./internal/compose/... ./internal/workspace/...
3	T5, T6	feat(compose): conditionally render dind service and entrypoint guard	internal/embed/assets/docker-compose.yml.tmpl, internal/embed/assets/entrypoint.sh	go test ./internal/compose/...
4	T7, T8	test(dind): add dind toggle tests for compose, config, and workspace	internal/compose/compose_test.go, internal/config/config_test.go, internal/workspace/workspace_test.go	go test ./internal/...
5	T9	docs(dind): document configurable dind toggle	docs/reference/configuration.md, docs/explanation/container-architecture.md, docs/how-to/workspace-configuration.md	—

---

Success Criteria

Verification Commands

go build ./...                    # Expected: clean build
go test ./...                     # Expected: all tests pass
go vet ./...                      # Expected: no issues
golangci-lint run                 # Expected: no issues

Final Checklist

• All "Must Have" items present and verified
• All "Must NOT Have" items absent (no forbidden changes)
• All 4 proxy/dind combinations produce valid compose YAML
• Backward compatible: default config produces identical output to current
• All tests pass including new dind-specific tests
• Documentation updated for reference, explanation, and how-to

[thejoeejoee]

Discussion: Network model analysis & proposed changes

Current iptables rule order (proxy ON)

1. ACCEPT  loopback, established, DNS, dind, gateway     ← always
2. ACCEPT  allowed_hosts on non-HTTP ports                ← private network exceptions
3. ACCEPT  allowed_networks on ALL ports                  ← private network exceptions
4. DROP    ports 80,443,8080,8443 EXCEPT to proxy IP      ← forces HTTP through mitmproxy
5. DROP    RFC 1918, link-local, CGNAT                    ← block private networks
6. (default policy: ACCEPT)                               ← public internet is OPEN

Asymmetry identified

• allowed_networks (CIDRs): bypass proxy entirely — ALL ports ACCEPT, including HTTP
• allowed_hosts (hostnames): HTTP still forced through proxy, only non-HTTP ACCEPT
• Public internet: HTTP through proxy, non-HTTP open — no mechanism to deny specific external hosts

allowed_hosts/allowed_networks are exceptions to the private network block (rule 5), not an allowlist for the internet.

Traffic flow matrix (current + configurable DinD)

Combo	proxy.enabled	dind.enabled	Traffic flow
1	true	true	HTTP chained through mitmproxy → internet. Docker ops via DinD sidecar (TLS :2376). Non-HTTP direct (allowed hosts/networks only).
2	true	false	HTTP chained through mitmproxy → internet. No Docker access. Non-HTTP direct (allowed hosts/networks only).
3	false	true	All traffic direct (no interception). Docker ops via DinD sidecar (TLS :2376). Private networks still DROP'd by iptables.
4	false	false	All traffic direct. No Docker access. Private networks still DROP'd. Lightest footprint.

In all combos: DNS resolvers always ACCEPT, RFC 1918/link-local/CGNAT always DROP (after explicit allows), allowed_hosts get non-HTTP ports only when proxy is on (all ports when proxy off), allowed_networks always ACCEPT regardless.

Proposed changes

1. When proxy enabled, force ALL HTTP through proxy — no exceptions (including allowed_networks CIDRs). Currently allowed_networks bypasses the proxy entirely for all ports including HTTP.

2. Rename allowed_hosts → allowed_internal_hosts and allowed_networks → allowed_internal_networks — to clarify these are exceptions for reaching private/internal resources, not external internet allowlists.

Open questions

• External non-HTTP when proxy on — should it stay ACCEPT (current), or DROP (full lockdown — only HTTP via proxy gets out)?
• Breaking rename — allowed_hosts → allowed_internal_hosts is a config-breaking change. Support old names with deprecation warning, or clean break?

Restricting external access (future)

To actually restrict which external hosts are reachable:

Approach	Restricts	Granularity
Proxy allowlist (mitmproxy script)	HTTP/HTTPS only	Per-domain, per-path, per-method
iptables DROP-all + explicit ACCEPT	All protocols	Per-IP only (hostnames need DNS resolution at rule time)
Combination	Everything	Domain-level via proxy, IP-level via iptables