jwbron · jwbron · May 20, 2026 · May 19, 2026 · May 19, 2026 · May 19, 2026
diff --git a/.egg-state/brc-history/2717-implement-slice-1.json b/.egg-state/brc-history/2717-implement-slice-1.json
diff --git a/.egg-state/brc-history/2717-implement-slice-1.md b/.egg-state/brc-history/2717-implement-slice-1.md
diff --git a/docs/architecture/claude-code-substrate.md b/docs/architecture/claude-code-substrate.md
diff --git a/docs/development/STRUCTURE.md b/docs/development/STRUCTURE.md
@@ -139,6 +139,21 @@ orchestrator/
 ├── status_reporter.py      # Real-time status reporter for collaborators
 ├── unified_sse.py          # Unified SSE stream for all pipelines
 ├── webhooks.py             # GitHub webhook handlers
+├── substrate/              # Substrate-swap abstraction layer (walking-skeleton #2623): four Protocol interfaces + env-var-selected factory
+│   ├── __init__.py         # `select_substrate(env)` factory; reads `EGG_SUBSTRATE` (`k3s` or `claude-code`)
+│   ├── spawner.py          # `AgentSpawner` protocol + `AgentResult` dataclass
+│   ├── message_bus.py      # `MessageBus` protocol
+│   ├── policy.py           # `PolicyEnforcer` protocol
+│   ├── worktree.py         # `WorktreeManager` protocol
+│   ├── k3s_adapter.py      # `K3sSpawnerAdapter` shim wrapping `KubernetesSpawner.create_concurrent_spawn_fn`
+│   ├── in_process.py       # `run_pipeline_in_process()` generator entry point (claude-code substrate only)
+│   └── claude_code/        # Claude-Code-native implementations
+│       ├── spawner.py      # `ClaudeCodeSpawner` — runs `egg_harness.run_agent` in-process (Agent-tool dispatch is a follow-up; see ADR "Open work")
+│       ├── hook_entry.py   # Standalone `python3 -m` PreToolUse hook script invoked by Claude Code (Bash/Write/Edit parser; fail-closed on ambiguous shapes)
+│       ├── message_bus.py  # `InProcessMessageBus` — subclasses `MessageStore` (in-memory)
+│       ├── policy.py       # `PolicyEnforcer` adapter (`check_write` + `install`) wrapping the `hook_entry.py` script
+│       ├── settings.template.json # Claude Code settings template registering `hook_entry.py` as the PreToolUse hook
+│       └── worktree.py     # `LocalWorktreeManager` — per-agent worktrees under `~/.egg-worktrees/`
 ├── overseer/               # Overseer agent package (LLM-powered tier of pipeline health monitoring)
 │   ├── classifier.py       # Haiku-tier classifiers (stall, loop, error triage, off-track detection)
 │   ├── decision_maker.py   # Sonnet/Opus-tier decision-maker (corrective actions, redirect messages)

diff --git a/docs/guides/deployment.md b/docs/guides/deployment.md
@@ -69,6 +69,10 @@ scripts/install-cilium.sh   # downloads cilium-cli and runs `cilium install`
 > **Why `--disable=metrics-server`?** Under Cilium, the metrics-server pod cannot reach the kubelet on the node IP, so it never becomes Ready. The resulting perpetually-unavailable `v1beta1.metrics.k8s.io` APIService causes the namespace controller's discovery step to fail, which wedges all namespace deletion (namespaces become stuck in `Terminating` indefinitely). egg does not use metrics-server; disabling it avoids this hang with no functional loss.
 >
 > **Migrating from a pre-#2703 install:** in-place CNI swap on a live k3s cluster is not supported (host CNI binaries, conflists, CRDs, `tunl0`, and per-pod veth pairs persist after deleting the calico-node DaemonSet). Run `make k3s-teardown && make k3s-setup` for a clean install. `install-cilium.sh` will refuse if it detects leftover Calico state.
