Skip to content

docs: clarify Android token comments#88554

Merged
steipete merged 203 commits into
mainfrom
codex/inline-comments-followup
May 31, 2026
Merged

docs: clarify Android token comments#88554
steipete merged 203 commits into
mainfrom
codex/inline-comments-followup

Conversation

@steipete

@steipete steipete commented May 31, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

Summary

  • Continue the inline-comment pass after PR docs: remove divider comments #88115, focused on useful declaration docs and tricky contract notes, rebased onto current main.
  • Document Android Compose tab/state/navigation helpers, Android WebView factory behavior, local dev-server handling, and Talk defaults without file-header or import-block comments.
  • Add public API docs for markdown chunk/fence/frontmatter/table helpers, tool-call repair grammar/promotion utilities, chat tool-content normalization, Talk logging, Talk session health, echo-suppression helpers, gateway client identity/mode/capability contracts, protocol version constants, readiness-start helpers, event-loop readiness probes, timeout clamp/resolution helpers, startup-unavailable retry contracts, secret-ref schema patterns, media-generation model/normalization helpers, media-understanding formatting helpers, shared utility helpers, API-key masking, safe timeout wrapper, bounded concurrency worker helpers, normalization helpers, LLM API registry helpers, tool-call validation helpers, agent message contracts, proxy env/fetch helpers, runtime fetch/redirect helpers, Node proxy agent helpers, undici runtime dispatcher helpers, undici family policy helpers, undici global dispatcher helpers, active managed proxy state helpers, managed proxy TLS helpers, proxy lifecycle helpers, proxy TLS helpers, proxy validation helpers, HTTP CONNECT tunnel helpers, APNs HTTP/2 proxy helpers, APNs registration/send helpers, APNs relay helpers, device identity helpers, device bootstrap token helpers, device bootstrap profile helpers, device auth helpers, device auth store helpers, device pairing API helpers, device pairing lifecycle helpers, pairing file helpers, node pairing helpers, node pairing approval helpers, pairing pending helper, pairing token helper, safe secret comparison helper, gateway auth helpers, gateway auth resolution helpers, gateway credential helpers, gateway credential secret-input helpers, gateway auth secret-input path helpers, gateway credential planner, gateway startup auth helpers, gateway startup config helpers, gateway startup early/log helpers, gateway startup post-attach helpers, gateway startup memory helpers, gateway startup plugin helpers, gateway runtime config helpers, gateway runtime service helpers, gateway runtime state helpers, gateway HTTP router helpers, gateway method dispatcher helpers, gateway method registry helpers, gateway method descriptor helpers, gateway method scope helpers, gateway role policy helpers, gateway audit/list helpers, shared approval helpers, agent config mutation helpers, config write-flow helpers, environment/web handler helpers, plugin host hook helpers, node pending/skill upload helpers, wizard/system handler helpers, commands/health handler helpers, artifact handler helpers, diagnostics/logs handler helpers, task handler helpers, model handler helpers, model auth-status handler helpers, tools catalog handler helpers, effective tools handler helpers, channel handler helpers, restart handler helpers, push handler helpers, TTS handler helpers, secrets handler helpers, cron handler helpers, native hook relay handler helper, update handler helpers, shared server-method helpers, agent wait-dedupe helpers, exec approvals handler helpers, voicewake handler helpers, node handler helpers, agent handler helpers, doctor memory handler helpers, config handler helpers, agent session helper comments, usage handler helpers, send handler helpers, WebChat media helper comments, session handler helpers, system handler helper comments, chat transcript injection helper comments, device handler helper comments, skills handler helper comments, Talk shared helper comments, shared gateway helper comments, guard-safe client alias wording, network-boundary scanner-safe comment wording, and agent harness message/truncation/environment/file-loader/session-context/session-entry/branch-summary/session-storage/JSONL-session/prompt/agent-loop runtime/AgentOptions/result contracts.
  • Keep comments out of file headers and import blocks; removed the truncation and agent-loop file-top overviews while documenting the exported contracts directly.
  • Repair current-main CI fallout found during the rebase: slash-command docs formatting and an unreachable Discord gateway close-code comparison.

