feat: catalog-only image promotion and a Telegram Desktop variant image

[obviyus]

What Problem This Solves

Resolves a problem where OpenClaw's Telegram Desktop proof lanes had to install ~20 apt packages, download Telegram Desktop from telegram.org, and download TDLib on every fresh Linux desktop lease. That per-lease bootstrap added minutes and raced Ubuntu's unattended-upgrades (Could not get lock /var/lib/dpkg/lock-frontend) — the leading failure in the last runs of https://github.com/openclaw/openclaw/actions/workflows/mantis-telegram-desktop-proof.yml.

It also fixes a gap that made a safe variant image impossible: crabbox image promote always rewrote the scoped default together with the capability catalog, so any variant would silently become every matching lease's image.

Why This Change Was Made

Telegram Desktop is a stable machine capability that only some lanes need, so it ships as a catalog-only variant image, never in the generic desktop default:

• crabbox image promote --catalog-only (AWS): writes only the capability-catalog record and never the scoped default. A catalog-only image is eligible only for leases that name one of its declared --sdk/--runtime capabilities (warmup --image-sdk telegram-desktop=7.0.9); generic requests such as --image-require-desktop or --image-min-os never see it even though the variant also declares desktop, so existing capability-aware leases are unaffected. --catalog-only therefore requires ≥1 --sdk/--runtime declaration (CLI + Worker reject otherwise); Azure rejects the flag; existing image promote calls are unchanged. Mixed versions fail closed: catalog-only uses a dedicated POST /v1/images/<id>/promote-catalog route, so an older coordinator answers 404 and the CLI stops before anything is promoted (it also refuses a response that does not confirm catalogOnly). Generic primitive — reusable for any future variant.
• scripts/install-linux-developer-tools.sh: CRABBOX_LINUX_TELEGRAM_DESKTOP=1 (default 0; the generic bake is unchanged) installs checksum-pinned Telegram Desktop 7.0.9 to /opt/Telegram, removes its Updater, writes /var/lib/crabbox/telegram-desktop-version, and adds zbar-tools/x11-utils plus the xcb/xkb runtime libs. amd64 only; other architectures skip and omit the marker.
• scripts/mint-aws-devtools-image.sh --telegram-desktop (Linux, desktop required): bakes crabbox-linux-devtools-telegram-<id>, smokes the Telegram contract, promotes --catalog-only --desktop --sdk telegram-desktop=7.0.9, then proves both that a --image-sdk telegram-desktop=7.0.9 lease selects the new AMI and that a plain lease still selects the previous default (default-unchanged proof lease).
• devtools-image-publish gains a telegram_desktop boolean input (default false); the generic path is byte-identical when false.

Consumers opt in per lease with crabbox warmup --desktop --image-sdk telegram-desktop=7.0.9; Crabbox refuses the lease if no such image is promoted. No TDLib, no login state, no scenario data in the image.

User Impact

Generic Crabbox desktop leases are unaffected. Operators can publish variant images without touching the default. Lanes that ask for the Telegram capability boot with Telegram Desktop ready and skip per-lease apt/download work; OpenClaw's recorder preflights the contract and starts recording in seconds.

Evidence

Real amd64 lease proof of the bake path (promoted crabbox-devtools-v1 desktop image, c7a.8xlarge, lease cbx_35253c1cee3e, released):

• Baseline on the current promoted image: telegram-absent, no-zbarimg.

• Prep script with the gate on → exit 0 in 1m40s; print_versions ends with telegram-desktop=7.0.9.

• Recorder preflight on the same lease:

  binary: ok            (/opt/Telegram/Telegram executable)
  updater removed: ok
  marker: 7.0.9
  wmctrl/xdotool/scrot/ffmpeg/zbarimg/xdpyinfo: ok
  DISPLAY :99: ok
  

• Launch: /opt/Telegram/Telegram -noupdate -workdir … → wmctrl -lx: Telegram.TelegramDesktop … Telegram; screenshot (intro screen, no login QR/token in frame):

  

Local, on the combined head:

