feat: add GitHub Codespaces provider

[coygeek]

Closes #348

Summary

Adds a direct GitHub Codespaces Linux SSH-lease provider with aliases codespaces and gh-codespaces.

• Creates claim-owned GitHub Codespaces through the GitHub REST API and local gh authentication.
• Uses gh codespace ssh --config to drive normal Crabbox SSH, rsync, run, ssh, status, stop, and cleanup flows.
• Keeps the provider direct-only; it does not route through the Crabbox coordinator.
• Adds provider config/flags/env handling, generated provider metadata, docs, OpenSSH config parsing, lifecycle tests, guarded standalone live-smoke coverage, and shared scripts/live-smoke.sh dispatch.
• Keeps release and cleanup conservative: local claim required, creating login must match, dirty Codespaces fall back to stop/retain, and repo-local config cannot redirect creation to an arbitrary repository.
• Rebased onto current main, retaining both the new vast defaults/provider docs and this Codespaces provider surface.

Verification

Local validation on current head 928f643a2398dc64608abf8680396e3c2da97aab:

go test ./internal/providers/githubcodespaces ./internal/providers/all ./internal/cli ./cmd/crabbox
node --test scripts/live-github-codespaces-smoke.test.js scripts/live-smoke.test.js
bash -n scripts/live-smoke.sh scripts/live-github-codespaces-smoke.sh
node scripts/generate-provider-matrix.mjs --check
node scripts/check-provider-matrix.mjs
node scripts/check-command-docs.mjs
node scripts/check-docs-links.mjs
node scripts/build-docs-site.mjs
scripts/check-docs.sh
go vet ./...
go build -trimpath -o bin/crabbox ./cmd/crabbox
git diff --check

Generated provider matrix was refreshed after the rebase: current docs now report 71 built-in providers and 42 SSH-lease providers.

Exact-head CI is terminal green: https://github.com/openclaw/crabbox/actions/runs/28685912168

Remaining Merge Gate

Do not merge yet while status: 📣 needs proof, merge-risk: 🚨 auth-provider, merge-risk: 🚨 compatibility, and merge-risk: 🚨 security-boundary remain. This still needs redacted authenticated GitHub Codespaces lifecycle proof:

CRABBOX_LIVE=1 \
CRABBOX_LIVE_PROVIDERS=github-codespaces \
CRABBOX_GITHUB_CODESPACES_SMOKE_REPO=<owner/repo> \
GH_TOKEN=<token> \
scripts/live-smoke.sh

Required proof should show doctor, create/wait for a short-lived Codespace lease, synced command execution, rendered SSH command, release/delete or safe stop/retain fallback, dry-run cleanup, final claim-owned inventory state, and no leaked token/output. Local GitHub auth still lacks the required codespace scope, so live provider proof remains the only blocker after exact-head local and CI validation.

[clawsweeper]

Codex review: needs real behavior proof before merge. Reviewed July 3, 2026, 6:50 PM ET / 22:50 UTC.

Summary
Adds a direct-only GitHub Codespaces Linux SSH-lease provider with aliases, config/env/flag handling, REST and gh integration, docs, tests, generated provider metadata, and guarded live-smoke wiring.

Reproducibility: not applicable. this is a new provider PR, not a bug report. Current main lacks a GitHub Codespaces provider, and the PR supplies the implementation candidate.

Review metrics: 2 noteworthy metrics.

• Diff size: 30 files, +4704/-4. The PR adds a broad provider surface across core config, registry, docs, tests, and live-smoke scripts, so proof and maintainer acceptance matter before merge.
• Provider surface: 1 built-in provider, 2 aliases. The canonical provider name and aliases become user-facing compatibility surface once released.

Root-cause cluster
Relationship: fixed_by_candidate
Canonical: #348
Summary: This PR is the linked implementation candidate for the open GitHub Codespaces provider feature request; no safer merged or open replacement PR supersedes it.

Members:

• canonical: Add GitHub Codespaces as a Crabbox Linux provider #348 - The PR body uses closing syntax for the open issue requesting the same GitHub Codespaces Linux provider and GitHub reports it as a closing issue reference.

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

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

Rank-up moves:

• [P2] Add redacted authenticated current-head live-smoke proof for doctor, create/wait, sync/run/ssh, release or retain fallback, cleanup dry-run, final inventory, and token redaction.
• Get maintainer acceptance for the provider contract: names, aliases, config/env/flag keys, defaults, direct-only scope, and delete-versus-stop policy.

Proof guidance:

• [P1] Needs real behavior proof before merge: The PR has tests and green CI, but no redacted current-head authenticated Codespaces lifecycle proof; terminal output, copied live output, recordings, linked artifacts, or redacted logs should be added to the PR body, then ClawSweeper can re-review automatically or via @clawsweeper re-review.

Risk before merge

