rpc

Web conversation transport

This bounded transport implements Protocol, ListSessionEntries, LoadSessionEntries, DeleteSessionEntries, ListSessions, History, Prompt, and Join from internal/rocketclaw/web/proto/web.proto. Steer Prompt waits for Backend RunTurn completion, using the authenticated username. Bare $stop runs cancel through RunTurn and waits for that interrupted turn. Queue Prompt stashes waiting work through existing Backend queue operations and returns without waiting for that turn. ListQueue, SteerQueueItem, RemoveQueueItem, and ReorderQueue use existing Backend queue operations; promotion keeps the queued item's original principal and message ID. ListQueue.delivery distinguishes later work from pending steers. Direct steers retain the client's Prompt.message_id as durable input_id; pure-Web queued/stashed messages retain the supplied stable message ID (or a server-generated ID when omitted). History uses those IDs to move waiting inputs into chat in consumption order without matching text. Dropped items never run. Reorder writes persisted enqueue positions. Join sends only committed, content-free conversation-change hints; it does not replay history or return output through Prompt's private response field. History accepts the last applied revision and returns changed entries, removed keys, the complete ordered key inventory, and running/terminal state. Invalid or differently scoped revisions reset the view. Running turns include those of hidden runs whose sync destination is the chat; each shows after the chat's history under the key its synced copy later takes, and Join reports its changes. A positive limit returns only the newest limit saved entries plus running turns, and its revision follows only those entries, so a read's cost depends on the entries shown, not on the whole chat. start is where the returned entries begin and more says older ones exist. A positive before reads a settled, unfollowed page of older entries: the newest limit of them, or every entry from from onward. If older history is cleared, the next limited read resets. A chat's origin still comes from its first entry when that entry is not returned. SearchSessions applies the same origin rules when it matches the query against every chat the caller may see; cron runs and private External MCP conversations never match.

StageRevert accepts a visible session ID and an optional recorded user message_id; omission selects Undo's predecessor from complete effective history, not the loaded page. It settles the runtime bridge, stages an exclusive durable cutoff, and returns the actual marker and editable TranscriptEvent prompt without its generated header. ClearRevert clears the entire cutoff and wakes preserved work, with no composer payload. Both require a top-level pure Web session; Slack, MCP-bound/private, Cron-origin and delegation sessions are ineligible even through direct calls.

History returns revert_eligible, revert_message_id and can_undo, including an empty first-message cutoff. Its opaque revision includes the cutoff; a change resets page bounds, inventory and delegation links from one database snapshot. Committed marker changes use the existing Join wake-up channel. Clients must reject outstanding reads across mutations/resets, not compare cutoff values alone: Stage followed by Redo can restore the same value. IDs are opaque decimal strings with replay indices; do not convert them to JavaScript numbers.

Prepared new prompt admission reconciles message identity under the history lock and atomically prunes the abandoned suffix, clears the cutoff, rebuilds the summary and stores the new queue owner. Retries of accepted IDs do not prune again. $agent and $stop are controls and leave the cutoff intact. Pending human work is hidden while staged, restored in order on Redo, and removed when a replacement is accepted. Automatic recovery, schedules and goal continuation cannot execute behind the cutoff. Uploads remain available to restored drafts. Revert never compensates files, external tool effects, deliveries or scheduled registrations. Deploy migration 026 with the regenerated protocol and Web assets; clear staged cutoffs before a schema downgrade to avoid exposing hidden history. In-progress turns and saved turns share source-qualified turn keys; item_id is render identity, while message_id identifies saved entry positions for commands. History returns the recorded turn in order, including developer messages, thinking summaries, tool calls, tool results, and user/assistant text. Encrypted reasoning bodies stay stored and are not sent. History retains tool call IDs and names so Web can group each call with its result. Recognized public records in OutputTrace add replay-neutral assistant text and fixed tool/delegation lifecycle states. Unknown trace records are not rendered. Progress rows use producer-qualified item/call identities, never fabricated message_id or input_id values. Per-item completion is independent of the parent turn's running state. Authoritative replay replaces overlapping partial text, including empty final output; retained public records provide display fallback when compaction removes the corresponding replay. Blocked, failed, or stopped delegation metadata suppresses private or reviewer-bearing result text in Web, including saved history, without changing canonical provider replay. Private child diagnostics, review reasons, reasoning bodies, and provisional arguments never enter this public path. History reads neither acknowledge Slack delivery nor change queue/steer boundaries. Slack keeps placeholder-plus-final delivery. New messages save their exact generated bracket header alongside model-facing text as prompt_header in local replay. History and session-list previews remove only that saved prefix from user/developer display text. History exposes it as TranscriptEvent.header; the Web message footer shows it through an info icon on hover or click. New text headers omit media=Text. Old messages are not backfilled or guessed from their text. Model-facing text still includes the generated header; local header metadata is never sent to the provider. Assistant text is unchanged. TranscriptEvent.principal decodes only the stored header's top-level quoted principal, including on attachment-bearing inputs. QueueItem.principal copies the item's recorded author; an item another session's agent wrote has none and shows agent <name> (session <ID>) instead. Web shows it above human text inside the existing bubble and above queue-row text, without replacing it with the viewer's identity. Missing or malformed stored principals stay unlabeled; raw headers remain intact. Previews use the latest nonempty user or assistant message, including the same successful delivery report shown in History. Migration 011_last_message_summaries.sql invalidates the derived user-only previews for the existing background backfill. Session running is true while the conversation has an unfinished turn.