Verification

Behavior addressed: comment-only follow-up for Android, markdown/parser utility, chat, Talk, gateway protocol/client, proxy env/fetch/runtime redirect/Node proxy/undici dispatcher/family policy/global dispatcher/active managed proxy state helpers, managed proxy TLS helpers, proxy lifecycle helpers, proxy TLS helpers, proxy validation helpers, HTTP CONNECT tunnel helpers, APNs HTTP/2 proxy helpers, APNs registration/send helpers, APNs relay helpers, device identity helpers, device bootstrap token helpers, device bootstrap profile helpers, device auth helpers, device auth store helpers, device pairing API helpers, device pairing lifecycle helpers, pairing file helpers, node pairing helpers, node pairing approval helpers, pairing pending helper, pairing token helper, safe secret comparison helper, gateway auth helpers, gateway auth resolution helpers, gateway credential helpers, gateway credential secret-input helpers, gateway auth secret-input path helpers, gateway credential planner, gateway startup auth helpers, gateway startup config helpers, gateway startup early/log helpers, gateway startup post-attach helpers, gateway startup memory helpers, gateway startup plugin helpers, gateway runtime config helpers, gateway runtime service helpers, gateway runtime state helpers, gateway HTTP router helpers, gateway method dispatcher helpers, gateway method registry helpers, gateway method descriptor helpers, gateway method scope helpers, gateway role policy helpers, gateway audit/list helpers, shared approval helpers, agent config mutation helpers, config write-flow helpers, environment/web handler helpers, plugin host hook helpers, node pending/skill upload helpers, wizard/system handler helpers, commands/health handler helpers, artifact handler helpers, diagnostics/logs handler helpers, task handler helpers, model handler helpers, model auth-status handler helpers, tools catalog handler helpers, effective tools handler helpers, channel handler helpers, restart handler helpers, push handler helpers, TTS handler helpers, secrets handler helpers, cron handler helpers, native hook relay handler helper, update handler helpers, shared server-method helpers, agent wait-dedupe helpers, exec approvals handler helpers, voicewake handler helpers, node handler helpers, agent handler helpers, doctor memory handler helpers, config handler helpers, agent session helper comments, usage handler helpers, send handler helpers, WebChat media helper comments, session handler helpers, system handler helper comments, chat transcript injection helper comments, device handler helper comments, skills handler helper comments, Talk shared helper comments, shared gateway helper comments, media generation/understanding, shared utility, normalization, LLM, guard-safe client alias wording, network-boundary scanner-safe comment wording, and agent harness/helper maintainability; no runtime behavior intended.
Real environment tested: local source checkout.
Exact steps or command run after this patch: git diff --check; pnpm test src/gateway/server-methods/server-methods.test.ts src/gateway/server-methods/config.shared-auth.test.ts src/gateway/server-methods/update.test.ts; pnpm test src/gateway/server-methods/talk.test.ts; pnpm test src/gateway/server-methods/skills.clawhub.test.ts src/gateway/server-methods/skills.proposals.test.ts src/gateway/server-methods/skills.search-detail.test.ts src/gateway/server-methods/skills.update.normalizes-api-key.test.ts; pnpm test src/gateway/server-methods/devices.test.ts src/infra/device-pairing.test.ts src/infra/device-pairing-churn.test.ts; pnpm test src/gateway/server-methods/chat.inject.parentid.test.ts src/gateway/server-methods/chat.abort-persistence.test.ts src/gateway/server-methods/chat.directive-tags.test.ts; pnpm test src/gateway/server.health.test.ts src/gateway/server/plugins-http.runtime-scopes.test.ts; pnpm test src/gateway/server-methods/sessions.abort-agent-scope.test.ts src/gateway/server-methods/sessions.send-deleted-agent.test.ts src/gateway/server-methods/sessions.send-followup-status.test.ts; pnpm test src/gateway/server-methods/chat-reply-media.test.ts src/gateway/server-methods/chat-webchat-media.test.ts; pnpm test src/gateway/server-methods/send.test.ts; pnpm test src/gateway/server-methods/usage.test.ts src/gateway/server-methods/usage.cost-usage-cache.test.ts src/gateway/server-methods/usage.sessions-usage.test.ts; pnpm test src/gateway/server-methods/agent.test.ts src/gateway/server-methods/agent.create-event.test.ts; pnpm test src/gateway/server-methods/config.test.ts src/gateway/server-methods/config.shared-auth.test.ts; pnpm test src/gateway/server-methods/doctor.test.ts; pnpm test src/gateway/server-methods/agents-mutate.test.ts; pnpm test src/gateway/server-methods/nodes.invoke-wake.test.ts src/gateway/server-methods/nodes-pending.test.ts; pnpm test src/gateway/server.models-voicewake-misc.test.ts; pnpm test src/gateway/server-methods/server-methods.test.ts src/gateway/method-scopes.test.ts; pnpm test src/gateway/server-methods/agent-wait-dedupe.test.ts; pnpm test src/gateway/server-methods/server-methods.test.ts; pnpm test src/gateway/server-methods/update.test.ts; pnpm test src/gateway/server-methods/native-hook-relay.test.ts; pnpm test src/gateway/server-methods/cron.validation.test.ts; pnpm test src/gateway/server-methods/secrets.test.ts; pnpm test src/gateway/server-methods/tts.test.ts; pnpm test src/gateway/server-methods/push.test.ts; pnpm test src/gateway/server-methods/restart.test.ts src/gateway/server-restart-sentinel.test.ts; pnpm test src/gateway/server-methods/channels.status.test.ts src/gateway/server-methods/channels.start.test.ts; pnpm test src/gateway/server-methods/tools-effective.test.ts; pnpm test src/gateway/server-methods/tools-catalog.test.ts; pnpm test src/gateway/server-methods/models-auth-status.test.ts; pnpm test src/gateway/server-methods/models.test.ts; pnpm test src/gateway/server-methods/tasks.test.ts; pnpm test src/gateway/server-methods/diagnostics.test.ts src/gateway/server-methods/server-methods.test.ts; pnpm test src/gateway/server-methods/artifacts.test.ts; pnpm test src/gateway/server-methods/commands.test.ts src/gateway/server-methods/server-methods.test.ts; pnpm test src/gateway/gateway.test.ts src/gateway/server.health.test.ts; pnpm test src/gateway/server-methods/nodes-pending.test.ts src/gateway/server-methods/skills-upload.test.ts; pnpm test src/gateway/method-scopes.test.ts src/gateway/call.test.ts; pnpm test src/gateway/server-methods/environments.test.ts src/gateway/server-methods/web.start.test.ts; pnpm test src/gateway/server-methods/config.shared-auth.test.ts src/gateway/server-methods/config.test.ts; pnpm test src/gateway/server-methods/agents-mutate.test.ts; pnpm test src/gateway/server-methods/approval-shared.test.ts src/gateway/server-methods/plugin-approval.test.ts src/gateway/server-methods/exec-approval.ts; pnpm test src/gateway/server-methods-list.test.ts src/gateway/method-scopes.test.ts src/gateway/server-methods.control-plane-rate-limit.test.ts; OPENCLAW_LOCAL_CHECK=0 pnpm format:docs:check; OPENCLAW_LOCAL_CHECK=0 pnpm tsgo:prod; OPENCLAW_LOCAL_CHECK=0 pnpm lint --threads=8; pnpm test extensions/discord/src/monitor/gateway-plugin.test.ts; pnpm tsgo:prod; pnpm check:deprecated-jsdoc; pnpm check:docs; pnpm test src/gateway/role-policy.test.ts src/gateway/control-plane-rate-limit.test.ts src/gateway/server-methods.control-plane-rate-limit.test.ts src/gateway/method-scopes.test.ts src/gateway/methods/registry.test.ts; added-line network-boundary regex check; pnpm test src/infra/push-apns-http2.test.ts src/infra/net/proxy-env.test.ts; pnpm test src/gateway/method-scopes.test.ts src/gateway/server-methods.control-plane-rate-limit.test.ts src/gateway/node-invoke-plugin-policy.test.ts src/gateway/methods/registry.test.ts; pnpm test src/gateway/method-scopes.test.ts src/gateway/methods/registry.test.ts src/gateway/server-startup-post-attach.test.ts src/gateway/server-methods.control-plane-rate-limit.test.ts; pnpm test src/gateway/methods/registry.test.ts src/gateway/method-scopes.test.ts src/gateway/server-methods.control-plane-rate-limit.test.ts; pnpm test src/gateway/server-methods.control-plane-rate-limit.test.ts src/gateway/method-scopes.test.ts src/gateway/node-invoke-plugin-policy.test.ts src/gateway/server/ws-connection/message-handler.post-connect-health.test.ts src/gateway/server-plugins.test.ts; pnpm test src/gateway/server-http.stages.test.ts src/gateway/server-http.probe.test.ts src/gateway/server-http.request-trace.test.ts src/gateway/server.plugin-http-auth.test.ts src/gateway/server.plugin-node-capability-auth.test.ts src/gateway/server.preauth-hardening.test.ts; pnpm test src/gateway/server-runtime-state.test.ts src/gateway/server/plugins-http.test.ts src/gateway/server/plugins-http/route-capability.test.ts; pnpm test src/gateway/server-runtime-services.test.ts src/gateway/server-startup-post-attach.test.ts; pnpm test src/gateway/server-runtime-config.test.ts src/gateway/auth.test.ts; pnpm test src/gateway/server-startup-plugins.test.ts src/gateway/server-startup-post-attach.test.ts; pnpm test src/gateway/server-startup-memory.test.ts src/gateway/server-startup-post-attach.test.ts; pnpm test src/gateway/server-startup-post-attach.test.ts src/gateway/server-startup-early.test.ts src/gateway/server-startup-log.test.ts; pnpm test src/gateway/server-startup-early.test.ts src/gateway/server-startup-log.test.ts src/gateway/server-startup-post-attach.test.ts; pnpm test src/gateway/server-startup-config.secrets.test.ts src/gateway/server-startup-config.recovery.test.ts src/gateway/startup-auth.test.ts; pnpm test src/gateway/startup-auth.test.ts src/gateway/server-startup-config.secrets.test.ts src/gateway/server-startup-config.recovery.test.ts; pnpm test src/gateway/credentials.test.ts src/secrets/runtime-gateway-auth-surfaces.test.ts src/gateway/startup-auth.test.ts; pnpm test src/gateway/auth.test.ts src/secrets/runtime.gateway-auth.integration.test.ts src/gateway/credentials.test.ts; pnpm test src/gateway/credentials.test.ts src/gateway/credential-precedence.parity.test.ts src/secrets/runtime.gateway-auth.integration.test.ts; pnpm test src/gateway/credentials.test.ts src/gateway/credential-precedence.parity.test.ts src/gateway/auth.test.ts; pnpm test src/gateway/auth.test.ts src/secrets/runtime.gateway-auth.integration.test.ts src/acp/server.startup.test.ts; pnpm test src/gateway/auth.test.ts src/gateway/server.auth.browser-hardening.test.ts src/gateway/auth-mode-policy.test.ts; pnpm test src/security/audit-extra.sync.test.ts src/infra/pairing-token.test.ts src/gateway/auth.test.ts; pnpm test src/infra/pairing-token.test.ts src/infra/device-pairing.test.ts src/infra/node-pairing.test.ts; pnpm test src/infra/pairing-pending.test.ts src/infra/node-pairing.test.ts; pnpm test src/infra/node-pairing-authz.test.ts src/infra/node-pairing.test.ts src/gateway/node-connect-reconcile.test.ts; pnpm test src/infra/node-pairing.test.ts src/gateway/server.node-pairing-authz.test.ts src/gateway/server.node-pairing-auto-approve.test.ts; pnpm test src/infra/pairing-files.test.ts src/infra/device-pairing.test.ts src/infra/node-pairing.test.ts; pnpm test src/infra/device-pairing.test.ts src/infra/device-pairing-churn.test.ts src/gateway/server-methods/devices.test.ts src/gateway/control-ui.http.test.ts; pnpm test src/infra/device-pairing.test.ts src/infra/device-pairing-churn.test.ts src/shared/device-pairing-access.test.ts; pnpm test src/shared/device-auth-store.test.ts src/infra/device-auth-store.test.ts src/gateway/client.test.ts; pnpm test src/shared/device-auth.test.ts src/shared/device-bootstrap-profile.test.ts src/infra/device-pairing-churn.test.ts; pnpm test src/shared/device-bootstrap-profile.test.ts src/infra/device-bootstrap.test.ts src/infra/device-pairing.test.ts; pnpm test src/infra/device-bootstrap.test.ts src/infra/device-identity.test.ts src/infra/device-pairing.test.ts; pnpm test src/infra/device-identity.test.ts src/infra/device-identity.state-dir.test.ts src/infra/push-apns.relay.test.ts; pnpm test src/infra/push-apns.relay.test.ts src/infra/push-apns.test.ts src/infra/push-apns.store.test.ts; git diff --check origin/main..HEAD; pnpm test src/infra/push-apns.test.ts src/infra/push-apns.auth.test.ts src/infra/push-apns.store.test.ts src/gateway/server-methods/push.test.ts; pnpm test src/infra/push-apns-http2.test.ts src/infra/push-apns.test.ts src/infra/net/proxy/proxy-validation.test.ts; pnpm test src/infra/net/http-connect-tunnel.test.ts src/infra/push-apns-http2.test.ts src/infra/net/proxy/proxy-validation.test.ts; pnpm test src/infra/net/proxy/proxy-validation.test.ts src/cli/proxy-cli.runtime.test.ts src/infra/net/proxy/proxy-lifecycle.test.ts; pnpm test src/infra/net/proxy/proxy-validation.test.ts src/infra/net/proxy/proxy-lifecycle.test.ts src/infra/net/proxy/managed-proxy-undici.test.ts; pnpm test src/infra/net/proxy/proxy-lifecycle.test.ts src/gateway/client.test.ts src/gateway/client.watchdog.test.ts src/tui/gateway-chat.test.ts; pnpm test src/infra/net/proxy/managed-proxy-undici.test.ts src/infra/net/undici-runtime.test.ts src/infra/net/proxy-fetch.test.ts src/plugin-sdk/fetch-runtime.test.ts; pnpm test src/infra/net/proxy/proxy-lifecycle.test.ts src/infra/net/proxy/managed-proxy-undici.test.ts src/infra/net/proxy-fetch.test.ts src/gateway/gateway-misc.test.ts; pnpm test src/infra/net/undici-global-dispatcher.test.ts src/infra/net/fetch-guard.ssrf.test.ts src/agents/embedded-agent-runner/run/attempt.spawn-workspace.timeout.test.ts; pnpm test src/infra/net/undici-global-dispatcher.test.ts src/infra/net/ssrf.dispatcher.test.ts src/infra/net/fetch-guard.ssrf.test.ts; pnpm test src/infra/net/undici-runtime.test.ts src/infra/net/undici-global-dispatcher.test.ts src/plugin-sdk/fetch-runtime.test.ts; pnpm test src/llm/utils/node-http-proxy.test.ts src/plugin-sdk/fetch-runtime.test.ts; pnpm test src/infra/net/runtime-fetch.test.ts src/infra/net/fetch-guard.ssrf.test.ts; pnpm test src/infra/net/proxy-fetch.test.ts; pnpm test src/infra/net/proxy-env.test.ts; pnpm test packages/agent-core/src/agent-loop.test.ts packages/agent-core/src/harness/messages.test.ts packages/agent-core/src/harness/session/memory-storage.test.ts; pnpm test packages/agent-core/src/harness/session/jsonl-storage.test.ts packages/agent-core/src/harness/session/memory-storage.test.ts packages/agent-core/src/harness/messages.test.ts; pnpm test packages/agent-core/src/agent-loop.test.ts packages/agent-core/src/harness/messages.test.ts packages/agent-core/src/harness/session/jsonl-storage.test.ts; pnpm test packages/agent-core/src/agent-loop.test.ts packages/agent-core/src/harness/messages.test.ts; pnpm test packages/agent-core/src/agent-loop.test.ts packages/agent-core/src/harness/prompt-templates.test.ts; pnpm test packages/agent-core/src/harness/prompt-templates.test.ts packages/agent-core/src/agent-loop.test.ts; pnpm test packages/agent-core/src/harness/session/jsonl-storage.test.ts packages/agent-core/src/harness/session/memory-storage.test.ts; pnpm test packages/agent-core/src/harness/session/memory-storage.test.ts packages/agent-core/src/harness/session/jsonl-storage.test.ts; pnpm test packages/agent-core/src/agent-loop.test.ts packages/agent-core/src/harness/messages.test.ts packages/agent-core/src/harness/session/memory-storage.test.ts; pnpm test packages/agent-core/src/harness/session/memory-storage.test.ts packages/agent-core/src/harness/session/jsonl-storage.test.ts packages/agent-core/src/harness/messages.test.ts; pnpm test packages/agent-core/src/harness/messages.test.ts packages/agent-core/src/harness/utils/truncate.test.ts; pnpm test packages/agent-core/src/harness/env/nodejs.test.ts packages/agent-core/src/harness/prompt-templates.test.ts; pnpm test packages/markdown-core/src/frontmatter.test.ts packages/markdown-core/src/tables.test.ts; pnpm test packages/llm-runtime/src/api-registry.test.ts packages/llm-core/src/validation.test.ts; pnpm test packages/normalization-core/src/number-coercion.test.ts packages/normalization-core/src/record-coerce.test.ts; pnpm test packages/normalization-core/src/string-coerce.test.ts packages/normalization-core/src/string-normalization.test.ts; pnpm test src/utils/mask-api-key.test.ts src/utils/timer-delay.test.ts src/utils/run-with-concurrency.test.ts; pnpm test src/utils.test.ts.
Evidence after fix: latest pushed commit 460168e documents RPC attachment input/normalization, base-hash extraction, and shared gateway validator response contracts; whitespace/diff checks and targeted gateway helper tests passed locally.
Observed result after fix: PR branch pushed after the shared gateway helper slice and body refreshed.
What was not tested: Android runtime/UI smoke, gateway-client runtime smoke, and broader parser/harness suites not run because this slice only adds comments.