• [P1] Redacted authenticated current-head Codespaces lifecycle proof is still absent, so scoped auth, quota/billing behavior, generated SSH config, sync/run/ssh, cleanup, and token redaction remain unproven in a real account.
• [P1] The provider name, aliases, flags/env/config keys, default machine/work-root behavior, and delete-versus-stop policy become compatibility surface once shipped.
• [P1] The PR handles GitHub credentials and can stop or delete personal Codespaces; even with claim checks, maintainers need explicit security-boundary acceptance before landing.

Maintainer options:

1. Require live Codespaces proof (recommended)
   Ask for redacted terminal output, logs, recording, or linked artifact from the documented current-head live-smoke command showing doctor, create, run/sync/ssh, release or safe retain, cleanup dry-run, final inventory, and no leaked secrets.
2. Accept the new provider contract
   After proof is posted, maintainers can explicitly accept the canonical name, aliases, config/env/flag keys, default machine/work-root behavior, and delete-versus-stop policy as the first shipped contract.
3. Pause if first-party scope is not settled
   If maintainers are not ready to own GitHub Codespaces as a built-in provider, pause or close this PR and keep the linked issue as the product-direction record.

Next step before merge

• [P1] The remaining work is credentialed live proof plus maintainer product/security acceptance, not a narrow automated code repair.

Security
Needs attention: Needs attention: no definite exploit was found, but the new credentialed Codespaces control plane and destructive lifecycle paths require redacted live proof and maintainer acceptance.

Review details

Best possible solution:

Merge only after current-head live-smoke proof demonstrates the full Codespaces lifecycle with redacted output and maintainers explicitly accept the provider API, defaults, and cleanup/security behavior.

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

Not applicable: this is a new provider PR, not a bug report. Current main lacks a GitHub Codespaces provider, and the PR supplies the implementation candidate.

Is this the best way to solve the issue?

Unclear for merge readiness: the dedicated provider adapter matches the repository architecture, but it should not land until current-head live proof and maintainer product/security acceptance are in place.

AGENTS.md: found and applied where relevant.

Codex review notes: model internal, reasoning high; reviewed against 62831c8972de.

Label changes

Label justifications:

• P2: This is a normal-priority new provider feature with a clear implementation path and limited blast radius, but it is not an urgent regression.
• merge-risk: 🚨 auth-provider: The provider depends on gh authentication and GH_TOKEN/GITHUB_TOKEN Codespaces scope, so merging could affect credential and provider-auth behavior.
• merge-risk: 🚨 compatibility: The new built-in provider names, aliases, config keys, defaults, and release policy become shipped user-facing contract.
• merge-risk: 🚨 security-boundary: The diff introduces credentialed GitHub API calls and claim-backed stop/delete operations for user Codespaces, which need live proof and maintainer acceptance.
• 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 green CI, but no redacted current-head authenticated Codespaces lifecycle proof; terminal output, copied live output, recordings, linked artifacts, or redacted logs should be added to the PR body, then ClawSweeper can re-review automatically or via @clawsweeper re-review.

Evidence reviewed

Security concerns:

• [medium] Credentialed Codespaces control plane needs live proof — internal/providers/githubcodespaces/backend.go:494
  The provider reads GH_TOKEN, GITHUB_TOKEN, or gh auth token and sends bearer auth to GitHub; the PR still lacks current-head live proof that scope handling and output redaction behave safely in a real account.
  Confidence: 0.9
• [medium] Codespaces delete and cleanup paths need acceptance — internal/providers/githubcodespaces/backend.go:326
  Release and cleanup can delete claim-backed Codespaces after validation, so maintainers should require proof that claim matching, safe retain fallback, and no-foreign-resource behavior hold in real GitHub Codespaces state.
  Confidence: 0.86

What I checked:

• Repository policy read: AGENTS.md was read fully; its provider-neutral architecture and secret-handling guidance are relevant because this PR adds a provider adapter, config surface, and credentialed control plane. (AGENTS.md:1, 62831c8972de)
• Current main does not implement this provider: Current main imports many built-in providers but has no internal/providers/githubcodespaces registration; repository search only found generic recommendation keywords for codespaces, not an implementation or provider docs. (internal/providers/all/all.go:31, 62831c8972de)
• PR adds the provider registration: The PR head imports internal/providers/githubcodespaces in the built-in provider registry, making this a real new built-in provider rather than docs-only cleanup. (internal/providers/all/all.go:32, 928f643a2398)
• Provider API surface: The provider advertises canonical name github-codespaces, aliases codespaces and gh-codespaces, Linux SSH-lease behavior, cleanup, and coordinator-never routing, which are user-facing compatibility decisions once shipped. (internal/providers/githubcodespaces/provider.go:21, 928f643a2398)
• Credentialed control plane: The backend uses GH_TOKEN, GITHUB_TOKEN, or gh auth token and creates/list/checks Codespaces through the GitHub API, so scoped auth and token redaction need real proof before merge. (internal/providers/githubcodespaces/backend.go:485, 928f643a2398)
• Repository-local config guard: The PR limits repository-local config from changing API URL, gh executable path, target repo, and delete-on-release policy unless the config path is trusted, which matches the stated safety goal but remains security-sensitive. (internal/cli/config.go:4832, 928f643a2398)