MoveToBackground moves every running execute and task call of agents with permission.rocketclaw.allow_background: allow in the conversation into Background Jobs and reports moved; with nothing eligible it changes nothing. StopBackgroundJob stops one running job by ID, records it as stopped by user, and reports stopped, false when the job had already finished. Stopping a task job also stops its subagent session's running turn and that subagent's own jobs. It reaches the conversation's own jobs and jobs of hidden cron or External MCP runs whose sync destination is this conversation, the same scope as the agent's rocketclaw_stop_background_job. Both authorize like the queue RPCs and are refused for private cron and External MCP conversations. History adds a movable flag, true while such a call runs attached to its turn, and a backgroundJobs list with label, kind, state, tool call ID, subagent key, who stopped it, and a hidden mark. The list holds jobs that are running or whose Completion Note is still pending, including those of hidden runs that report here. History also lists pendingQuestions: the unanswered ask_user_question calls of the conversation's Web turns, read from their saved turn steps, so they survive a closed tab or a restart. AnswerQuestion authorizes like the queue RPCs, then saves the selected values and custom text as the answer to the named question of that conversation and wakes its waiting turn. The first answer wins; any other answer, including one naming another conversation's question, fails with NotFound "no longer pending" and changes nothing. Transcript events that deliver Completion Notes carry them in completionNotes with each job ID, final state, and note text. They come from the stored jobs whose IDs the system input saved as its input ID, never from its text, so output that looks like a note adds no row; the jobs stay until their conversation is deleted, and a fork copies the finished ones its copied notes list, as already read, with their unexpired retained output. A task call's events carry delegation, the Delegation History of the subagent the call started or continued, as recorded in its public progress. Any call's function_call event carries review, the Delegation History its automatic permission reviews save to, derived from the turn ID and call ID; the Web links it only while the response's delegations list it, so a review saved after the row was sent still links. Job changes and movable flips send the usual conversation-change hint.

Session.tags (additive protobuf field 14) carries the owning conversation's durable, lexically sorted active tag names in ListSessions. Missing metadata returns an empty list. The existing session-list query joins tags without adding a request per row or widening private-session discovery. Tag-only changes appear on the next snapshot without changing previews, timestamps, or pin. HTTP retains the same owner/completeness envelopes and ordering; no tag mutation RPC or event is added.

Session discovery starts from explicitly recorded conversations with stored entries, excluding private Cron locators and recorded MCP X bindings. It does not discover orphaned entry rows or backfill records. CreateSession records a fresh opaque ID with the selected loaded agent. ListSessions streams one conversation per response message in list order. The Go HTTP adapter forwards these progressively through a finite SSE response, preserving full previews and gRPC's default 4 MiB per-message receive limit. Each envelope carries the authenticated owner and summary completeness; the final empty envelope marks upstream success and aggregate summary completeness, including for an empty list. An SSE complete event is sent only after successful gRPC EOF. HTTP iterator exhaustion is separate from that application terminal: a failure or wire cut can leave a visible prefix, which is not a completed list. Cancellation cancels the gRPC call, including pending reads, and releases database rows. Identity returns the Go-mapped username separately from Protocol negotiation. ListAgents loads the current runtime definitions. Session allowed_agents comes from those definitions for Web conversations and the existing Slack channel policy for Slack Y. $agent name persists selection and updates the live bridge without resetting history; private producer X cannot be selected. Removed choices are not re-added merely because they remain the current selection.