• npm test --prefix worker → 37 files passed, 2 skipped; 1359 tests passed, 3 skipped — includes: catalog-only writes the catalog key only; default selection unchanged after a catalog-only promotion; --image-sdk selection returns the catalog-only image; --image-require-desktop alone still selects the older generic default even though a newer catalog-only variant declares desktop, and adding --image-sdk telegram-desktop=7.0.9 selects the variant; catalog-only with only generic capabilities (desktop) → 400 catalog_only_capabilities_required; re-promoting a catalog-only variant as the default clears the marker and generic requests select it again ; the promote-catalog route writes no default record (1361 tests).
• go test ./internal/cli/... → ok (--catalog-only parsing/serialization on the promote-catalog route; missing or generic-only capabilities exit 2; Azure rejects; older coordinator → 404 → CLI error without falling back to /promote; coordinator that ignores the marker → CLI refuses).
• node --test scripts/install-linux-developer-tools.test.js scripts/mint-aws-devtools-image.test.js scripts/devtools-image-workflow.test.js → 34 passed, 0 failed.
• shellcheck (koalaman/shellcheck:v0.10.0) on both scripts → clean; worker format:check/lint/check clean.
• Tarball digest re-verified: sha256sum tsetup.7.0.9.tar.xz = d3c05df0259ab116d11d8c1cdc1403019d2a3be303ad3b46d16a84e19df6615f; upstream latest tag v7.0.9.

Known proof gap: catalog-only promotion and selection against a deployed coordinator cannot run before this Worker code is deployed; the storage/selection logic is covered by the Worker tests above, and the first post-merge devtools-image-publish telegram_desktop=true run asserts both --image-sdk telegram-desktop=7.0.9 selection of the new AMI and the default-unchanged plain-lease proof (scripts/mint-aws-devtools-image.sh) — that log will be attached here.

[clawsweeper]

🦞👀
ClawSweeper picked this up.

Pull request received. I will update this pull request when review starts.

[clawsweeper]

Codex review: needs real behavior proof before merge. Reviewed August 15, 2026, 12:07 PM ET / 16:07 UTC.

ClawSweeper review

What this changes

This PR adds an AWS-only --catalog-only image-promotion mode and an opt-in Linux image variant containing Telegram Desktop.

Merge readiness

⛔ Blocked until stronger real behavior proof is added - 5 items remain

Keep open: current main does not contain this feature, and the branch fixes the earlier fail-closed concern. Before merge, the new public image-promotion contract needs maintainer sponsorship and real coordinator-bound proof that the variant is selected without changing the default.

Priority: P2
Reviewed head: 63638711a66597ea9ec0326d34978a5f12003809
Owner decision: Required. See Decision needed.

Review scores

Measure	Result	What it means
Overall readiness	🦐 gold shrimp (3/6)	The patch has substantial focused coverage and a real bake proof, but the unproven coordinator boundary remains a merge gate.
Proof confidence	🦐 gold shrimp (3/6)	Needs stronger real behavior proof before merge: A real AWS lease screenshot proves the baked client launches, but the PR itself confirms that catalog-only promotion and default-preserving selection have not run against a deployed coordinator; attach redacted live logs or a recording after that run. 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.
Patch quality	🐚 platinum hermit (4/6)	No actionable review findings were identified.

Verification

Check	Result	Evidence
Real behavior	Needs proof	Needs stronger real behavior proof before merge: A real AWS lease screenshot proves the baked client launches, but the PR itself confirms that catalog-only promotion and default-preserving selection have not run against a deployed coordinator; attach redacted live logs or a recording after that run. 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	6 items	Current main lacks the proposed feature: A current-tree search found no catalog-only promotion route, flag, marker, or Telegram Desktop variant implementation, so this PR still supplies a distinct capability. Current selection path establishes the compatibility boundary: Current main combines the scoped default with catalog entries for capability requests and chooses the newest matching image; the PR’s catalog-only eligibility guard therefore protects an established selection path. PR includes the fail-closed coordinator boundary: The supplied PR diff adds a distinct promotion route and makes the CLI reject an older coordinator’s 404 or a response that does not confirm catalog-only status; this addresses the prior P1 finding.
Findings	None	None.
Security	None	None.

How this fits together

Crabbox’s CLI asks the Worker coordinator to record provider images, and lease requests then select a compatible default or catalog image. This change adds a catalog-only path so a capability-specific AWS image can be selected only by an explicit SDK/runtime request while ordinary leases retain their default image.

flowchart LR
  A[Image publisher] --> B[Crabbox CLI]
  B --> C[Coordinator promotion route]
  C --> D[AWS image catalog]
  E[Lease capability request] --> F[Image selection]
  D --> F
  F --> G[Remote desktop lease]

Loading

Decision needed

Question	Recommendation
Should Crabbox adopt --catalog-only as a supported public AWS image-promotion contract, contingent on deployed-coordinator proof?	Sponsor the generic contract: Accept the reusable AWS capability-variant API after a safe deployed-coordinator trace proves explicit selection and default preservation.

