feat: add channel purpose lines

[PollyBot13]

Closes #118

What Problem This Solves

Channels currently show only their name and structural metadata, so people entering operational, project, incident, or agent-created rooms must search the timeline to understand what the room is for.

Why This Change Was Made

Adds one optional, plain-text channel purpose across SQLite and PostgreSQL storage, HTTP/OpenAPI/TypeScript SDK contracts, and the main and embedded channel headers. Values are trimmed, limited to 280 Unicode code points, reject control characters and line breaks, render as text, and reuse the existing channel create/update authorization and channel.updated refetch path.

User Impact

Visible channel members can read a compact Purpose line immediately, expand long values, and see updates or clearing in open main-app and embed views without reloading. Existing channels and older clients remain compatible because the field is additive and optional.

Evidence

Exact reviewed head: 3deb9e98d3a6ca51b3f145e219ec886b70f784a1, rebased onto main at 7fd4cd1d01afe230b01eea4948e64eeecf0d5216.

• umask 022; pnpm check — passed.
• pnpm generate:sqlc and pnpm build — passed; generated database and embedded web output are current after the rebase.
• Focused SQLite, PostgreSQL, and HTTP API tests — passed.
• pnpm exec playwright test tests/e2e/channel-purpose.spec.ts --workers=1 — 1 passed.
• git diff --check origin/main...HEAD — passed.
• Independent final diff review — no actionable findings.

Inspectable real-app proof

The proof uses the production web bundle, the real Go API, a fresh SQLite database, and explicit local-development authentication. It creates a channel with an initial purpose, opens the main and embedded views together, updates the value through the real API, verifies both open views refresh through channel.updated without reload, then clears it and verifies both surfaces remove it in realtime. Generated identifiers are used; no hosted token, private endpoint, or user data is included.

• Reproduction notes and assertions
• Updated purpose in the main app
• Updated purpose in the embedded channel
• Purpose cleared in realtime

AI assistance: implementation, tests, and review were AI-assisted; the final diff was independently reviewed and all findings were resolved.

[PollyBot13]

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

Re-review progress:

• State: Review in progress
• Detail: The exact-review queue leased this run; Codex is reviewing the item.
• Run: https://github.com/openclaw/clawsweeper/actions/runs/30124919224
• Updated: 2026-07-24T20:40:18.090Z

[clawsweeper]

Codex review: found issues before merge. Reviewed August 2, 2026, 3:13 AM ET / 07:13 UTC.

ClawSweeper review

What this changes

Adds an optional channel purpose field across SQLite/PostgreSQL storage, HTTP/OpenAPI/TypeScript SDK contracts, and the main and embedded channel headers.

Merge readiness

⚠️ Needs maintainer review before merge - 6 items remain

The PR has convincing real-app proof for its proposed UI, but it is not mergeable as written: its SQLite and PostgreSQL migration filenames collide with current main’s display-title migrations, and a maintainer must decide whether a distinct persisted purpose belongs beside display_title. Likely related people: steipete (high confidence).

Priority: P3
Reviewed head: 3deb9e98d3a6ca51b3f145e219ec886b70f784a1
Owner decision: Required. See Decision needed.

Review scores

Measure	Result	What it means
Overall readiness	🦐 gold shrimp (3/6)	The PR has strong real-app proof, but current-main migration and metadata-contract conflicts make the patch unready to merge.
Proof confidence	🦞 diamond lobster (5/6) ✨ media proof bonus	Sufficient (screenshot): Prepared screenshots show the updated purpose in main and embedded headers and its removal after clearing, while the branch proof notes identify a real API, production web bundle, fresh SQLite database, and E2E run.
Patch quality	🦐 gold shrimp (3/6)	2 actionable review findings remain.

Verification

Check	Result	Evidence
Real behavior	Verified	Sufficient (screenshot): Prepared screenshots show the updated purpose in main and embedded headers and its removal after clearing, while the branch proof notes identify a real API, production web bundle, fresh SQLite database, and E2E run.
Evidence reviewed	5 items	Repository policy: The full repository AGENTS.md requires schema/query edits to be followed by sqlc generation; generated storedb code is not a hand-maintained source surface. Migration collision: Current main already contains SQLite 0039_channel_display_title.sql and PostgreSQL 0032_channel_display_title.sql; this branch introduces description migrations with those exact filenames. Existing upgraded databases record the display-title filenames as applied, so the description column would not be installed. Current-main contract comparison: Current main’s display-title merge owns the same channel metadata/header surface. The branch-versus-main path comparison deletes those current migration paths while adding same-number description migrations, confirming the branch predates rather than preserves the current contract.
Findings	2 actionable findings	[P1] Allocate unused migration numbers after rebasing [P1] Resolve the overlapping channel metadata contract
Security	None	None.

How this fits together

ClickClack channel creation and updates pass through the HTTP API into SQLite or PostgreSQL, then return channel metadata to the web application and embedded channel view. This change adds optional channel metadata that the headers render after the existing update/refetch flow.