ListConfig exposes only the retained ConfigView fields: workspace, overlays, model aliases, channel agent choices, MCP server names, logging level, auto-approver model, and enabled flags. It never serializes credentials, database URLs, environment values, MCP commands/headers, or browser/user mappings. ListSkills uses the existing rooted runtime-definition loader and returns loaded skill text and metadata; origin is the loader's relative definition location. With ListSkills.agent, it returns only skills allowed for that loaded agent, excluding denied and review-only permissions; an unavailable agent returns no skills. Omitting the filter retains the full skills-page catalog. The composer supplies its selected agent and lists commands before those skills. Choosing a skill inserts $name , or $skill name for a built-in name collision, without sending. Web-only outer $enqueue queues automatic later work, $stash holds work until explicit send, and $steer sends now or into the active turn. These commands override the requested delivery and strip only the outer command and surrounding prefix whitespace, preserving inner text, spacing, and nested commands. Explicit Prompt.delivery=STASH treats the entire payload as literal text instead, including all three commands. Bare $stop and $agent keep their built-in meanings. Normal Send during a turn queues; Cmd/Ctrl+Enter steers. Skills are loaded when consumed.

ListCronJobs uses the same started Cron manager as scheduled/Slack execution. It exposes parsed definitions and each schedule's next trigger within 24 hours, using persisted due times for recurring schedules rather than restarting their intervals on a read. RunCronJob loads the selected stem through that manager, runs its fresh private X, and returns the actual destination Y only after the existing runner's RunTurn and Sync finish successfully.

Historical Cron rows use existing sync_source_entry_id links to surviving source entries. Backend entry reads expose generic source conversation provenance; RPC decodes the Cron prefix and the timestamp/random suffix from the right. The stored path label is used as-is, including previously stored underscores, without matching current definitions. Runs are deduplicated by source X within each recorded human Y and link only to Y. Rows sort newest-first by the source run timestamp, with Y and X as tie-breakers. A synced row proves a copy, not successful model execution or delivery. Recorded private Cron conversations with saved entries or visible turn checkpoints also supply run timestamps through the same metadata query, without reading replay content. Checkpoint visibility follows the transcript's terminal, supersession, and revert rules. When no human destination has a copy, Web shows “No delivered chat” with an Open chat action. CreateSession.source_conversation_id accepts a recorded Cron producer and creates or reuses web:<source ID>, then calls SyncConversation. Creation and sync are idempotent, including concurrent opens and retries after a failed sync. This creates a writable Web conversation, without Slack creation or Cron execution. The Web chat ID retains its source cron ID to resolve the current definition's channel for agent choices in the picker, session list, and server-side agent changes. Choices use the current configured channel agent order intersected with loaded agents; if no list can be computed, all loaded agents are allowed. Creation selects the first allowed loaded agent; reopening does not overwrite a conversation's selection. Existing delivered chat links are preserved. Authenticated users can read Cron producer history through History, including runs without a delivered chat; this does not grant prompt, queue, deletion, or other mutation access to producers. A delivered copy takes precedence over the undelivered row for the same source. Missing source entries cannot supply history; no migration, backfill, or history rewrite is performed. Web groups runs beneath their definition, retaining groups whose definition is gone. History.source_conversation_id optionally restricts the authorized destination's history to one source run before replay decoding; it does not change access to other private source conversations. The grid uses this filter for quick previews, with a link to the destination chat.

Attachments

