PRD 0012: Stuck-agent recovery flow #18

Merged

didericis merged 13 commits from agent-unstuck into main 2026-05-25 04:19:52 -04:00

Conversation 0 Commits 13 Files Changed 3

+608

didericis commented 2026-05-24 23:10:46 -04:00

Owner

Copy Link

Copy Source

Summary

Draft PRD for an async recovery flow when an agent in a bottle gets blocked by a missing permission or tool. Agent invokes a slash command, the request reaches the host via the existing cred-proxy (no forge token inside the bottle), a TUI dashboard surfaces the ask and approves a manifest diff, and the orchestrator rebuilds a fresh bottle on the same branch with best-effort transcript carry-over. Working tree is mandatory state; transcript is best-effort; no live channel into running containers.

Tool-denial hook (auto-detect stuck) and a web dashboard are explicitly deferred.

## Summary Draft PRD for an async recovery flow when an agent in a bottle gets blocked by a missing permission or tool. Agent invokes a slash command, the request reaches the host via the existing cred-proxy (no forge token inside the bottle), a TUI dashboard surfaces the ask and approves a manifest diff, and the orchestrator rebuilds a fresh bottle on the same branch with best-effort transcript carry-over. Working tree is mandatory state; transcript is best-effort; no live channel into running containers. Tool-denial hook (auto-detect stuck) and a web dashboard are explicitly deferred.

didericis added 1 commit 2026-05-24 23:10:47 -04:00

docs: add PRD 0012 — stuck-agent recovery flow b4c9e149b0

didericis added 1 commit 2026-05-24 23:12:59 -04:00

docs(prd-0012): open question for gitlock/pipelock exception flow 83756fa8c9

didericis added 1 commit 2026-05-24 23:39:20 -04:00

docs: research on git-gate commit approval; link from PRD 0012 a74dd2b97f

didericis added 1 commit 2026-05-24 23:54:48 -04:00

docs(research): survey gitleaks dashboards + add baseline-file primitive c33930290f

didericis added 1 commit 2026-05-24 23:59:46 -04:00

docs(research): add Betterleaks switching analysis 1f9722ae27

didericis added 2 commits 2026-05-25 00:20:44 -04:00

docs(research): built-in supervisor design (TUI + PR feedback) 02647917b2

Merge branch 'built-in-supervisor' into agent-unstuck ... f733e7195f

Brings the built-in supervisor research note (TUI + PR feedback design)
onto the agent-unstuck branch alongside the existing PRD 0012 +
companion research stack.

didericis added 1 commit 2026-05-25 00:50:44 -04:00

docs(research): drop auto-respawn from the supervisor design ... 95a4433d39

The autonomous "review comment → respawn bottle with comment as
next prompt" loop is the one feature that opens a prompt-injection
vector the bottle wall can't close (a public commenter would get
to issue instructions inside the agent's perimeter on every
launch). The available mitigations — commenter allowlists,
prompt-injection regex screens, private-repo defaults — are all
soft. The durable defense is to keep the human between the
review comment and any next agent prompt.

So `supervise` is now strictly notify-only. The `auto_respawn`
manifest field, the "with auto_respawn: true" behavior paragraph,
and the matching trust-model edge case all go. The reasoning
stays in the "Where to be conservative" bullet so the decision
isn't re-litigated later.

didericis added 1 commit 2026-05-25 01:37:14 -04:00

docs(prd-0012): adopt text-only notify protocol + SIGHUP routes reload ... 49082dfadf

Rewrites Scope, Proposed Design, Data model, and Open questions to
match the model where /supervise/notify is text-in/text-out, routes
edits + SIGHUP reload are supervisor-side tooling, and manifest
rebuilds are the heavy path. Adds the per-bottle routes-edit audit log.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

didericis added 1 commit 2026-05-25 01:47:27 -04:00

docs(prd-0012): name the three stuck categories and add pipelock path ... e5a4c324a0

Introduces cred-proxy block, pipelock block, and capability gap as the
three named categories of stuck. Adds pipelock-edit support (restart-
based for v1) parallel to the existing cred-proxy routes-edit path,
plus a pipelock audit log. Broadens Goals to cover all three paths.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

didericis added 1 commit 2026-05-25 02:53:29 -04:00

docs(prd-0012): switch /stuck to three structured MCP tool calls ... c71713e7d3

Replaces the text-only /supervise/notify protocol with three MCP tools
the agent calls directly: cred-proxy-block, pipelock-block, and
capability-block. Each tool carries the agent's proposed config file
(routes.json, pipelock allowlist, or Dockerfile) plus a justification.
Adds a new MCP sidecar, a read-only current-config mount in the agent
container, and renames "capability gap" to "capability block" to match
the tool name. The text-only-vs-structured tradeoff is captured as an
Open question with pros/cons on both sides.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

didericis added 1 commit 2026-05-25 03:05:58 -04:00

docs(prd-0012): explain why the MCP server is a sidecar, not in-container ... 5c3c60cff4

Captures the rationale for placing the MCP server outside the agent
container. The bottle wall doesn't strictly require it (the operator
TUI is the actual gate), but pattern consistency, audit metadata
trust, connection lifecycle, future enforcement headroom, and
pipelock cleanliness all argue for sidecar placement.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

didericis added 1 commit 2026-05-25 03:40:04 -04:00

docs(prd-0012): split into overview + 4 implementation PRDs ... e10634abe7

PRD 0012 becomes the cross-cutting overview (stuck categories taxonomy,
sidecar-vs-in-container rationale, implementation chunk pointers).
Implementation detail moves into four follow-on PRDs that 0012
references: 0013 (supervise plane foundation), 0014 (cred-proxy block
remediation), 0015 (pipelock block remediation), 0016 (capability
block remediation).

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

didericis merged commit 4079678ceb into main 2026-05-25 04:19:52 -04:00

didericis deleted branch agent-unstuck 2026-05-25 04:19:52 -04:00

Sign in to join this conversation.

Reviewers

No Reviewers

Labels

Clear labels

Compat/Breaking

Breaking change that won't be backward compatible

Kind/Bug

Something is not working

Kind/Documentation

Documentation changes

Kind/Enhancement

Improve existing functionality

Kind/Feature

New functionality

Kind/Security

This is security issue

Kind/Testing

Issue or pull request related to testing

Priority

Critical

1

The priority is critical

Priority

High

2

The priority is high

Priority

Low

4

The priority is low

Priority

Medium

3

The priority is medium

Reviewed

Confirmed

1

Issue has been confirmed

Reviewed

Duplicate

2

This issue or pull request already exists

Reviewed

Invalid

3

Invalid issue

Reviewed

Won't Fix

3

This issue won't be fixed

Status

Abandoned

3

Somebody has started to work on this but abandoned work

Status

Blocked

1

Something is blocking this issue or pull request

Status

Need More Info

2

Feedback is required to reproduce issue or to continue work

No Label

Milestone

No items

No Milestone

Projects

Clear projects

No project

Assignees

Clear assignees

didericis-claude (didericis (claude)) didericis-codex (didericis (codex)) didericis-gemma (gemma) didericis

No Assignees

1 Participants

Notifications

Subscribe

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: didericis/bot-bottle#18