Why: This is a new operator-facing CLI, Worker route, and persisted image-record behavior; code review cannot decide whether that API surface is a maintained product commitment.

Before merge

• Add real behavior proof - Needs stronger real behavior proof before merge: A real AWS lease screenshot proves the baked client launches, but the PR itself confirms that catalog-only promotion and default-preserving selection have not run against a deployed coordinator; attach redacted live logs or a recording after that run. 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.
• Resolve merge risk (P1) - The new catalog-only record and selection behavior have not been exercised through a deployed coordinator, so the central no-default-change guarantee is not yet proven at the production boundary.
• Resolve merge risk (P1) - --catalog-only creates a durable public CLI and coordinator contract; maintainers must deliberately own its long-term compatibility semantics.
• Complete next step (P2) - A maintainer must sponsor the new public contract and require deployed-boundary proof; there is no narrow mechanical repair for automation to make.

Agent review details

Security

None.

Review metrics

Metric	Value	Why it matters
Change surface	17 files; +1,226, -53	The PR spans CLI, coordinator, image baking, workflow, documentation, and tests.
Implementation versus tests	production/docs +398, tests +828	The branch has substantial focused coverage, but tests do not replace the missing deployed-coordinator proof.

Root-cause cluster

Relationship: canonical
Canonical: #1349
Summary: This PR subsumes the catalog-only work from the related closed, unmerged PR and adds the Telegram Desktop variant consumer.

Members:

• superseded: feat: catalog-only image promotion for capability variants #1350 - Its catalog-only promotion scope is incorporated into this PR, while the earlier PR is closed unmerged.

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

Merge-risk options

Maintainer options:

1. Require deployed-boundary proof (recommended)
   Run the promotion against a safe deployed coordinator, then attach redacted logs showing the explicit SDK lease selects the variant and a plain lease keeps the previous default.
2. Defer the public promotion contract
   Pause this PR if maintainers do not want to support catalog-only records and selection rules as an operator-facing compatibility commitment.

Technical review

Best possible solution:

Keep catalog-only promotion as a narrowly documented AWS capability-variant contract, after a staging or controlled deployed-coordinator run proves both explicit variant selection and an unchanged ordinary default.

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

No: the real lease screenshot verifies the opt-in bake and launch, but no deployed coordinator trace yet reproduces catalog-only promotion followed by both variant and ordinary lease selection.

Is this the best way to solve the issue?

Unclear: the implementation is narrowly aligned with the existing catalog selection path, but maintainers must first accept the new public contract and require proof at the coordinator boundary.

AGENTS.md: found and applied where relevant.

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

Labels

Label changes:

• remove mantis: telegram-visible-proof: Current Telegram visible-proof status is not_needed.

Label justifications:

• P2: This is a useful but bounded image-publishing capability whose remaining blocker is merge confidence rather than an active outage.
• merge-risk: 🚨 compatibility: The PR adds a public promotion mode and changes how persisted catalog images participate in lease selection.
• rating: 🦐 gold shrimp: Overall readiness is 🦐 gold shrimp; proof is 🦐 gold shrimp and patch quality is 🐚 platinum hermit.
• status: 📣 needs proof: The PR needs real behavior proof before ClawSweeper can clear the contributor ask. Needs stronger real behavior proof before merge: A real AWS lease screenshot proves the baked client launches, but the PR itself confirms that catalog-only promotion and default-preserving selection have not run against a deployed coordinator; attach redacted live logs or a recording after that run. 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.
• proof: 📸 screenshot: Contributor real behavior proof includes screenshot evidence. A real AWS lease screenshot proves the baked client launches, but the PR itself confirms that catalog-only promotion and default-preserving selection have not run against a deployed coordinator; attach redacted live logs or a recording after that run.

Evidence

What I checked:

• Current main lacks the proposed feature: A current-tree search found no catalog-only promotion route, flag, marker, or Telegram Desktop variant implementation, so this PR still supplies a distinct capability. (internal/cli/image.go:47, f85159d989fb)
• Current selection path establishes the compatibility boundary: Current main combines the scoped default with catalog entries for capability requests and chooses the newest matching image; the PR’s catalog-only eligibility guard therefore protects an established selection path. (worker/src/fleet.ts:24379, f85159d989fb)
• PR includes the fail-closed coordinator boundary: The supplied PR diff adds a distinct promotion route and makes the CLI reject an older coordinator’s 404 or a response that does not confirm catalog-only status; this addresses the prior P1 finding. (internal/cli/coordinator.go:1824, 63638711a665)
• Real proof is incomplete at the changed boundary: The PR body includes a real AWS lease bake, preflight, and launch screenshot, but explicitly says catalog-only promotion and selection against a deployed coordinator have not yet run. (63638711a665)
• Recent selection-path owner: Peter Steinberger most recently changed the coordinator’s adjacent lease/provider path on current main. (worker/src/fleet.ts:24366, fda80796fa81)
• Release/main check: The latest release is v0.42.0 at 13f20f8; current main is later at f85159d and neither contains this unmerged PR feature. (f85159d989fb)