UploadAttachment(stream Attachment) -> Attachment accepts one file per call. The first frame supplies conversation_id, name, and optional data; subsequent frames supply data. Each chunk is at most 256 KiB, below gRPC's default 4 MiB receive limit. Close the sending side to finish. The response supplies the immutable ID, basename, detected MIME type, and original byte count. Pass IDs in Prompt.attachment_ids for either steer or queue. Images retain the existing model-side normalization; all uploads are also materialized through os.OpenRoot(cfg.Workspace) at artifacts/uploads/<id>/<basename>. Other files are available to model tools at those paths. The original text, principal, attachment references, and image input travel through existing durable queue content. Prompt text includes attachment:<id> and the safe workspace path so replay retains a file reference without embedding its bytes in transcript RPCs.

DownloadAttachment(Attachment) -> stream Attachment requires the visible conversation ID in conversation_id and the attachment ID in id. It authorizes against that conversation's current history or queued references on every call, including uploads referenced by its selected staged user boundary for composer restoration—not arbitrary uploads or other references in the hidden suffix— then returns exact original bytes in 256 KiB chunks. Merely knowing an ID is not authorization. Private Cron producers and recorded private external MCP sessions are denied, as are unmapped browser IPs. Deleting history revokes its references; deleting a source also revokes its dangling synced copies. Queued references remain valid until removed or consumed.

History and ListQueue carry repeated attachments metadata. The protobuf JSON shape (using protojson) is:

{"id":"opaque-id","name":"image.png","mimeType":"image/png","size":"1520338","originalUnverified":false,"conversationId":"producer-id"}

data is absent from transcript/queue metadata. conversationId there identifies the stored producer, which can differ from the visible conversation for a synced entry. The HTTP proxy must use the currently viewed conversation for download authorization, never substitute this producer field. Standard Go encoding/json uses the generated snake_case tags and a numeric size; the HTTP adapter uses protojson instead. Upload raw bytes to POST /api/UploadAttachment?conversationId=…&name=…. Download through GET /api/DownloadAttachment?conversationId=…&id=…; download=1 forces a download. Both paths stream chunks and cancel gRPC on disconnect.

New tool outputs persist original bytes in the configured filesystem directory or S3 bucket before returning immutable IDs in successful tool replay. PostgreSQL stores ownership, file metadata, and byte counts only; migration 014_attachments.sql creates that metadata table. The default directory is <workspace>/.rocketclaw/attachments (or .femtoclaw/attachments for the legacy configuration). See the root README for the attachments configuration. Historical successful tool calls may recover still-available workspace files once; recovered metadata says original_unverified=true. Later overwrites or removal never replace recovered bytes. Missing or root-escaping historical files are omitted. This is a snapshot of available bytes, not a claim to recover an old file version. Originals are never resized in storage. Unreferenced blobs remain stored but cannot be downloaded; garbage collection is not part of this transport.

Voice

