Vision: make plugin workflow failures recoverable inside ourocode

[Q00]

Vision

ourocode should make plugin workflow failures recoverable inside the active session, without forcing users back into shell commands, hidden log files, or manual internal run storage directory inspection.

Issue #2 defines the missing bridge for installed Ouroboros UserLevel plugin dispatch: users should be able to invoke trusted plugins from inside ourocode through direct ooo <plugin> ... prompts or natural language. PR #3 documents that product boundary. Once plugin workflows enter the TUI, failure handling becomes part of the core user experience.

The vision is that every expected plugin workflow failure should become a structured recovery state: explain what happened, preserve the user's original intent, show the safe next action, and allow the user to continue without losing context.

Why this matters

The current manual path is brittle because every failure breaks the loop:

• missing plugin installation sends the user to external commands
• missing trust looks like a runtime problem unless the remediation is explicit
• invalid plugin arguments require users to reconstruct their original intent
• handoff generation can succeed while artifact detection fails
• continuation into ooo run can be blocked even though the generated Seed exists
• users may not know whether a failure happened before dispatch, during plugin execution, during artifact capture, or during continuation

If ourocode becomes the terminal-native front door for plugin workflows, it also needs to be the place where users recover from predictable workflow failures.

Product principle

A plugin workflow is not product-ready until its failure states are first-class session objects.

For a prompt like:

Use Superpowers test-driven-development to add retry behavior, then run the generated handoff.

ourocode should be able to stop at any stage and show a recoverable state:

• plugin not installed: show the plugin identity that was requested and the install path or registry source if known
• plugin not trusted: show the exact non-destructive trust command, without granting trust automatically
• command not found: show nearby installed commands and ask for clarification
• missing required arguments: preserve the inferred command and ask only for the missing argument
• plugin execution failed: keep stdout, stderr, exit status, run id, and provenance attached to the session
• artifact detection failed: show the run directory and offer to scan or select the generated artifact
• continuation blocked: show why ooo run seed_path=... cannot proceed and what is required to unblock it

Proposed scope

1. Define a PluginWorkflowRecovery model or equivalent structured state for expected plugin dispatch failures.
2. Attach recovery states to the original prompt, resolved plugin, resolved command, trust state, run id, output, artifacts, and continuation policy when available.
3. Render recovery states in the TUI with one clear next action instead of raw error text alone.
4. Preserve enough context for the user to retry after fixing trust, arguments, missing plugin state, or artifact selection.
5. Ensure recovery actions never silently install, trust, or execute destructive plugin commands.
6. Record recovery transitions in the journal so failures can be audited and reproduced.
7. Cover the Superpowers golden path with at least one recoverable failure at each major stage: resolution, trust, execution, artifact detection, and continuation.

Acceptance criteria

• Missing plugin, untrusted plugin, missing command, missing arguments, plugin execution failure, artifact detection failure, and continuation-blocked states are represented as structured recovery states.
• Each recovery state includes a human-readable explanation and a single safe next action.
• The user's original prompt and inferred workflow are preserved across recovery and retry.
• Trust recovery shows an explicit command but does not auto-trust plugins.
• Artifact recovery can surface a run directory and allow the generated Seed to be selected or re-detected.
• Continuation recovery shows the blocked ooo run seed_path=... step and the condition required to proceed.
• Tests cover recovery-state construction, TUI rendering metadata, retry context preservation, and journal persistence.

Non-goals

• Auto-installing plugins.
• Auto-trusting plugins.
• Retrying destructive actions without explicit user approval.
• Replacing the plugin preflight, workflow plan, capability contract, or audit issues.
• Building a full troubleshooting wizard.

Related

• Builds on Support natural-language dispatch for installed Ouroboros UserLevel plugins #2.
• Informed by PR docs: rescope userlevel plugin dispatch around SSOT #25 (PR 1/5) #3.
• Complements Vision: turn plugin intent into reviewable workflow plans #11 by defining what happens after a workflow plan cannot proceed.
• Complements Vision: make plugin resolution an explicit preflight step #16 by turning blocked preflight results into recoverable session states.