bot-bottle/docs/prds/0015-pipelock-block-remediation.md

PRD 0015: pipelock block remediation

• Status: Superseded by PRD 0017 and PRD 0052
• Author: didericis
• Created: 2026-05-25
• Parent: PRD 0012
• Depends on: PRD 0013

Superseded. Pipelock and its restart-based allowlist remediation path were removed in issue #193. Current egress enforcement is the mitmproxy design from PRD 0017 with DLP in PRD 0052. The design below is retained as history.

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.