@openclaw-barnacle openclaw-barnacle Bot added app: android App: android size: XS maintainer Maintainer-authored PR labels May 31, 2026
@clawsweeper

clawsweeper Bot commented May 31, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

Codex review: needs maintainer review before merge. Reviewed May 31, 2026, 8:53 AM ET / 12:53 UTC.

Summary
The branch adds and revises inline KDoc/JSDoc/commentary across Android app, gateway/auth/proxy/APNs/pairing, agent-core, package, Talk, and utility surfaces, plus removes a redundant Discord gateway close-code comparison.

Reproducibility: not applicable. This PR is a source-comment documentation pass, not a bug report with a runtime reproduction path. The relevant check is whether the added comments accurately describe current code contracts.

Review metrics: 1 noteworthy metric.

  • Non-comment code delta: 2 added, 3 removed. The measured non-comment delta confirms this is source documentation/comment maintenance with only a redundant Discord predicate cleanup to review for behavior.

Merge readiness
Overall: 🐚 platinum hermit
Proof: 🦞 diamond lobster
Patch quality: 🐚 platinum hermit
Result: ready for maintainer review.

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

Rank-up moves:

  • [P2] Have a maintainer spot-check representative comments across Android, gateway/auth/security, proxy/APNs, and agent-core before merge.