Likely related people:

• coygeek: Authored the current-main Vast.ai SSH lease provider and the initial GitHub Codespaces provider lifecycle commits on this PR branch. (role: recent provider contributor and proposed implementation owner; confidence: high; commits: 878b370a5526, 326ceb5aab84, 60ed3ae5dd14; files: internal/providers/vast, internal/providers/githubcodespaces, internal/cli/config.go)
• vincentkoc: Pushed branch repairs for unused wrappers, live-smoke wiring, auth-scope preflight, and the current provider matrix refresh while repeatedly documenting the missing live proof gate. (role: recent branch repair contributor and proof-gate reviewer; confidence: high; commits: a1408eb8f553, fbf75a1af28e, 074eff234d8b; files: internal/providers/githubcodespaces, scripts/live-smoke.sh, scripts/live-github-codespaces-smoke.sh)
• steipete: Authored the merged AWS Lambda MicroVM provider mentioned in the rebase history and added Codespaces default/release-policy hardening commits on this branch. (role: adjacent provider contributor and branch hardening contributor; confidence: medium; commits: 0301236b2752, d42770ca1a5c, fc23f36a52d5; files: internal/providers/githubcodespaces, internal/cli/config_test.go, CHANGELOG.md)

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.

[vincentkoc]

@clawsweeper re-review

Maintainer update on 2afc239e021e093fd021e2b09657d7831e7cb0ba:

• rebased the GitHub Codespaces provider branch onto current main
• fixed the CI Go/deadcode failure by removing unreachable helper wrappers from internal/providers/githubcodespaces/core.go
• regenerated the provider category matrix so the generated docs check stays in sync

Local validation:

go run golang.org/x/tools/cmd/deadcode@v0.45.0 -test ./...
go test ./internal/providers/githubcodespaces ./internal/providers/all ./internal/cli ./cmd/crabbox
node scripts/live-github-codespaces-smoke.test.js
node scripts/generate-provider-matrix.mjs --check
node scripts/check-command-docs.mjs
node scripts/check-docs-links.mjs
go vet ./...
go build -trimpath -o bin/crabbox ./cmd/crabbox

GitHub CI on the pushed head is green: Go, Apple VZ, Worker, Scripts, Docs, and Release Check all passed in https://github.com/openclaw/crabbox/actions/runs/28077485642.

Still not merging this yet: it remains gated by status: 📣 needs proof, merge-risk: 🚨 auth-provider, merge-risk: 🚨 compatibility, and merge-risk: 🚨 security-boundary. I do not have live GitHub Codespaces provider credentials/quota proof here, so this still needs real live create/status/run/ssh/release evidence before merge readiness.

[clawsweeper]

🦞🧹
ClawSweeper re-review requested.

I asked ClawSweeper to review this item again.
Action: item re-review queued (workflow sweep.yml, event repository_dispatch).
Result: the existing ClawSweeper review comment will be edited in place when the review finishes.

[vincentkoc]

Rebased this PR onto current main after #674 landed.

New head: 41ccc44ed02061a53eb20a55a848ed18aa91f352

Conflict resolution kept both AWS Lambda MicroVM and GitHub Codespaces in generated docs/source-map metadata. Provider matrix now reports 67 providers.

Local validation on the rebased head:

go test ./internal/providers/githubcodespaces ./internal/providers/all ./internal/cli ./cmd/crabbox
node --test scripts/live-github-codespaces-smoke.test.js
node scripts/generate-provider-matrix.mjs --check
node scripts/check-command-docs.mjs
node scripts/check-docs-links.mjs
go vet ./...
go run golang.org/x/tools/cmd/deadcode@v0.45.0 -test ./...
go build -trimpath -o bin/crabbox ./cmd/crabbox
git diff --check

Still not merging: live GitHub Codespaces create/status/run/ssh/release proof and auth/security/compatibility gates are still required.

[vincentkoc]

Public CI is green on rebased head 41ccc44ed02061a53eb20a55a848ed18aa91f352: https://github.com/openclaw/crabbox/actions/runs/28087205563

Green checks: Go, Apple VZ, Worker, Scripts, Docs, and Release Check. Merge state is clean.

Still not merging: status: 📣 needs proof plus auth-provider/compatibility/security-boundary labels remain, and this still needs redacted live GitHub Codespaces create/status/run/ssh/release proof.

[vincentkoc]

