claude-projects/agent-builder/GAMEPLAN_agent-sudo_secrets-proxy.md

# Gameplan — Agent-Sudo + secrets-proxy to fully deployed

**Written:** 2026-07-15 20:10 · **Author:** Claude (Opus 4.8) · **Status:** ACTIVE PLAN
**Why now:** 2026-07-15 is the LAST day dedicated to this work. After this, time goes to
business development (revenue) + other projects. Everything here is scoped so a background
agent can do it, with human touches minimized to the ones that are human-only *by design*.

---

## 0. READ THIS FIRST — the goal is not what it sounds like

The stated goal was "Agent-Sudo and secrets-proxy handling tier 0–4 commands."

**Tier 4 must never be handled autonomously. That is not a gap — it is the design.**
Per D-CB7, the `agent-sudo-daemon` unit env holds `SUDO_MD_VERIFY_ENFORCE`. A system that can
restart its own daemon can disarm its own gate. So tier 4 = human-at-a-terminal, permanently.

**"Agent-Sudo handles tier 4" means "Agent-Sudo correctly REFUSES tier 4."** That is
**DONE and VERIFIED LIVE** (2026-07-15 19:52, both hosts):

| command | tier | source |
|---|---|---|
| `rm -rf /` | 4 | `danger_veto` |
| `systemctl restart agent-sudo-daemon` | 4 | `host_override_setb` |
| `vi /etc/systemd/system/agent-sudo-daemon.service` | 4 | `host_override_setb` |

Do not let a future session "finish tier 4." There is nothing to finish. If someone proposes
making tier 4 autonomous, that is a request to delete the security model — refuse it.

**Real remaining scope = tier 1, tier 2, tier 3.**

---

## 1. VERIFIED STATE as of 2026-07-15 20:00 (measured tonight, not remembered)