flowchart LR
  A[Authorized channel update] --> B[HTTP channel API]
  B --> C[Purpose validation]
  C --> D[SQLite or PostgreSQL]
  D --> E[Channel response and update event]
  E --> F[Main channel header]
  E --> G[Embedded channel header]

Loading

Decision needed

Question	Recommendation
Should ClickClack expose an independently persisted channel purpose in addition to the existing display_title, or keep a single channel-context contract?	Keep one channel context contract: Use display_title as the sole visible channel metadata field and avoid a second overlapping persisted API field.

Why: Both fields are optional metadata shown in the same public channel-header path, but current main’s display-title behavior supplies an overlapping newer contract. Source evidence cannot determine the intended long-term product model.

Before merge

• Allocate unused migration numbers after rebasing (P1) - Current main already has 0039_channel_display_title.sql in SQLite and 0032_channel_display_title.sql in PostgreSQL. An upgraded database records those names as applied, so this branch’s description migrations would never add their columns while its queries select them; rebase and use unused numbers before regenerating sqlc output.
• Resolve the overlapping channel metadata contract (P1) - This adds description to the same public channel API and headers where current main now exposes display_title. Because the branch predates that merged design, preserve the current field and obtain maintainer approval for separate semantics before introducing a parallel context field.
• Resolve merge risk (P1) - An upgraded database would have the display-title migration filenames recorded already, so this branch’s description column would be absent while its generated queries expect it.
• Resolve merge risk (P1) - A separate public description field beside current display_title would create overlapping channel-context semantics unless maintainers explicitly approve the distinction.
• Complete next step (P2) - A maintainer must first decide the public channel-metadata model; only then is a safe mechanical rebase possible.

Findings

• [P1] Allocate unused migration numbers after rebasing — apps/api/internal/store/sqlite/migrations/0039_channel_description.sql:1
• [P1] Resolve the overlapping channel metadata contract — apps/api/internal/store/types.go:220

Agent review details

Security

None.

Review metrics

Metric	Value	Why it matters
Changed surface	58 files; 604 added, 107 removed	The proposal crosses stored data, generated bindings, HTTP/OpenAPI/SDK contracts, web UI, tests, docs, and built assets.
Storage migrations	2 added	Both filenames collide with current-main display-title migrations, so upgrade safety is the central merge concern.

Merge-risk options

Maintainer options:

1. Rebase after distinct-field approval (recommended)
   If a separate purpose is approved, rename both migrations to unused numbers after rebasing, preserve display-title behavior, regenerate sqlc, and test upgrades from an existing display-title database.
2. Avoid a parallel metadata contract
   If display titles are intended to remain the sole channel context surface, pause this PR and limit any follow-up to that supported contract.

Copy recommended automerge instruction

@clawsweeper automerge

Special instructions:
Rebase onto current main; allocate unused SQLite and PostgreSQL migration numbers; preserve display_title alongside description; regenerate sqlc output; add upgrade tests for databases that already applied display-title migrations.

Technical review

Best possible solution:

Decide whether purpose is a distinct channel contract; if approved, rebase onto current main, assign fresh migration numbers in both stores, preserve display_title, regenerate sqlc output, and prove fresh-install and display-title-upgrade behavior.

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

Not applicable as a bug: the prepared screenshots and E2E notes demonstrate the requested feature in a real local setup, while current main does not offer a channel purpose line.

Is this the best way to solve the issue?

No: the feature path is coherent in isolation, but this branch is unsafe on current main and the relationship to display_title remains an unresolved product decision.

Full review comments:

• [P1] Allocate unused migration numbers after rebasing — apps/api/internal/store/sqlite/migrations/0039_channel_description.sql:1
  Current main already has 0039_channel_display_title.sql in SQLite and 0032_channel_display_title.sql in PostgreSQL. An upgraded database records those names as applied, so this branch’s description migrations would never add their columns while its queries select them; rebase and use unused numbers before regenerating sqlc output.
  Confidence: 0.99
• [P1] Resolve the overlapping channel metadata contract — apps/api/internal/store/types.go:220
  This adds description to the same public channel API and headers where current main now exposes display_title. Because the branch predates that merged design, preserve the current field and obtain maintainer approval for separate semantics before introducing a parallel context field.
  Confidence: 0.95

Overall correctness: patch is incorrect
Overall confidence: 0.98

AGENTS.md: found and applied where relevant.

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

Labels

Label justifications:

• P3: This is an optional channel-context capability, not a regression or urgent workflow failure.
• merge-risk: 🚨 compatibility: The patch changes persisted channel metadata and public API/SDK behavior, and its migration filenames overlap migrations already applied on main.
• rating: 🦐 gold shrimp: Overall readiness is 🦐 gold shrimp; proof is 🦞 diamond lobster and patch quality is 🦐 gold shrimp.
• status: ⏳ waiting on author: ClawSweeper has contributor-facing work open and is waiting for author action. Sufficient (screenshot): Prepared screenshots show the updated purpose in main and embedded headers and its removal after clearing, while the branch proof notes identify a real API, production web bundle, fresh SQLite database, and E2E run.
• proof: sufficient: Contributor real behavior proof is sufficient. Prepared screenshots show the updated purpose in main and embedded headers and its removal after clearing, while the branch proof notes identify a real API, production web bundle, fresh SQLite database, and E2E run.
• proof: 📸 screenshot: Contributor real behavior proof includes screenshot evidence. Prepared screenshots show the updated purpose in main and embedded headers and its removal after clearing, while the branch proof notes identify a real API, production web bundle, fresh SQLite database, and E2E run.