Risk before merge

  • [P1] The branch is broad and comments auth, proxy, APNs, pairing, gateway, Android, and agent-core contracts; green CI cannot prove those comments are all accurate, so representative maintainer spot-checking remains the real merge gate.
  • [P1] The protected maintainer label requires explicit maintainer handling even though no concrete contributor-facing repair was found.

Maintainer options:

  1. Decide the mitigation before merge
    Land only after a maintainer spot-checks representative Android, gateway/auth/security, proxy/APNs, and agent-core comments and confirms the final merge result remains source-comment maintenance with no unintended behavior change.
  2. Pause or close
    Do not merge this PR until maintainers decide whether the risk is worth taking.

Next step before merge

  • [P2] Human maintainer review is the right next action because the protected label and broad contract-comment surface make accuracy judgment the remaining blocker, not an automated repair.

Security
Cleared: No concrete security or supply-chain regression was found; the diff changes source comments plus one redundant Discord predicate and does not touch dependencies, workflows, lockfiles, secret storage semantics, or code execution paths.

Review details

Best possible solution:

Land only after a maintainer spot-checks representative Android, gateway/auth/security, proxy/APNs, and agent-core comments and confirms the final merge result remains source-comment maintenance with no unintended behavior change.

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

Not applicable: this PR is a source-comment documentation pass, not a bug report with a runtime reproduction path. The relevant check is whether the added comments accurately describe current code contracts.

