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

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 <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.