Likely related people:

• Peter Steinberger: Recent current-main history on the adjacent image/lease selection surface includes the provider-bound lease mutation work. (role: recent coordinator contributor; confidence: medium; commits: fda80796fa81; files: worker/src/fleet.ts)

Rank-up moves

Optional improvements that raise the rating; they are not merge blockers.

• Attach redacted deployed-coordinator evidence for catalog-only promotion, explicit SDK selection, and unchanged ordinary-default selection.
• Obtain maintainer confirmation that the new public CLI and persisted catalog contract should be supported.

Rating scale

Score	Internal tier	Crab rank	Meaning
6/6	S	🦀 challenger crab	Exceptional readiness
5/6	A	🦞 diamond lobster	Very strong readiness
4/6	B	🐚 platinum hermit	Good normal PR; ordinary maintainer review
3/6	C	🦐 gold shrimp	Useful, but confidence is limited
2/6	D	🦪 silver shellfish	Proof or implementation needs work
1/6	F	🧂 unranked krab	Not merge-ready
N/A	NA	🌊 off-meta tidepool	Rating does not apply

Overall follows the weaker of proof and patch quality.
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.

Workflow

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

History

Review history (6 earlier review cycles)

• reviewed 2026-08-15T12:05:57.793Z sha 276ac44 :: needs real behavior proof before merge. :: none
• reviewed 2026-08-15T12:36:44.591Z sha 276ac44 :: needs maintainer review before merge. :: none
• reviewed 2026-08-15T14:28:30.606Z sha 569e6a7 :: needs real behavior proof before merge. :: [P1] Gate the variant on catalog-only support
• reviewed 2026-08-15T14:33:36.774Z sha fe42b93 :: needs real behavior proof before merge. :: [P1] Preserve the default before catalog-only variants
• reviewed 2026-08-15T15:11:00.918Z sha 0cc5504 :: needs real behavior proof before merge. :: [P1] Clear the catalog-only marker on normal promotion
• reviewed 2026-08-15T15:34:38.603Z sha 91f1116 :: needs real behavior proof before merge. :: [P1] Fail closed against older coordinators

[obviyus]

@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 exact_review_queue).
Result: when the review finishes, ClawSweeper will create the durable review comment if needed or update the existing comment in place.

[obviyus]

@clawsweeper re-review

[clawsweeper]

🦞👀
Exact review queued.

Re-review progress:

• State: Complete
• Detail: A newer review tuple already exists; this stale result was superseded.
• Run: https://github.com/openclaw/clawsweeper/actions/runs/31890063345
• Updated: 2026-08-15T14:30:08.169Z

[obviyus]

@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 exact_review_queue).
Result: when the review finishes, ClawSweeper will create the durable review comment if needed or update the existing comment in place.

Re-review progress:

• State: Complete
• Detail: The durable review result and its route handoff completed.
• Run: https://github.com/openclaw/clawsweeper/actions/runs/31890310122
• Updated: 2026-08-15T14:35:22.549Z

[obviyus]

@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 exact_review_queue).
Result: when the review finishes, ClawSweeper will create the durable review comment if needed or update the existing comment in place.

[obviyus]

@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 exact_review_queue).
Result: when the review finishes, ClawSweeper will create the durable review comment if needed or update the existing comment in place.

Re-review progress:

• State: Complete
• Detail: The durable review result and its route handoff completed.
• Run: https://github.com/openclaw/clawsweeper/actions/runs/31893161736
• Updated: 2026-08-15T15:36:17.497Z

[obviyus]

@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 exact_review_queue).
Result: when the review finishes, ClawSweeper will create the durable review comment if needed or update the existing comment in place.

Re-review progress:

• State: Complete
• Detail: A newer review tuple already exists; this stale result was superseded.
• Run: https://github.com/openclaw/clawsweeper/actions/runs/31894433321
• Updated: 2026-08-15T16:03:18.746Z