Is this the best way to solve the issue?

Unclear until maintainer review: a comment-only follow-up is a maintainable path if the wording stays accurate and useful, and no alternate runtime implementation is needed for the stated goal.

AGENTS.md: found and applied where relevant.

Codex review notes: model gpt-5.5, reasoning high; reviewed against c8f7e9102b88.

Label changes

Label justifications:

  • P3: This is a low-risk docs/source-comment polish PR with no intended runtime behavior change and no blocking correctness finding found.
  • rating: 🐚 platinum hermit: Overall readiness is 🐚 platinum hermit; proof is 🦞 diamond lobster and patch quality is 🐚 platinum hermit.
  • status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR. Sufficient (terminal): The PR body provides structured local source-checkout proof with exact post-patch diff, docs, type, lint, and targeted test commands plus observed results; for a source-comment pass, that is sufficient real-environment proof.
  • proof: sufficient: Contributor real behavior proof is sufficient. The PR body provides structured local source-checkout proof with exact post-patch diff, docs, type, lint, and targeted test commands plus observed results; for a source-comment pass, that is sufficient real-environment proof.
Evidence reviewed

What I checked:

  • Repository policy applied: Root AGENTS.md requires full policy review, scoped-guide review for touched paths, and concrete findings only for real regressions or mismatches; the gateway scoped guide was also read because gateway files are touched. (AGENTS.md:24, c8f7e9102b88)
  • Protected routing: Live PR metadata shows the PR is open at head 7c5658b with labels including maintainer, proof: sufficient, docs, Android, Discord, web UI, and gateway. (7c5658bd98eb)
  • Non-comment delta scan: A diff scan found only two non-comment added lines and three non-comment removed lines: the session_info discriminator comment moved to its own preceding comment, and a redundant Discord policy-close-code comparison was removed while the broader non-1000/non-1001 close-code condition remains. (extensions/discord/src/monitor/gateway-plugin.ts:161, 7c5658bd98eb)
  • Discord behavior spot-check: Current main already logs all close codes other than 1000 and 1001, so the explicit 1008 policy-code branch removed by the PR is behaviorally redundant rather than a fallback removal. (extensions/discord/src/monitor/gateway-plugin.ts:161, c8f7e9102b88)
  • Security-sensitive comment spot-check: Current main pads both secret buffers before timingSafeEqual and separately checks original lengths, matching the PR's safe-secret comparison comment intent. (src/security/secret-equal.ts:25, c8f7e9102b88)
  • Auth comment spot-check: Current startup auth code resolves token and password secret refs using the effective mode and source-specific candidate checks, matching the PR's comment about avoiding unrelated secret-provider requirements. (src/gateway/startup-auth.ts:145, c8f7e9102b88)

