From 0197599e494d6c2e251d42ed874c4ff40cced9e9 Mon Sep 17 00:00:00 2001 From: didericis Date: Mon, 25 May 2026 03:41:10 -0400 Subject: [PATCH] docs(prd-0015): pipelock block remediation Adds PRD 0015, the second remediation engine in the stuck-agent recovery flow (overview in PRD 0012, foundation in PRD 0013). Wires the pipelock block path with restart-based reload: supervisor writes the new allowlist on approval and restarts pipelock, proactive pipelock edit TUI verb, pipelock audit log filled in. SIGHUP reload for pipelock is deferred to a follow-up. Co-Authored-By: Claude Opus 4.7 --- docs/prds/0015-pipelock-block-remediation.md | 67 ++++++++++++++++++++ 1 file changed, 67 insertions(+) create mode 100644 docs/prds/0015-pipelock-block-remediation.md diff --git a/docs/prds/0015-pipelock-block-remediation.md b/docs/prds/0015-pipelock-block-remediation.md new file mode 100644 index 0000000..1534fa4 --- /dev/null +++ b/docs/prds/0015-pipelock-block-remediation.md @@ -0,0 +1,67 @@ +# PRD 0015: pipelock block remediation + +- **Status:** Draft +- **Author:** didericis +- **Created:** 2026-05-25 +- **Parent:** PRD 0012 +- **Depends on:** PRD 0013 + +## Summary + +Wires the **pipelock block** path (PRD 0012 *Stuck categories*) end-to-end. The supervisor, on approval of a `pipelock-block` proposal, writes the new pipelock allowlist to the host and restarts pipelock; the agent's in-flight outbound calls may drop and rely on retry. The TUI gains a proactive `pipelock edit ` verb for operator-initiated edits unrelated to a tool call. The pipelock audit log (format defined in PRD 0013) is filled in with real entries on every edit. + +## Problem + +See PRD 0012. This PRD specifically addresses: with 0013 in place, the operator can approve a `pipelock-block` proposal but nothing happens — the allowlist doesn't change and pipelock doesn't notice. This PRD closes the loop, using restart-based reload. SIGHUP for pipelock is deferred to a follow-up (see Open questions). + +## Goals / Success Criteria + +A real pipelock block recovers end-to-end: the agent's outbound HTTP request fails with a connection-refused (host not in allowlist), the agent calls `pipelock-block` with a proposed allowlist and justification, the operator approves in the TUI, the supervisor writes the new allowlist and restarts pipelock, the agent retries and proceeds. + +## Non-goals + +- SIGHUP / hot reload for pipelock. v1 ships restart-based reload only. +- One-off gitlock / pipelock exceptions (e.g. waive a specific commit SHA, not a permanent allowlist entry) — see Open questions. +- cred-proxy or capability handling (covered by 0014 and 0016). + +## Scope + +### In scope + +- Supervisor write path: on operator approval of a `pipelock-block` proposal, write the proposed allowlist to the host-side path pipelock reads, then restart the pipelock container. +- `pipelock edit ` TUI verb: open the bottle's current pipelock allowlist in `$EDITOR`, write + restart pipelock on save. Not gated on a pending proposal. +- pipelock audit log entries: every allowlist edit (from a tool-call approval or from a proactive `pipelock edit`) appends an entry with timestamp, diff, justification (if from tool call), and operator action. + +### Out of scope + +- SIGHUP reload (deferred — see Open questions). +- cred-proxy equivalents (PRD 0014). + +## Proposed Design + +### New services / components + +- **`pipelock edit ` TUI verb.** Opens the bottle's current pipelock allowlist in `$EDITOR`. On save, the supervisor writes the new file and restarts pipelock. + +### Existing code touched + +- **pipelock** — gains a clean restart path that picks up the new allowlist on container restart. No pipelock code changes likely needed if pipelock already reads its config on startup; the orchestration is supervisor-side. +- **MCP sidecar** (PRD 0013) — the `pipelock-block` approval handler stops being a no-op; on approval, calls the supervisor's write+restart path. +- **`cli.py`** — dashboard subcommand gains the `pipelock edit` verb. + +### Data model changes + +None beyond PRD 0013. + +## Open questions + +- **SIGHUP reload for pipelock.** v1 ships restart-based reload, which drops in-flight outbound calls. Should pipelock gain SIGHUP support so **pipelock block** is as cheap as **cred-proxy block**? Depends on how often the operator edits the allowlist mid-task and how disruptive a pipelock bounce actually is. +- **Gitlock / pipelock one-off exceptions.** Some pipelock denials don't want a permanent allowlist entry — e.g. a commit that includes docs with intentionally-bogus tokens that the secret scanner correctly flags. The shape (agent blocked → tool call → operator decides → result) is the same, but the *resolution* is a per-operation override or a scoped allowlist entry, not a permanent edit. Is this a fourth tool (`exception-block`?), or does it fold into `pipelock-block` with a scoped one-shot allowlist entry? Either way, the approval must be auditable so a future reader can see what was waived and why. See `docs/research/git-gate-commit-approval.md` for a survey of gitleaks's native allowlist primitives and a recommendation. + +## References + +- PRD 0001 — per-agent egress proxy via pipelock. +- PRD 0008 — git-gate. +- PRD 0012 — stuck-agent recovery flow overview. +- PRD 0013 — supervise plane foundation (prerequisite). +- `docs/research/git-gate-commit-approval.md` — gitleaks allowlist primitives.