+>
+> **Migrating from a pre-#2713 install:** `install-cilium.sh` chains the portmap CNI plugin (`cni.chainingMode=portmap`) for hostPort support and installs a pod-egress MASQUERADE iptables rule that Cilium omits in chained mode. If the running cluster predates #2713, `install-cilium.sh` will exit with a `cni-chaining-mode` mismatch error and instruct you to run `make k3s-teardown && make k3s-setup` — the chainingMode cannot be changed on a live cluster.
+>
+> **After a host reboot:** re-run `scripts/install-cilium.sh` (or `make k3s-setup`) to restore the pod-egress MASQUERADE iptables rule. This rule is not persisted across reboots. Without it, pod-to-external traffic (gateway → GitHub, sandbox agents → Anthropic API) silently fails while intra-cluster traffic continues working. On long-running hosts where re-running after every reboot is painful, wire the rule into `netfilter-persistent`/`iptables-restore` at the system level instead.
 
 #### Image Management
 

diff --git a/docs/guides/sdlc-pipeline.md b/docs/guides/sdlc-pipeline.md
@@ -1634,9 +1634,10 @@ If the commit logs show success but files are missing/present in the PR diff, th
 
 1. `PR-phase push succeeded` — Push completed. Includes `commits_ahead` showing how many local commits were ahead of remote before the push.
 2. `Push attempt failed — caller may retry via reconcile` (INFO) followed by `Push rejected — attempting fetch+rebase+retry to reconcile divergence` (WARNING) — Initial push was rejected; `GatewayClient` is attempting a fetch+rebase reconcile and a second push automatically.
-3. `PR-phase push failed after reconcile — falling back to PR against remote HEAD; orchestrator housekeeping commits dropped` (WARNING) — The reconcile+retry also failed. The PR is still created against the current remote HEAD — agent commits are preserved, but orchestrator housekeeping commits (BRC history rewrite, cleanup) are not included. This is preferable to failing the whole pipeline.
-4. `PR-phase push skipped` — The push was not attempted. The `reason` field explains why: `"worktree_repo_path == repo_path"` (no separate worktree to push from) or `"no branch set"` (pipeline has no branch configured).
-5. Check the gateway health: `curl http://egg-gateway:9848/api/v1/health`.
+3. `Push reconcile: rebase succeeded but autostash pop produced conflicts` (ERROR) — The rebase itself succeeded, but the post-rebase autostash pop hit a merge conflict (`reconcile_autostash_pop_conflict`). The autostash entry is preserved in `git stash list` on the orchestrator worktree for manual recovery. The conflicting paths are listed in the log's `conflicting_paths` field.
+4. `PR-phase push failed after reconcile — falling back to PR against remote HEAD; orchestrator housekeeping commits dropped` (WARNING) — The reconcile+retry also failed. The PR is still created against the current remote HEAD — agent commits are preserved, but orchestrator housekeeping commits (BRC history rewrite, cleanup) are not included. This is preferable to failing the whole pipeline.
+5. `PR-phase push skipped` — The push was not attempted. The `reason` field explains why: `"worktree_repo_path == repo_path"` (no separate worktree to push from) or `"no branch set"` (pipeline has no branch configured).
+6. Check the gateway health: `curl http://egg-gateway:9848/api/v1/health`.
 
 **Quick diagnostic checklist**:
 

diff --git a/docs/index.md b/docs/index.md
@@ -31,6 +31,7 @@ This index helps both humans and LLMs navigate the documentation efficiently.
 | [The Agentic Feedback Loop](architecture/agentic-feedback-loop.md) | The foundational work-review-feedback cycle that drives quality |
 | [Why egg Works](architecture/collaboration-effectiveness.md) | How the public, sandboxed, async model delivers safety and collaboration |
 | [Integration-Test Trust Boundary](architecture/integration-test-trust-boundary.md) | Test execution contexts (in-sandbox-agent / trusted-CI-runner / human-operator) and fixture tiers; authoritative reference for plan-phase Trust-Boundary Audit (#2594) |
+| [Claude Code Substrate](architecture/claude-code-substrate.md) | Substrate-swap walking-skeleton (#2623): four `Protocol`s (`AgentSpawner` / `MessageBus` / `PolicyEnforcer` / `WorktreeManager`) under `orchestrator/substrate/`, env-var-selected via `EGG_SUBSTRATE`, with Claude-Code-native implementations and an in-process orchestrator generator (`run_pipeline_in_process`) |
 
 ### Development