---
id: SAND-WP-0004
type: workplan
title: "the-custodian e2e shim and deprecation"
domain: infotech
repo: sand-boxer
status: finished
owner: codex
topic_slug: custodian
created: "2026-06-23"
updated: "2026-06-23"
state_hub_workstream_id: "9fe4beb2-d766-4054-b998-10b01ca66a0e"
---

# the-custodian e2e shim and deprecation

Complete the `e2e-framework/` migration arc: operators keep `make e2e REPO=` in
`the-custodian`, but execution delegates to **wise-validator** (`validate run`)
and **sand-boxer** (provision via `profile.compose-e2e`). Retire embedded
provision/validation in `e2e-framework/` with deprecation notices.

**Charter:** `INTENT.md` (lineage), `docs/migration-gaps.md`  
**Predecessor:** SAND-WP-0003 (wise-validator extraction — finished)  
**Gap analysis:** `history/2026-06-23-post-wp0003-intent-scope-gap-analysis.md` (P1)

Primary implementation touches `the-custodian`; sand-boxer owns coordination,
doc pointers, and verification runbook updates.

## Shim Makefile target

```task
id: SAND-WP-0004-T01
status: done
priority: high
state_hub_task_id: "112917a5-2f04-4c82-bc40-2a6d8b54e188"
```

In `the-custodian/Makefile` (or documented wrapper), replace `e2e` target body:

- Resolve `REPO` path (`~/REPO` or `REPO_ROOT/REPO`)
- Invoke `validate run <repo>` with env passthrough:
  `HOST` → `SANDBOXER_HOST`, `KEEP`, `WORKSTREAM_ID`, `SANDBOXER_COMPOSE_CMD`
- Preserve exit code semantics (0 pass / 1 fail)
- Document prerequisites: `sandboxer` + `validate` on PATH

## Deprecate e2e_framework module

```task
id: SAND-WP-0004-T02
status: done
priority: high
state_hub_task_id: "94399b5c-89dd-4ef6-9c5e-ffa3887ca572"
```

`the-custodian/e2e-framework/`:

- `cli.py` / `__main__.py`: print deprecation warning; delegate to
  `validate run` via subprocess (thin wrapper for backward compat)
- `sandbox.py`: mark module deprecated — provision owned by sand-boxer
- Keep files until one release cycle; no new features

## Runbook and doc migration

```task
id: SAND-WP-0004-T03
status: done
priority: medium
state_hub_task_id: "40c70f8b-fa2e-4f4b-b521-665c8d92b403"
```

- Update `the-custodian/e2e-framework/RUNBOOK.md` — banner pointing to
  `wise-validator/docs/runbooks/validate-compose-e2e.md` and
  `sand-boxer/docs/runbooks/profile-compose-e2e.md`
- Update `sand-boxer/docs/migration-gaps.md` — mark SAND-WP-0004 delivered
- Update `SCOPE.md` "What Is Possible Now" if needed

## Verification

```task
id: SAND-WP-0004-T04
status: done
priority: high
state_hub_task_id: "7a993f9d-cc79-400d-b6c1-73621fbd4055"
```

- Document verification steps (CoulombCore): `make e2e REPO=sand-boxer` and
  `make e2e REPO=activity-core` with `SANDBOXER_HOST` + `podman-compose`
- Optional: add `scripts/verify-e2e-shim.sh` in the-custodian
- wise-validator T09 remote smoke can satisfy sand-boxer path; activity-core
  run is stretch goal (Temporal slow start)

## activity-core scheduling pointer (optional)

```task
id: SAND-WP-0004-T05
status: done
priority: low
state_hub_task_id: "3a1bb3e1-6433-47b5-8ef6-a9bfab3a7c2f"
```

Document how activity-core instructions should invoke `validate run` instead of
`make e2e` — no activity-core code changes in this workplan unless a ready
instruction template exists.

---

## Success criteria

- `make e2e REPO=<repo>` from `the-custodian` uses wise-validator + sand-boxer
- No new code paths call `e2e_framework.sandbox.provision()` directly
- Deprecation visible on legacy `python -m e2e_framework` entry
- Migration gaps doc shows e2e-framework arc complete

## Follow-ons (from gap analysis)

| Item | Workplan |
|------|----------|
| Extension SDK + `ext.vm-packer` | SAND-WP-0005 |
| TTL enforcement + scheduled reap | TBD (extend telemetry or new WP) |
| SaaS extensions + payments | SAND-WP-0006 |
| Snapshot / restore | SAND-WP-0007 |