Likely related people:

  • steipete: Current-main blame/log for the Discord gateway close handling points to Peter Steinberger commits, and the related merged inline-comment cleanup was also authored by this contributor. (role: recent area contributor and source-doc follow-up owner; confidence: high; commits: 94b1427fdfa1, fd88f34a8fb7, e1ad5f51707e; files: extensions/discord/src/monitor/gateway-plugin.ts)
  • obviyus: Sampled current-main Android, gateway auth, and agent-core session files trace to Ayaan Zaidi's recent broad commit, making this a useful routing candidate for those contract comments. (role: recent area contributor; confidence: medium; commits: f454d6202f1a; files: apps/android/app/src/main/java/ai/openclaw/app/LocationMode.kt, src/gateway/startup-auth.ts, packages/agent-core/src/harness/types.ts)
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.

@clawsweeper clawsweeper Bot added proof: sufficient ClawSweeper judged the real behavior proof convincing. rating: 🐚 platinum hermit Good normal PR readiness with ordinary maintainer review expected. status: 👀 ready for maintainer look ClawSweeper has no concrete contributor-facing blocker left for this PR. labels May 31, 2026
@steipete
steipete requested a review from a team as a code owner May 31, 2026 10:14
@steipete
steipete force-pushed the codex/inline-comments-followup branch 3 times, most recently from 3342139 to 2f2d3d2 Compare May 31, 2026 11:46
@clawsweeper clawsweeper Bot added the P3 Low-priority cleanup, docs, polish, ergonomics, or speculative work. label May 31, 2026
@steipete
steipete force-pushed the codex/inline-comments-followup branch from b9e803f to dd3b4dd Compare May 31, 2026 12:21
@openclaw-barnacle openclaw-barnacle Bot added docs Improvements or additions to documentation channel: discord Channel integration: discord labels May 31, 2026
@byungskers