Maintainer proof update for github-codespaces shared live-smoke wiring.

Changed:

• wired CRABBOX_LIVE_PROVIDERS=github-codespaces|codespaces|gh-codespaces through scripts/live-smoke.sh to the guarded standalone Codespaces smoke
• added shared dispatch regression coverage that proves the shared smoke exits before provider mutation when the smoke repo is missing
• documented the shared operations entry point and provider prerequisites

Local validation at head 2eb4f8af:

• bash -n scripts/live-smoke.sh scripts/live-github-codespaces-smoke.sh
• node --test scripts/live-smoke.test.js scripts/live-github-codespaces-smoke.test.js
• go test ./internal/providers/githubcodespaces ./internal/providers/all ./internal/cli ./cmd/crabbox
• node scripts/check-docs-links.mjs
• node scripts/check-command-docs.mjs
• git diff --check

Still not claiming live provider proof from this machine because I do not have an authenticated Codespaces smoke repo/token here. The added path is meant to make that live proof one standard command once credentials are available.

@clawsweeper re-review

[clawsweeper]

🦞🧹
ClawSweeper re-review requested.

I asked ClawSweeper to review this item again.
Action: item re-review queued (workflow sweep.yml, event repository_dispatch).
Result: the existing ClawSweeper review comment will be edited in place when the review finishes.

[vincentkoc]

Public CI is now green on current head 2eb4f8afe67f3072bea093d085795641290acc9c: https://github.com/openclaw/crabbox/actions/runs/28098639697.

Green checks: Go, Apple VZ, Worker, Scripts, Docs, and Release Check.

Still not merging: authenticated GitHub Codespaces lifecycle proof remains missing, and status: 📣 needs proof plus auth/compat/security risk labels remain.

[vincentkoc]

@clawsweeper re-review

Updated the PR body with current-head validation evidence, full issue link, and the remaining authenticated live-proof gate. No code changes in this update.

Still not merging unless the live Codespaces proof labels clear and the auth/compat/security gates are satisfied.

[vincentkoc]

@clawsweeper re-review

Follow-up maintainer repair pushed in a96ae6283bac22de7fce0f091fe7035d9cf32a7f.

What changed:

• GitHub API 401/403 errors now explicitly call out the required codespace scope and the gh auth refresh -h github.com -s codespace fix.
• scripts/live-github-codespaces-smoke.sh now runs gh codespace list --limit 1 as a non-mutating scope preflight after gh auth status.
• Missing scope exits as classification=credential_bound ... reason=github_codespaces_scope_missing before any provider mutation.
• Docs and tests cover the new preflight.

Local validation:

• go test ./internal/providers/githubcodespaces ./internal/providers/all ./internal/cli ./cmd/crabbox
• node --test scripts/live-github-codespaces-smoke.test.js scripts/live-smoke.test.js
• bash -n scripts/live-smoke.sh scripts/live-github-codespaces-smoke.sh
• node scripts/check-docs-links.mjs
• node scripts/check-command-docs.mjs
• go vet ./...
• go build -trimpath -o bin/crabbox ./cmd/crabbox
• git diff --check

Local live-auth preflight with the current maintainer auth is credential-bound, as expected:

classification=credential_bound command=gh\ codespace\ list\ --limit\ 1 exit=1 reason=github_codespaces_scope_missing
error getting codespaces: HTTP 403: Must have admin rights to Repository. (https://api.github.com/user/codespaces?per_page=1)
This API operation needs the "codespace" scope. To request it, run:  gh auth refresh -h github.com -s codespace

crabbox doctor --provider github-codespaces --github-codespaces-repo openclaw/crabbox now surfaces the same actionable scope hint.

Public CI is green on a96ae6283bac22de7fce0f091fe7035d9cf32a7f: https://github.com/openclaw/crabbox/actions/runs/28107119948. Green checks: Go, Apple VZ, Worker, Scripts, Docs, and Release Check.

Still not merge-ready: this proves the local auth blocker and improves the proof harness, but it is not a live Codespaces create/run/ssh/release proof. The PR still needs redacted authenticated lifecycle proof and explicit auth/compat/security acceptance.

[clawsweeper]

🦞🧹
ClawSweeper re-review requested.

I asked ClawSweeper to review this item again.
Action: item re-review queued (workflow sweep.yml, event repository_dispatch).
Result: the existing ClawSweeper review comment will be edited in place when the review finishes.

[vincentkoc]

@clawsweeper re-review

Updated the PR body to current head a96ae6283bac22de7fce0f091fe7035d9cf32a7f and current green public CI: https://github.com/openclaw/crabbox/actions/runs/28107119948

No code changes in this update. Remaining gate is still redacted authenticated GitHub Codespaces lifecycle proof; my current GitHub token lacks the codespace scope, so I cannot produce that live proof non-interactively from here.