didericis
47c3ba63f8
Flip Status: Draft -> Active for the 23 PRDs whose work has shipped to main (including 0027, now that PR #95 has merged). Leaves the terminal-status PRDs unchanged: 0007 and 0010 (Superseded) and 0014 (Retargeted) were replaced, not shipped as-is. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
68 lines
4.3 KiB
Markdown
68 lines
4.3 KiB
Markdown
# PRD 0015: pipelock block remediation
|
|
|
|
- **Status:** Active
|
|
- **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 <bottle>` 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 <bottle>` 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 <bottle>` 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.
|