byungskers commented May 31, 2026

Copy link
Copy Markdown

This is a helpful documentation sweep — the intent behind a lot of these gateway helpers is much clearer after the added comments. My only meta concern is drift: given how many JSDoc blocks are being added/edited in one pass, do we have (or want) any lightweight lint/check to keep these comments in sync with exported signatures/behavior over time? Even a small convention for “behavioral invariant comments only” vs full API docs could make future maintenance easier.

@steipete
steipete force-pushed the codex/inline-comments-followup branch from 312d91a to 5c05e52 Compare May 31, 2026 13:24
@openclaw-barnacle openclaw-barnacle Bot removed the channel: discord Channel integration: discord label May 31, 2026
@steipete
steipete merged commit 85beee6 into main May 31, 2026
146 of 149 checks passed
@steipete
steipete deleted the codex/inline-comments-followup branch May 31, 2026 13:37
This was referenced May 31, 2026
Closed
Closed
Closed
Merged
Closed
Closed
Closed
Closed
Closed
Merged
Merged
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

app: android App: android app: web-ui App: web-ui docs Improvements or additions to documentation gateway Gateway runtime maintainer Maintainer-authored PR P3 Low-priority cleanup, docs, polish, ergonomics, or speculative work. proof: sufficient ClawSweeper judged the real behavior proof convincing. rating: 🐚 platinum hermit Good normal PR readiness with ordinary maintainer review expected. size: XL status: 👀 ready for maintainer look ClawSweeper has no concrete contributor-facing blocker left for this PR.

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

2 participants

@steipete @byungskers