feat(flue): add delegated-run provider

[coygeek]

Closes #382 (#382)

Summary

Adds a Flue delegated-run provider for one-shot Linux command execution through a local Flue workflow.

• registers provider: flue as delegated-run with archive-sync and coordinator never
• adds Flue config, flags, environment overrides, protocol request/response handling, sync archive creation, cleanup, and run summaries
• adds non-mutating doctor --provider flue diagnostics
• documents the provider, command behavior, request-file protocol, and Node/local v1 target boundary
• adds a dependency-free Node protocol runner example under docs/examples/flue/

Review Fixes

• Preserves delegated command exit classification when Flue emits a valid protocol response from a non-zero process exit.
• Keeps workflow/process failures as provider failures when Flue exits non-zero despite a success-shaped protocol response.
• Normalizes relative Flue roots before passing them as both --root and process cwd.
• Wires documented CRABBOX_FLUE_* environment variables with timeout validation.
• Sizes Flue process output capture for JSON protocol framing and escaping overhead.
• Keeps secrets out of Flue argv by passing only a request-file pointer.
• Rejects unsafe archive entries, including link entries, before extraction in the example runner.

Verification

• go test ./internal/providers/flue ./internal/providers/all ./internal/cli -run 'Flue|Provider|Doctor|Run|Config|Delegated|Archive|Protocol|Reject'
• go build -trimpath -o bin/crabbox ./cmd/crabbox
• node scripts/generate-provider-matrix.mjs --check
• bash scripts/check-docs.sh
• go vet ./...
• go test -race ./...
• branch autoreview: clean, no accepted/actionable findings

Additional smoke coverage used a fake local Flue CLI from outside the repository to prove provider discovery, doctor success, echo ok, non-zero delegated command classification, relative --flue-root, timeout handling, and archive link rejection.

Notes

Cloudflare/server Flue targets remain intentionally unsupported in v1 because this bridge uses host-local request and archive files. Remote targets need a future upload or HTTP staging contract.

[clawsweeper]

Codex review: needs real behavior proof before merge. Reviewed June 25, 2026, 3:22 PM ET / 19:22 UTC.

Summary
Adds a built-in Flue delegated-run provider with config, flags, environment overrides, request-file protocol handling, archive sync, doctor diagnostics, tests, provider docs, and a Node runner example.

Reproducibility: not applicable. this is a new provider feature rather than a broken existing behavior. Current-main source search shows there is no existing Flue provider to reproduce.

Review metrics: 2 noteworthy metrics.

• Changed surface: 25 files changed, +3024/-2. This is a broad new execution provider, so maintainers need product and runtime confidence beyond ordinary unit tests.
• Config surface: 9 flags, 9 env overrides, 9 config fields. Provider-specific config becomes a user-facing CLI/config API once merged.

Root-cause cluster
Relationship: fixed_by_candidate
Canonical: #382
Summary: This PR is the candidate implementation for the open Flue delegated provider feature request.

Members:

• canonical: Add a Flue delegated provider for running Crabbox jobs through Flue sandboxes #382 - The open issue requests the same first-class Flue delegated-run provider, config, archive-sync, docs, and v1 limitations implemented by this PR.

Proposal only: this assessment does not dispatch repair, suppress jobs, mutate sibling items, close, or merge anything.

Merge readiness
Overall: 🧂 unranked krab
Proof: 🧂 unranked krab
Patch quality: 🐚 platinum hermit
Result: blocked until real behavior proof from a real setup is added.

Overall follows the weaker of proof and patch quality, so missing proof can cap an otherwise strong patch.

Rank-up moves:

• [P1] Add redacted real Flue workflow proof for doctor --provider flue and run --provider flue behavior; updating the PR body should trigger re-review, or a maintainer can comment @clawsweeper re-review.
• Get maintainer confirmation that built-in Flue support and its request-file workflow boundary should be accepted in core.

Proof guidance:

• [P1] Needs real behavior proof before merge: The PR has tests and fake-CLI smoke coverage but no redacted terminal output, logs, recording, or linked artifact from an actual Flue workflow; proof should redact private data before posting. After adding proof, update the PR body; ClawSweeper should re-review automatically. If it does not, the PR author or someone with repository write access can comment @clawsweeper re-review.

Risk before merge

• [P1] The PR body has tests and fake-CLI smoke notes, but no redacted terminal output, logs, recording, or linked artifact from an actual Flue workflow.
• [P1] Merging would decide first-class built-in Flue provider direction while Add a Flue delegated provider for running Crabbox jobs through Flue sandboxes #382 remains open and marked for product and maintainer review.
• [P1] The provider delegates command and environment execution through a local Flue workflow and request file, so maintainers need to explicitly accept that security boundary before release.

Maintainer options:

1. Gate on product approval and live proof (recommended)
   Before merge, a maintainer should explicitly accept built-in Flue support and the contributor should add redacted terminal or log proof from an actual Flue workflow for doctor and run behavior.
2. Accept the opt-in provider boundary
   Maintainers could intentionally land the opt-in provider with current tests, but that would own the unproven live Flue workflow boundary as a release decision.
3. Pause behind the canonical issue
   If the v1 Flue contract is not ready for core, keep the open issue as the design record and pause or close this PR.

Next step before merge

• [P1] Manual review is needed because automation cannot provide product approval for first-class Flue support or contributor proof from a real Flue workflow.

Security
Cleared: No discrete security or supply-chain defect was found in the diff; the remaining security-boundary concern is a maintainer acceptance and live-proof gate.

Review details

Best possible solution:

Land a maintainer-approved built-in Flue provider only after redacted live Flue workflow proof and explicit acceptance of the local request-file execution boundary.

Do we have a high-confidence way to reproduce the issue?

Not applicable; this is a new provider feature rather than a broken existing behavior. Current-main source search shows there is no existing Flue provider to reproduce.

Is this the best way to solve the issue?

Unclear until maintainer product direction is confirmed. The delegated-run shape fits the repository architecture, but built-in provider acceptance and real Flue workflow behavior still need approval and proof.

AGENTS.md: found and applied where relevant.

Codex review notes: model internal, reasoning high; reviewed against 0ec69d642764.

Label changes

Label justifications:

• P2: A new delegated provider is a normal-priority enhancement with bounded but non-trivial provider, config, docs, and execution surface.
• merge-risk: 🚨 security-boundary: The PR introduces a local workflow execution path that carries command/env details through a request file and lacks real Flue workflow proof.
• rating: 🧂 unranked krab: Overall readiness is 🧂 unranked krab; proof is 🧂 unranked krab and patch quality is 🐚 platinum hermit.
• status: 📣 needs proof: The PR needs real behavior proof before ClawSweeper can clear the contributor ask. Needs real behavior proof before merge: The PR has tests and fake-CLI smoke coverage but no redacted terminal output, logs, recording, or linked artifact from an actual Flue workflow; proof should redact private data before posting. After adding proof, update the PR body; ClawSweeper should re-review automatically. If it does not, the PR author or someone with repository write access can comment @clawsweeper re-review.

Evidence reviewed

What I checked:

• AGENTS.md policy read: Repository policy was read fully; the provider-neutral architecture and no-secrets-on-argv guidance apply to this new provider and execution boundary. (AGENTS.md:15, 0ec69d642764)
• Current main has no Flue surface: Current main contains no Flue provider, FlueConfig, CRABBOX_FLUE env wiring, docs, or internal/providers/flue package, so the PR is not obsolete on main. (0ec69d642764)
• Provider contract added by PR: The PR defines provider name/family flue as Linux-only delegated-run with archive-sync and coordinator never. (internal/providers/flue/provider.go:23, 63b7e09cefa2)
• Request-file security boundary: The provider writes command/env details into a 0600 temp JSON request file and passes only a requestFile pointer through flue --input, reducing argv secret exposure but still adding a local workflow trust boundary. (internal/providers/flue/sync.go:72, 63b7e09cefa2)
• Flue CLI invocation shape: The PR invokes flue run workflow: --target node --input and applies configured root/config/env/output paths. (internal/providers/flue/cli.go:56, 63b7e09cefa2)
• Proof remains mock-only: The PR body lists tests and fake local Flue CLI smoke coverage, and the only PR comment is the existing ClawSweeper proof request; no terminal output, logs, recording, or linked artifact from an actual Flue workflow was posted. (63b7e09cefa2)

Likely related people:

• coygeek: Current-main history and blame connect this person to provider backend interfaces, provider registration, and recent delegated-provider additions beyond this PR proposal. (role: recent provider-area contributor; confidence: high; commits: beb0dabaa97e, 4003a3000972, 159da078de76; files: internal/cli/provider_backend.go, internal/providers/all/all.go, internal/providers/agentsandbox)
• Peter Steinberger: Recent current-main provider work added and documented provider surfaces touching the same config, registry, metadata, and provider matrix areas. (role: adjacent provider contributor; confidence: medium; commits: 0301236b2752, 7323324381a2, 494f3a4d779e; files: internal/providers/all/all.go, docs/providers/provider-metadata.json, docs/provider-backends.md)
• Vincent Koc: Git blame shows this person as committer on current-main provider backend and provider registration commits relevant to the routing surface. (role: recent provider-surface committer; confidence: medium; commits: beb0dabaa97e, c886fc794cef; files: internal/cli/provider_backend.go, internal/providers/all/all.go, internal/cli/config.go)

What the crustacean ranks mean

• 🦀 challenger crab: rare, exceptional readiness with strong proof, clean implementation, and convincing validation.
• 🦞 diamond lobster: very strong readiness with only minor maintainer review expected.
• 🐚 platinum hermit: good normal PR, likely mergeable with ordinary maintainer review.
• 🦐 gold shrimp: useful signal, but proof or patch confidence is still limited.
• 🦪 silver shellfish: thin signal; proof, validation, or implementation needs work.
• 🧂 unranked krab: not merge-ready because proof is missing/unusable or there are serious correctness or safety concerns.
• 🌊 off-meta tidepool: rating does not apply to this item.

Shiny media proof means a screenshot, video, or linked artifact directly shows the changed behavior. Runtime, network, CSP, and security claims still need visible diagnostics.

How this review workflow works

• ClawSweeper keeps one durable marker-backed review comment per issue or PR.
• Re-runs edit this comment so the latest verdict, findings, and automation markers stay together instead of adding duplicate bot comments.
• A fresh review can be triggered by eligible @clawsweeper re-review comments, exact-item GitHub events, scheduled/background review runs, or manual workflow dispatch.
• PR/issue authors and users with repository write access can comment @clawsweeper re-review or @clawsweeper re-run on an open PR or issue to request a fresh review only.
• Maintainers can also comment @clawsweeper review to request a fresh review only.
• Fresh-review commands do not start repair, autofix, rebase, CI repair, or automerge.
• Maintainer-only repair and merge flows require explicit commands such as @clawsweeper autofix, @clawsweeper automerge, @clawsweeper fix ci, or @clawsweeper address review.
• Maintainers can comment @clawsweeper explain to ask for more context, or @clawsweeper stop to stop active automation.