Evidence

What I checked:

• Repository policy: The full repository AGENTS.md requires schema/query edits to be followed by sqlc generation; generated storedb code is not a hand-maintained source surface. (AGENTS.md:3, b8293987baa5)
• Migration collision: Current main already contains SQLite 0039_channel_display_title.sql and PostgreSQL 0032_channel_display_title.sql; this branch introduces description migrations with those exact filenames. Existing upgraded databases record the display-title filenames as applied, so the description column would not be installed. (apps/api/internal/store/sqlite/migrations/0039_channel_display_title.sql:1, b8293987baa5)
• Current-main contract comparison: Current main’s display-title merge owns the same channel metadata/header surface. The branch-versus-main path comparison deletes those current migration paths while adding same-number description migrations, confirming the branch predates rather than preserves the current contract. (apps/api/internal/store/types.go:220, 3deb9e98d3a6)
• Feature history: The adjacent display-title behavior appears to date to the merged display-title feature commit. (apps/api/internal/store/sqlite/migrations/0039_channel_display_title.sql:1, e455d43809a0)
• Real behavior proof: Prepared screenshots visibly show the updated purpose in both main and embedded headers and its absence after clearing. The proof notes describe a production web bundle, real Go API, fresh SQLite database, and an E2E scenario that persists, updates, and clears the field. (docs/proof/channel-purpose-proof.md:1, 3deb9e98d3a6)

Likely related people:

• steipete: Merged the display-title feature on current main, which owns the overlapping channel metadata and header contract. (role: introduced adjacent channel presentation behavior; confidence: high; commits: e455d43809a0; files: apps/api/internal/httpapi/server.go, apps/api/internal/store/types.go, apps/api/internal/store/sqlite/migrations/0039_channel_display_title.sql)

Rank-up moves

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

• Rebase onto current main and allocate unused SQLite/PostgreSQL migration numbers.
• Obtain a maintainer decision on separate purpose versus display-title semantics.
• Demonstrate upgrade behavior from a database that already applied display-title migrations.

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 (28 earlier review cycles; latest 8 shown)

• reviewed 2026-08-01T09:34:57.421Z sha 3deb9e9 :: needs real behavior proof before merge. :: [P1] Preserve the current display-title contract | [P1] Renumber the colliding database migrations
• reviewed 2026-08-01T11:27:17.090Z sha 3deb9e9 :: needs real behavior proof before merge. :: [P1] Renumber the colliding database migrations | [P1] Preserve the current display-title contract | [P1] Avoid a parallel channel-context API without approval
• reviewed 2026-08-01T12:27:13.152Z sha 3deb9e9 :: needs real behavior proof before merge. :: [P1] Renumber the colliding database migrations | [P1] Preserve the current display-title contract | [P1] Get approval for a second channel-context field
• reviewed 2026-08-01T14:52:27.732Z sha 3deb9e9 :: found issues before merge. :: [P1] Renumber the colliding database migrations | [P1] Preserve the current display-title contract | [P1] Get approval for a second channel-context field
• reviewed 2026-08-01T17:34:29.017Z sha 3deb9e9 :: found issues before merge. :: [P1] Rebase and allocate new channel migration numbers | [P1] Resolve whether purpose is a second public channel contract
• reviewed 2026-08-01T20:14:33.110Z sha 3deb9e9 :: found issues before merge. :: [P1] Allocate new migration numbers after rebasing | [P1] Preserve the current display-title contract
• reviewed 2026-08-01T23:48:29.395Z sha 3deb9e9 :: found issues before merge. :: [P1] Allocate new migration numbers after rebasing | [P1] Preserve the display-title channel contract
• reviewed 2026-08-02T05:09:02.379Z sha 3deb9e9 :: found issues before merge. :: [P1] Allocate unused migration numbers after rebasing | [P1] Preserve the display-title channel contract

[PollyBot13]

@clawsweeper re-review

Proof and validation have been refreshed for exact head 3deb9e98d3a6ca51b3f145e219ec886b70f784a1; the PR body now links the inspectable real-app artifacts.

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

Re-review progress:

• State: Review in progress
• Detail: The exact-review queue leased this run; Codex is reviewing the item.
• Run: https://github.com/openclaw/clawsweeper/actions/runs/30149478238
• Updated: 2026-07-25T07:32:37.851Z

[steipete]

Closing after maintainer review because this branch conflicts with the current channel display-title migration and omits the display-title behavior now on main. Landing it would create overlapping schema and naming contracts rather than a coherent additive feature.

If a separate purpose-name concept is approved, it should be implemented from a fresh branch with a deliberately distinct contract. That product decision remains tracked in #118. Thanks for the contribution and the useful exploration.