Voice(VoiceRequest) -> stream VoiceEvent runs one GPT-Live call for exactly as long as its request lives. HTTP serves it only as POST /api/Voice, so CrossOriginProtection blocks cross-site starts; it is not a GET stream route. The body is {"conversationId":"<visible-id>","sdp":"<offer>","voice":"<name>"}; voice is optional and must be one the agent's provider offers (ListAgents lists them per agent, the default first: Codex's voices on chatgpt, the public API's on api_key), else the call is refused with InvalidArgument. The handler checks identity and visibility, takes credentials from the provider of the conversation agent's model (api_key uses the public API and honors api_base_url; chatgpt uses the saved login on Codex's fixed internal URLs), creates the call, and attaches its sideband socket before answering. SSE frames are {"answer":{"sdp":"…","route":"public"|"codex"}} first, then any {"notice":"…"} frames, then one {"ended":{"reason":"…"}} with reason stopped, replaced, expired, safety, closed, lost, or error. A notice reports a hand-off the agent refused; the call continues. Errors before the answer are ordinary JSON errors: NotFound for an unrecorded conversation, and FailedPrecondition (HTTP 400, code 9) for missing credentials, a failed ChatGPT token refresh (naming its rocketclaw oai login command), a plain-HTTP api_base_url whose host is not localhost or a loopback IP, or an OpenAI rejection, which reports only the upstream HTTP status. Voice requests to OpenAI drop Authorization, Api-Key and Chatgpt-Account-Id on any redirect to another scheme, host, or port.

Each person (the caller's username) has one live call across all conversations; the newest wins, and the older stream ends with replaced. Different people's calls on one conversation run side by side. The server has no idle or no-speech timers. Aborting the request ends the call: over a live sideband the server sends session.close and waits up to 3 s; it then hangs up a public session that did not confirm, and closes the socket. The handler returns right after ended. OpenAI's session.closed ends the call as expired, safety (a content stop), or closed.

VoiceSettings(VoiceSettingsRequest) -> VoiceSettingsResponse (POST /api/VoiceSettings) reads and changes the caller's voice settings: their current voice conversation, the agent for their next one, their voice, and the transcript view. The action is READ (the default), START (returns the current conversation, or creates one with agent as CreateSession would), RESET (forgets the current conversation while it is still conversationId), or UPDATE (stores the agent, voice and transcript fields that are set; an agent the caller cannot choose or a voice no route offers is InvalidArgument). Every action answers with the caller's whole settings row, and conversationId is empty when none is current. Startup cleanup never deletes a person's current voice conversation; after RESET, ordinary cleanup applies.

When the sideband drops, a public call ends as lost. A Codex call reconnects as Codex does: it waits 200 ms, doubling to 5 s (reset after 30 s connected), then dials up to 5 times. A 404 or 410 ends it as closed, and 5 failed dials as lost. As in Codex, a normal close (1000) of a Codex sideband is no drop: it ends the call as closed at once. Stop cancels a dial in progress at once. While the sideband is down the browser gets reconnecting: true, and false once it is back; it shows "Reconnecting to the agent…" meanwhile. Audio keeps flowing, since it never passes through RocketClaw. Messages that failed to send go out first after reconnecting. A Codex call stopped while disconnected sends no session.close; the browser closing its audio ends it.

Each hand-off is admitted in arrival order through StashQueueItem, without waiting for the turn: it joins the running turn as a Web steer or starts the next turn. It carries media=Voice, the caller's principal, and the hand-off ID as both the queue item ID and web_message_id, so a re-delivered hand-off is admitted once. It bypasses Prompt: $ text in it never runs commands, skills, or workflows. Its text is taken the moment the hand-off arrives and written exactly as Codex wraps it: <realtime_delegation> with the request in <input> and the voice conversation since the previous hand-off in <transcript_delta> (user:/assistant: lines; the request is added as a user line unless already said), XML-escaped and each cut to 4 KiB behind a "…" (the request keeps its start, the transcript its end). Public hand-offs carry no request text, so that conversation is the request too. A hand-off with nothing to send is ignored, and talk after the last hand-off is not stored. A stopping runtime ends the call as error.

Nothing is sent to the voice model while the agent works. When a turn this call handed off finishes, its final reply is sent once, as written, unless it is over 3,960 bytes (about 990 tokens). Then, as Codex shows such a reply on screen, the browser gets it in a reply event and the voice model hears that it is on the screen. A user message typed during the call cancels the reply of every earlier hand-off, as Codex does; only a later hand-off speaks again. It also sends the browser a typed event: the browser mutes the voice model at once and unmutes it when the model begins a reply after the person spoke again, as Codex suppresses its speaker. Each pending question in the conversation is sent once as "I need your input. Please respond in the app." with its text and options; spoken words never answer it. OpenAI receives only the audio, the seed (up to 40 recent user messages and complete assistant replies as written, each cut to 600 bytes, 12,000 bytes in total), those final replies, and those question notices: no tool names, arguments, or results, no progress, reasoning, or attachments.

Start

History summary backfill

Existing histories gain durable session-list summaries in the background when the RocketClaw runtime starts. Backfill does not gate readiness. It commits progress incrementally, so a later runtime start resumes histories that still lack a summary. It does not create conversation records or expose orphaned histories. Normal history writes maintain the summary in the same transaction as the history. New conversation records initialize their summary in the creation transaction, including when they attach existing orphan history. An empty summary is complete; a missing summary is not. Empty histories retain blank previews and display timestamps. Session-list enumeration checks for stored entries and reads stored summaries without decoding replay, including while legacy summaries are still missing. Empty histories are omitted until an entry is stored.

If backfill fails, the runtime logs backfill session summaries with the error and stops that backfill attempt; it does not retry automatically within the same run. Investigate the logged error before restarting to resume. Shutdown cancels and joins the backfill before releasing the runtime lock or closing the store.

Run the Web transport

Session-list Slack labels use stored channel facts. A background lane refreshes known channels every three minutes; rate limits can extend staleness, and failed lookups retain the last known facts. Session-list requests do not wait for Slack. Stored facts do not grant permission: action authorization still uses live checks. Configure rename subscriptions using Slack Channel Rename Subscriptions.

Build the browser assets before compiling Go. Frontend source lives in internal/rocketclaw/web/; the build writes compiled assets to internal/rocketclaw/internal/web/dist/, which Go embeds in the binary. make build, make lint, and make test build these assets as a prerequisite. Bun 1.4.2 or newer is needed for builds and tests, but the deployed binary needs no Bun or Next.js process.

From the repository root:

export TMPDIR="$PWD/.tmp"
(cd internal/rocketclaw/web && bun install --frozen-lockfile && bun run build)
go run ./cmd/rocketclaw

Web always starts. Its HTTP listener defaults to 0.0.0.0:3000; set web.listen_address in rocketclaw.json or femtoclaw.json to change it. The HTTP adapter connects to gRPC entirely in memory inside the same process. No Web environment variables or filesystem sockets are needed. Browser identity on that listener still comes from the connecting IP, using web_users first and Tailscale WhoIs otherwise. When web.tsnet is set, RocketClaw also runs a tailscale.com/tsnet node that serves the same handler over HTTPS on port 443 of its tailnet name; see Identity boundary.

The normal RocketClaw command still starts its existing Slack/Cron runtime. The isolated transport tests below do not start Slack or touch runtime configuration.

Open /s/<base64url-conversation-id> in the Web UI to read the conversation. Thinking and tool traces appear inline within each turn as the browser's Timeline detail setting shapes them (Compact by default: one closed summary row); replies and successful verbatim-delivery reports always remain visible. For example, obtain the URL component with:

bun -e 'console.log(Buffer.from(process.argv[1]).toString("base64url"))' 'slack-thread:C1:1.1'

The DeleteSessionEntries RPC removes saved entries and retained failed/stopped turns for that exact conversation ID, not an unfinished turn or its conversation or goal record, and retains its session tags. Ordinary GC remains responsible for those records; permanent session pruning removes tag metadata too.

Identity boundary

TranscriptEvent carries additive agent, model, optional reasoning_effort, and origin fields. HTTP/SSE uses their protobuf JSON camelCase names. Absent reasoning is unknown; a present empty string means provider default. History resolves replay attribution ranges before the entry snapshot. Join carries no transcript content or execution attribution; clients read these through History. Saved copy locators survive source-row retention without exposing source or destination IDs in the transcript.

RocketClaw accepts browser connections directly (for example over the private network). HTTP mutations and uploads reject cross-origin browser requests using Go's CrossOriginProtection; browser-IP identity never grants cross-origin authority.

The HTTP proxy forwards only the connection's remote IP. It ignores X-Forwarded-For, X-Real-IP, Tailscale-User-*, and client-supplied principal headers. Do not put another HTTP reverse proxy in front of it: that would identify the proxy rather than the browser.

Each opencode server gets a relay on its own port, on the Web listen host and, with web.tsnet, on the tailnet node. The relay admits exactly the browsers the Web admits (by IP on the plain listener, by Tailscale user on the tailnet), adds the server's password, and serves OpenCode's own web app, which the Web frames at /server/<base64url relay origin>/session/<id>. It refuses any request, WebSocket upgrades included, whose Origin is another site, sends OpenCode its own origin so OpenCode's terminal origin check still holds, and lets only pages on the same host frame it. Everyone the Web admits gets full control of every configured OpenCode server, including its shell. Remote sessions are listed from a copy RocketClaw syncs every 5 seconds; once a day the server's full list removes copies of sessions it no longer has. Prompt refuses their opencode: IDs. People tag remote sessions with any tag and RocketClaw sessions with tags their agent allows.

Phones get the secure page that voice needs from the web.tsnet listener (see the root README for setup). There, a wrapping handler asks the node's LocalClient().WhoIs about the connection's remote address and refuses tagged or unknown callers. It passes the login and display name to gRPC as -bin metadata keys, because names may be non-ASCII. When those keys are present, principal and ListConfig use them and never consult web_users or tailscale whois. The listen_address listener never sets those keys and keeps the IP rules below. Tailscale logins and web_users names are separate namespaces, so one person may appear under two names. The node stores its state under os.UserConfigDir()/rocketclaw/tsnet-<hostname>, outside the workspace. rocketclaw ts login logs it in, with web.tsnet.auth_key or a printed login link; the server never prints a link or waits for one. A logged-out node without a key is closed at startup with one "Tailscale authentication unavailable" warning, and a node that loses its login later stops serving the same way. Tailscale's log upload is off. Never use tailscale funnel.

Local processes can still act as the owner. On an untagged host signed in to Tailscale as the owner, a connection from the host to its own Tailscale IP arrives from that IP, and tailscale whois names the host's own user (checked on macOS). A connection from the host to the tsnet name likewise arrives from the owner's device. A 127.0.0.1 mapping, for a browser on the host, adds the direct loopback path but no new local authority there. On a tagged host, where WhoIs rejects every local caller, it does add authority.

Go snapshots configured web_users IP-to-username mappings at startup. An explicit mapping takes precedence; otherwise Go runs tailscale whois --json for the browser IP and uses UserProfile.LoginName as its identity. New prompts instead record UserProfile.DisplayName as their principal, with the login as the fallback for a missing or blank display name. A manual mapping uses its configured name for both. Admission, conversation ownership, inbound routing, and Config's Tailscale user stay login-based. Identity.username remains the login; the separate Identity.principal is used only for new composer/handoff previews. Successful lookups are cached per IP for five minutes and shared with the Config page. Concurrent misses are serialized; expired entries must be looked up again, and a failed refresh denies access rather than using the stale identity. Failed lookups, missing login names, and tagged devices without a manual mapping are rejected with Unauthenticated (HTTP 401). Mapping changes require restart. TypeScript does not read RocketClaw configuration or perform Tailscale WhoIs. For the Config page, Go runs tailscale whois --json with the authenticated browser connection IP and exposes only UserProfile.LoginName as tailscale_user. Lookup failures leave that display field empty; a manually mapped user can still access the Web interface. For Tailscale identification, the CLI must be available on the RocketClaw process's PATH and connected to its local service. Protocol exposes only the schema hash to the trusted local proxy and requires no browser identity, so startup does not require mapping localhost.

Verify without a live Slack runtime

Use a dedicated test PostgreSQL database, never a production database. Each run creates an isolated schema via the existing test helper.

mkdir -p "$PWD/.tmp/test-tmp"
export TMPDIR="$PWD/.tmp/test-tmp"
export ROCKETCLAW_TEST_DATABASE_URL='postgres://postgres:postgres@127.0.0.1:55435/rocketclaw_test?sslmode=disable'
go test -race -count=1 -run '^(TestWebRPC|TestSessionEntries)$' \
  ./cmd/rocketclaw ./internal/rocketclaw/frontend/rpc

TestSessionEntries starts real Unix gRPC and the Go HTTP adapter, uses Bun as its HTTP test client, and verifies PostgreSQL results. It checks spoofed forwarding headers, unmapped IPv6 connections, ordering, empty results, and preservation of unrelated entries and conversation/goal records. Bun must be installed and web dependencies must already be installed. The TypeScript integration test skips when run alone; Go provides its isolated storage fixture.

For real desktop/mobile transcript gestures, build Web first and provide an installed Playwright module and Chromium executable:

(cd internal/rocketclaw/web && bun run build)
export ROCKETCLAW_PLAYWRIGHT_MODULE='/absolute/path/to/playwright-core/index.mjs'
export ROCKETCLAW_CHROMIUM='/absolute/path/to/chromium'
go test -count=1 -timeout=80s -v ./internal/rocketclaw/frontend/rpc

The browser check starts its own Next server on an ephemeral port and checks the default closed activity summary row and visible replies on desktop and at 390px width. It stops only that test process and saves r22-web-desktop.png and r22-web-mobile.png under the repository-local TMPDIR.

After changing the proto, run go generate ./internal/rocketclaw/frontend/rpc with protoc and protoc-gen-go on PATH. This regenerates messages and the schema hash; the network test also compares Go's hash with the TypeScript source.