Improve channel resolution and ambiguity handling

[joshka]

Parent: #100

Related Gitcrawl context: openclaw/gitcrawl#81

Observed Workflow

While using Discrawl through Codex, channel-name resolution was sometimes brittle. A bare channel name like help could be ambiguous or collide with command/help parsing expectations, while using the numeric channel id worked reliably.

A local helper eventually encoded the numeric channel id for a common #help workflow, which made repeated queries much more reliable.

Current Workaround

The current workaround is to remember or manually discover numeric channel ids, then use those ids in discrawl search and discrawl messages.

This is reliable once known, but it makes repeated agent workflows depend on external notes or project-specific helper scripts.

Request

Improve channel resolution and ambiguity handling.

Example shape:

discrawl channels resolve help --json
discrawl search --channel help --explain-resolution "query"
discrawl messages --channel help --last 40

Useful Behavior

• if a channel name is ambiguous, print matching guild/channel ids instead of failing tersely
• prefer exact id matches when the input is numeric
• show which channel was selected in JSON output
• include enough context for Codex to retry with the right id
• document that numeric ids are the safest stable input for repeated workflows

Why This Matters

Codex-assisted archive use works better when command failures provide the next exact command. Ambiguous channel names are common in Discord, and a generic local archive tool should make it easy to move from "I know the visible name" to "I have the stable id."

Acceptance Criteria

• A command can resolve channel names to ids in JSON.
• Ambiguous name errors include candidate ids.
• Query commands expose selected channel id/name in JSON output where practical.
• Docs recommend numeric ids for repeatable agent workflows.

---

Prepared with Codex, confirmed as accurate by human.

[clawsweeper]

Codex review: keeping this open for maintainer follow-up; there is still a little grit to resolve. Reviewed June 25, 2026, 12:35 PM ET / 16:35 UTC.

Summary
Keep open: current main still has only channels list/show plus loose id/name/partial query filters, but no resolver command, ambiguity candidate diagnostics, selected-channel resolution envelope, or merged docs covering numeric ids for repeatable workflows.

Reproducibility: not applicable. as a bug reproduction; this is a feature request for a resolver and output contract. Source inspection confirms current main lacks that resolver surface.

Root-cause cluster
Relationship: canonical
Canonical: #104
Summary: This issue is the narrow channel-resolution tracker; the parent workflow issue and docs PR overlap but do not replace the resolver work.

Members:

• partial_overlap: Track initial local Discord maintainer-archive use friction #100 - The parent tracker records the broader maintainer-archive friction and names channel ambiguity as one slice.
• partial_overlap: Document initial local maintainer-archive workflows #106 - The docs issue covers workflow guidance including numeric channel ids, but it does not request a resolver implementation.
• partial_overlap: Document maintainer archive workflows #107 - The open PR is docs-only and may cover stable channel-id guidance, but it does not add resolver commands or query ambiguity handling.

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

Ways to help us reproduce this

• Add a screenshot or short recording showing the behavior.
• Add expected vs actual behavior.

Next step
Manual review should settle the resolver subcommand, optional explain flag, and JSON/error contract before a fix PR is queued.

Review details

Best possible solution:

Define one shared resolver contract and use it from channels, search, and messages, while letting the workflow docs PR cover numeric-id guidance if maintainers accept it.

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

Not applicable as a bug reproduction; this is a feature request for a resolver and output contract. Source inspection confirms current main lacks that resolver surface.

Is this the best way to solve the issue?

Unclear until maintainers settle the CLI and JSON/error contract. A shared resolver reused by channels, search, and messages looks narrower and safer than adding separate ad hoc matching behavior per command.

AGENTS.md: not found in the target repository.

Remaining risk / open question:

• The remaining work needs a maintainer decision on the CLI shape, JSON envelope, and ambiguity/error contract before implementation.
• The open docs PR may cover the numeric-id documentation slice, but it does not implement resolver behavior or query-command ambiguity diagnostics.

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

Label changes

Label changes:

• add clawsweeper:fix-shape-clear: Current issue advisory state selects this label.

Label justifications:

• P2: This is a concrete CLI ergonomics and agent-workflow improvement with limited blast radius, not an urgent runtime regression.
• impact:other: The impact is maintainer-visible archive usability and retryability for ambiguous Discord channel names, outside the more specific owned impact categories.

Evidence reviewed

Acceptance criteria:

• GOWORK=off go test ./internal/cli ./internal/store
• Add focused CLI/store tests for numeric ids, exact names, partial matches, ambiguous names, no-match errors, and JSON resolver output.
• Check docs for channels resolve, query resolution output, and numeric channel-id guidance after the product contract is approved.

What I checked:

• Repository policy check: No target-repository AGENTS.md or VISION.md file was found at the repository root or immediate checked paths. (670994a45f61)
• Channels command surface: runChannels currently accepts only list and show; an unknown subcommand such as resolve is still rejected. (internal/cli/query_commands.go:337, 670994a45f61)
• Message channel filter: ListMessages normalizes #name and filters with channel id, exact name, or partial name SQL, but it does not resolve to a single channel or report ambiguous candidates. (internal/store/messages.go:65, 670994a45f61)
• Search channel filter: SearchMessages applies the raw --channel value to channel_id or channel_name like, so JSON results include row channel fields but not a selected-channel resolution contract. (internal/store/query.go:84, 670994a45f61)
• Existing sync resolver is narrow: messages --sync prefers numeric Discord ids and can resolve matching names to channel ids for syncing, but its no-match error only says to pass an id or guild and it does not provide the requested candidate-id ambiguity output. (internal/cli/query_sync.go:31, 670994a45f61)
• Command docs: The channels docs document only discrawl channels list and discrawl channels show; search/messages docs mention id/name/partial filters but do not document numeric ids as the safest stable input. (docs/commands/channels.md:7, 670994a45f61)

Likely related people:

• Peter Steinberger: History shows this contributor introduced the message history query command and later split the CLI query command surface where channel filtering now lives. (role: introduced behavior; confidence: high; commits: d5df845b2c1d, 14b4b06a6527, 63375ea57325; files: internal/store/messages.go, internal/cli/query_commands.go, internal/store/query.go)
• vincentkoc: Current visible blame and recent history for the channel command/docs and query paths point to the latest release snapshot and adjacent cloud/read-command work. (role: recent area contributor; confidence: medium; commits: 6a91d9cc67bb, f01e699c1c86; files: internal/cli/query_commands.go, internal/store/query.go, docs/commands/channels.md)
• joshka: The issue and related parent tracker document the observed maintainer-archive workflow and the open docs PR that partially overlaps the numeric-id documentation request. (role: workflow reporter; confidence: medium; commits: 893e4a55495a; files: docs/guides/maintainer-archive-workflows.md, docs/README.md)

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.