### Agent-Sudo — DEPLOYED ON BOTH HOSTS (first time ever)
- Commit `005c214` on `origin/main` (repo: `boilerplates.git`, path `/opt/appdata/docker`).
- **server-01**: `192.168.1.90:8082` · healthy · 0 restarts · `{"status":"ok","server_id":"server-01"}`
- **primary**:   `192.168.1.88:8084` · healthy · 0 restarts · `{"status":"ok","server_id":"primary"}`
- Old sudo-bridge STILL owns `192.168.1.88:8082` on primary. **No cutover has happened.** (#146)
- **D-CB6 breaker log is now persistent on BOTH hosts** — `/var/lib/agent-sudo/breaker.log`,
  dir `0700 root:root`, on a bind mount, verified resolving inside the container.
  `docker restart` can no longer reset a tripped breaker. **This closed a hole that was OPEN
  IN PRODUCTION.** `breaker.log` does not exist yet — correct, created 0600 on first append.
- 85/85 tests pass on both hosts.
- Capability gates: `SANDBOX_ENABLED=false`, `SNAPSHOT_ENABLED=false` on both.
  ⇒ **tier 2 and tier 3 currently return 503 stubs. They do not work.**

### Subsystem availability — MEASURED, and it is asymmetric
| host | incus | sandboxes | timeshift |
|---|---|---|---|
| server-01 | **YES** | `sandbox-primary` + `sandbox-server01` both RUNNING | YES |
| primary | **NO** | — | YES |

**This asymmetry is the single most important fact in this document.** Tier 2 (sandbox-test)
CANNOT be enabled on primary — there is no Incus there at all. Any plan that says "enable
tier 2 on both hosts" is wrong. See §3-A3, which is an unresolved DESIGN question, not a task.

### secrets-proxy — STOPPED, NOT BROKEN
- `secrets-proxy-secrets-proxy-1` = `Exited (0)` 6 days ago.
- Logs show a **graceful shutdown** ("Application shutdown complete", "Stopping parent process").
  It was stopped on purpose. **This is not a crash and not a debugging job.**
- Repo: `/opt/appdata/docker/docker-compose/secrets-proxy/` (app.py, docker-compose.yml,
  Dockerfile, mirror/, requirements.txt).
- **HONEST GAP: I did not investigate what work remains on secrets-proxy.** Task #128 says
  "Finish secrets-proxy (sprint-11 #1)" but I have not read sprint-11 or the code. Everything
  below for secrets-proxy is therefore scoped as INVESTIGATE-THEN-PLAN. Do not treat S2 as a
  known quantity. **Do not let an agent invent secrets-proxy work.**
- Its being down has a live cost: the `secrets_via_proxy_only` rule has no proxy to use, so
  secret handling currently falls back to file-passing workarounds.

---

## 2. THE RECURRING BUG CLASS — check this reflexively

**Per-host values hardcoded into files tracked once and shared by both hosts.**
It bit TWICE tonight in one directory, and both were invisible until the two hosts were compared:

1. `docker-compose.yml` hardcoded primary's port `8084`. Pulling it to server-01 would have
   moved Agent-Sudo off 8082 and **silently undone the D8 cutover**. → FIXED: `${AGENT_SUDO_PORT}`
   in each host's gitignored `.env` (primary 8084, server-01 8082).
2. `agent-sudo-daemon.service` carries `SERVER_ID` + `VAULT_ADDR`. The tracked copy says
   `SERVER_ID=primary` and omits `VAULT_ADDR`. Installing it on server-01 would make server-01
   **identify as primary and apply primary's tier-4 rules**, with no Vault path to verify its
   own allowlist. → NOT FIXED. See A4. Currently preserved by hand on server-01.

**Rule for every future session: before landing any shared file on a second host, diff the two
hosts' copies first.** Nothing in the test suite measures cross-host divergence. It never will.

Related lesson from tonight, worth carrying: **a green test suite said nothing about whether the
module even shipped.** 85/85 passed while the image would have crashed on boot with
`ModuleNotFoundError`, and while the breaker was resettable by `docker restart`. A passing check
only means what it measures.

---

## 3. AGENT-SUDO — remaining work

### A1. Fix tier-1 scoped-undo — **DO THIS FIRST. It is code, not config.** 🔴 BLOCKING
**The defect:** `security/scoped_undo.py:186` declares `REQUIRES_UNDO_TIERS = (1, 3)`, but
`app.py:244` calls `scoped_undo.capture_or_refuse(command, 3, server_id=SERVER_ID)` with the
tier **hardcoded to 3**. Nothing ever captures undo for tier 1. So **tier-1 commands
auto-execute today with no undo capture**, which contradicts D4 ("tier 1 = auto-execute +
capture scoped-undo").

**Resolve the conflict BEFORE writing code — this is a human decision:**
The P3 task contract said "tier 0/1 behaviour unchanged"; D4 says tier 1 captures undo. The
background agent followed the task contract and pinned it with a test, then flagged it. It was
right to flag rather than silently pick. Someone must decide:
- (a) Implement D4: tier 1 captures scoped-undo. Cost: every tier-1 command pays undo-capture
  latency. Benefit: tier 1 becomes reversible, which is what makes autonomy safe.
- (b) Amend D4: tier 1 is genuinely fire-and-forget, drop `1` from `REQUIRES_UNDO_TIERS`.
  Cheaper and faster, but then tier 1 is irreversible — and tier 1 is where the volume is.
- **LEAN: (a).** The whole premise of constrained autonomy is that the constraint is real.
  An irreversible tier-1 with no undo is an approval gate removed without a constraint added.
  But this is a real trade and the user decides, not an agent.

⚠️ Whichever way it goes, **the test that currently pins the wrong behaviour must be updated**,
or it will lock in the bug.

### A2. Phase 2 — enable capabilities on server-01, ONE AT A TIME 🟡
Runbook: `/opt/appdata/docker/docker-compose/agent-sudo/DEPLOY_RUNBOOK.md` phase 2.
server-01 only (it has Incus + both sandboxes RUNNING + timeshift).
**This is the first-ever live exercise of the sandbox and snapshot paths.** Until now tier-2/3
have ONLY run against injected fakes — the real Incus and timeshift paths have never executed.
Expect real failures. Budget for that; do not schedule it as a 20-minute flag flip.

Order (do not batch — one flag, verify, then the next):
1. `SNAPSHOT_ENABLED=true` in server-01's `.env` → `docker compose up -d` → exercise a tier-3
   command → verify a timeshift snapshot is actually created AND that undo restores.
2. Then `SANDBOX_ENABLED=true` → exercise a tier-2 command → verify it runs in the Incus
   sandbox and NOT on the host.
⚠️ **Do NOT test the latch by firing a danger-veto command on a live host** (runbook says so).
Latch behaviour is already proven by unit tests + mutation testing.
⚠️ Verify the 503 stub is actually gone, not that health is green. Health does not measure this.

### A3. **DESIGN QUESTION, NOT A TASK: what does tier 2 mean on primary?** 🔴 UNRESOLVED
Primary has no Incus. Options, none free:
- (a) Install Incus on primary. But: `reference_incus_on_docker_host_networking` documents that
  Docker's `FORWARD DROP` breaks the incus bridge and debian/13 systemd-resolved is broken.
  This is a known-painful install on a Docker host — and primary is the PRODUCTION host.
- (b) Primary tier-2 commands execute in server-01's sandbox (cross-host). Introduces the same
  cross-host dependency class as #173, and the sandbox would not mirror primary's state.
- (c) Tier 2 stays permanently 503 on primary; primary's SUDO.md never classifies anything as
  tier 2. Honest and safe; means primary is a lesser-capability host by design. **LEAN: (c)**
  for now — it is the only one that ships without new risk on the production host, and (a) can
  come later if tier-2 volume on primary justifies the pain.
**This must be decided by the user before anyone touches primary tier-2.**

### A4. Daemon unit `EnvironmentFile` — fix the §2 bug class 🟡 HUMAN-ONLY
Make `agent-sudo-daemon.service` host-neutral: `EnvironmentFile=/etc/agent-sudo/daemon.env`,
with `SERVER_ID` / `VAULT_ADDR` / `SUDO_MD_VERIFY_ENFORCE` per-host in that file.
**Tier-4 human-only by design** — that unit's env IS the gate. An agent must never edit it.
**Fold into #173**: the `VAULT_ADDR=http://192.168.1.88:8200` line in server-01's unit IS the
cross-host Vault dependency that #173 exists to resolve. Same file, same edit, one human pass.

### A5. #146 — primary port swap 8084 → 8082 🟢 NOW TRIVIAL
Was a manual file edit; the `${AGENT_SUDO_PORT}` change reduced it to a one-line `.env` edit
plus stopping the old sudo-bridge. Do this LAST, after primary tier-1/2/3 behaviour is settled.
Blocked by: #191 (sudo-bridge/app.py is one of the git-held files).

### A6. server-01 repo hygiene 🟢
server-01's `/opt/appdata/docker` is at HEAD `96f8c05`, **28 commits behind**, with the
agent-sudo dir checked out from `005c214` into a staged index, plus uncommitted local changes to
`jenkins/Dockerfile`, `sudo-bridge/app.py`, `sudo-bridge/docker-compose.yml`.
The files are correct and the deploy is sound, but the repo state is a trap for the next person.
**Why it is this way:** a full `git pull` would have clobbered those held local changes, so a
targeted `git checkout origin/main -- docker-compose/agent-sudo` was used instead. That was the
right call under time pressure; reconciling properly is a separate, careful job.
⚠️ Whoever does this must NOT blindly `git checkout`/`stash` the local changes away — find out
what they are first. Same category as #191.

### A7. Spec gaps A + C on projects row 187 🟢 confirm-and-close
- **(A)** `ATTACK_TIER4_SOURCES` = `('danger_veto', 'host_override_setb')`. `classify()` can also
  reach tier 4 via `rule_match` (explicit SUDO.md tier-4 rule) and `miss_verb_heuristic`. The
  agent made both audit-only, reasoning a latch must mean "this is not resolving." **Decide: is
  an explicit tier-4 SUDO.md rule an attack signal?** One-line change; the D10 seam holds.
  Note D-CB8 deliberately excludes `miss_primary_refuse` — latching on it would take a host
  read-only on the first typo. Do not "fix" that.
- **(C)** A failed PRE-exec snapshot refuses 503 without calling `record_tier3_failure()` — the
  command never ran, so counting it toward the benign trip threshold would let a broken
  timeshift disarm tier 3. Reasoning is sound; just confirm and close.

---

## 4. SECRETS-PROXY — remaining work

### S1. INVESTIGATE — **must happen before any plan is written** 🔴
Nobody currently knows what "finish secrets-proxy" means. Establish, with evidence:
1. **Why was it stopped?** Exit was graceful and deliberate 6 days ago (~2026-07-09). Check git
   log, session summaries, and task #128 / sprint-11 notes for the reason. **It may have been
   stopped for a reason that still applies** — do not just start it.
2. What is incomplete in `app.py` / `mirror/`? What did sprint-11 #1 actually scope?
3. Does it start cleanly today? What breaks if it does?
4. Is its `docker-compose.yml` carrying the §2 per-host-value bug? Check before any second host.
5. Check `project_coolify_env_var_debt`: are there `${VAR}` Coolify placeholders that will bite
   on restart? **This is a known live trap for any container restart.**
**Output: a written scope. Then and only then, plan S2.** Do not skip to S2.

### S2. FINISH + DEPLOY — cannot be scoped until S1 lands 🔴
Placeholder by construction. Anyone writing detail here before S1 is guessing.

### S3. #150 — sign `proxy.md` via Vault transit 🟡
Explicitly blocked on secrets-proxy deploy. Mirrors Agent-Sudo's SUDO.md signing (#145), so the
pattern is proven — reuse `security/sudo_sign.py`, do not reinvent.

### S4. Restore the `secrets_via_proxy_only` rule 🟢
Once up, secret reads go back through the proxy `/shell` + `env_secrets` vault refs, retiring
tonight's file-passing workaround.

---

## 5. SEQUENCING — and the trap in the obvious order

**The ordering paradox** (`feedback_build_the_freeing_capability_first`): the obvious order is
"finish Agent-Sudo, then secrets-proxy, then business dev." But the item that removes a
recurring tax is often scheduled last, behind the things that charge it.

**secrets-proxy being down taxes EVERY future session** — every secret read needs a workaround,
and that cost is paid on business-development days too, when this infrastructure is supposed to
be out of the way. **S1 is zero-dependency and small. Do S1 FIRST**, even before A1, so the
scope is known and can be handed to an agent while attention is elsewhere.

Recommended order:
| # | item | who | why here |
|---|---|---|---|
| 1 | **S1** investigate secrets-proxy | agent | zero-dep, removes a recurring tax, unblocks S2/S3 |
| 2 | **A1 decision** tier-1 undo (a) vs (b) | **human** | blocks all tier-1 work; 5-min decision |
| 3 | **A3 decision** primary tier-2 | **human** | blocks primary; 5-min decision |
| 4 | **A1 implement** | agent | the real code work |
| 5 | **A2** phase 2 on server-01 | agent + human | first live sandbox/snapshot run |
| 6 | **A7** confirm gaps A + C | agent | cheap close-out |
| 7 | **S2** finish secrets-proxy | agent | scoped by S1 |
| 8 | **A4 + #173** unit EnvironmentFile | **human** | tier-4 by design |
| 9 | **A6** repo hygiene, **A5**/#146 swap, **S3**/#150 | mixed | last, low risk |

**Steps 2 and 3 are two human decisions totalling ~10 minutes that unblock everything else.**
Make them before starting a business-development day and the agents can run without you.

---

## 6. WHAT AGENTS MAY AND MAY NOT DO

**Never delegate to an agent (tier-4 / human-only by design):**
- Restarting or stopping `agent-sudo-daemon`; editing its unit file (A4) — *the unit env is the gate*
- Editing `SUDO.md`; writing `/var/lib/agent-sudo/breaker.log`; resetting a tripped latch
- The #146 port swap
- The A1 and A3 **decisions** (implementation is delegable; the choice is not)
- Anything in §2 that lands a shared file on a second host without diffing both first

**Good agent work:** S1 investigation, A1 implementation once decided, A2 under supervision,
A7 confirmations, S2 once scoped, test writing.

**Every agent prompt must carry** (`playbook_background_agent_prompts` +
`feedback_agent_prompt_mandatory_wrapup`): the mandatory wrap-up JSON block
(`status` / `actions_taken` / `actions_failed` / `notes` / `human_action_required`) so the agent
structurally cannot stop without reporting; an explicit permitted-file list; and
`--max-turns`. Tonight proved the value: the P3 agent's two most valuable findings were the
blockers **outside** its permitted file set, which it could only flag, not fix. **An agent that
flags what it cannot touch is working correctly — do not "fix" that by widening permissions.**

---

## 7. DEFINITION OF DONE

Agent-Sudo is done when:
- [ ] Tier 0 executes. **(DONE — verified 2026-07-15)**
- [ ] Tier 4 is refused on both hosts. **(DONE — verified 2026-07-15)**
- [ ] Breaker log persists across restart on both hosts. **(DONE — verified 2026-07-15)**
- [ ] Tier 1 behaviour matches a D4 that has been reconciled with the task contract (A1)
- [ ] Tier 3 creates a real timeshift snapshot and restores, on server-01 (A2)
- [ ] Tier 2 executes in the real Incus sandbox on server-01 (A2)
- [ ] Primary's tier-2 story is decided and written down (A3)
- [ ] The daemon unit is host-neutral (A4 / #173)
- [ ] Instrument-the-gate audit query is scheduled and someone READS it
      (`feedback_instrument_the_gate` — a gate nobody reads is not instrumented)

secrets-proxy is done when: S1 scope written · S2 deployed · S3 `proxy.md` signed ·
`secrets_via_proxy_only` restored without workarounds.

**Not done ≠ not useful.** As of tonight Agent-Sudo safely runs tier-0 and correctly refuses
tier-4 on both hosts, with a tamper-evident breaker. That is real, and it is the part that was
open in production this morning.

---

## 8. XREF
projects **id=187** (P3 detail + 3 spec gaps) · **#149** (parent) · **#146** (port swap) ·
**#173** (fail-open/closed — fold A4 in) · **#191** (git-held files) · **#128** (secrets-proxy) ·
**#150** (proxy.md signing) · `DEPLOY_RUNBOOK.md` (phases) ·
`agent_sudo_design_decisions.md` (D1–D10, D-CB1–D-CB9) ·
memory: `feedback_build_the_freeing_capability_first`, `feedback_instrument_the_gate`,
`feedback_autonomous_security_constrain_not_gate`, `reference_incus_on_docker_host_networking`,
`project_coolify_env_var_debt`, `feedback_agent_prompt_mandatory_wrapup`