Restore the WebSocket, stop the 5s repaint, share one launch roster (v0.5.0)

[TadMSTR]

Three defects, grouped because they share two files and one deploy cycle.
Covers vikunja#532 and vikunja#523.

1 — The WebSocket has been dead since v0.4.0 (#532)

v0.4.0 tightened the upgrade guard from if (origin && !allowed.includes(origin)) to
if (!allowed.includes(origin)), so a handshake with no Origin is rejected. The stated
reasoning was that only non-browser clients omit Origin.

On this deployment the only non-browser client is CloudCLI's own plugin WS proxy, which uses
the ws library — and that sends no Origin unless one is passed. Every upstream handshake
was 403'd from 2026-08-02T17:45 (the v0.4.0 deploy) to today: 2239 WS proxy error … 403 lines, and a tab reading disconnected throughout.

The guard now gates on the peer — loopback only, anything else refused outright — and
applies the Origin allowlist only when an Origin is actually present. A present-but-wrong
Origin is still refused.

This is a narrowing, not a relaxation. The loopback bind on an ephemeral port was always the
real boundary; Origin was never doing the work this deployment needed. Two independent
controls remain either way: CloudCLI's verifyClient authenticates the browser leg before
handlePluginWsProxy is ever called, and the server binds 127.0.0.1.

AGENTS.md carried the defect as a project invariant — "The WebSocket upgrade rejects a
missing Origin, not just a wrong one." Contradicting that in code alone would invite the next
reviewer to restore the bug on principle, so the sentence is rewritten with the loopback rule
and the history.

New src/ws-guard.ts holds the decision as a pure function; server.ts calls listen() at
import time, so this is the same extraction rationale as control-api.ts.

Verified against a live instance of the new binary on a scratch port:

Handshake	Result
no Origin (what the proxy sends)	101 Switching Protocols
Origin: http://127.0.0.1:3001	101 Switching Protocols
Origin: http://localhost:3001	101 Switching Protocols
Origin: http://evil.example	403 Forbidden

2 — The five-second full-panel repaint (#532)

ws-client.ts emitted _disconnected from onclose and reconnected every 5000ms forever.
index.ts handled it by setting state.wsConnected = false and calling render()
unconditionally — and render() does root.innerHTML = ''.

So the entire panel was torn down and rebuilt every 5 seconds while disconnected, losing
scroll position and closing any open filter dropdown, even though wsConnected was already
false.

Connection state no longer reaches render() at all. updateConnectionBadge() mutates the
header's dot colour and label in place, and only on a genuine transition. Reconnect backoff
added: 5s → 10s → 30s, capped, reset on a successful open — the first delay is unchanged, so a
transient blip still recovers as fast as before; the widening is for outages. A fixed 5s retry
is what turned a three-week outage into 2239 identical log lines.

Noted, not fixed: render() is called on every filter change and every detail load and
always does root.innerHTML = ''. Restructuring that was out of scope here, but it is why
any future state change is a full repaint by default.

3 — Start could not launch a run-as agent (#523)

AGENT_PROJECTS was a hardcoded five-agent map with no steward entry, so launchSession()
refused it. Adding an entry would have been worse than the bug: launchSession() spawned
claude directly as the plugin's own user, so a "fixed" map would have started a session in
steward's project dir, as the wrong user, with none of steward's credentials — a session
appearing as steward in every log while holding nothing of steward's. The launcher's identity
guard never fires when the launcher is bypassed.

The literal is deleted, not extended. Both this plugin and task-dispatcher.py now read
one file, ~/scripts/agent-launch.yml (override: AGENT_LAUNCH_POLICY). Two rosters of one
fact is exactly what drifted into this ticket.

Validation re-establishes what the literal gave for free — nothing user-supplied reached
spawn. Every field is checked against a closed set (agent name shape, project_dir under
~/.claude/projects with .. normalised first, run_as_user matching agent-*, launcher
under /usr/local/sbin/forge/), and the whole document is rejected on any violation. A
loader that skipped bad entries would pass nearly every test while silently dropping an agent
from the queue's reach.

A missing or malformed file is a named error, never an empty policy: an empty policy makes
run_as_user absent for every agent, which is precisely the impersonation above. A missing
or non-executable launcher is refused by name — there is no fallback path, deliberately.

Negative test, live: pointing steward's launcher at a nonexistent path returns
Launcher missing or not executable for run-as agent 'steward': … — deploy it with forge-scripts-deploy.sh, and nothing is spawned.

The sudo argv the plugin now builds was exercised end to end against the real launcher with
an empty prompt, so the launcher's own guard fires before it reaches claude: sudo accepts
the argv and the identity guard passes.

No new sudoers grant. The plugin runs as ted, and ted already holds
(agent-steward) CWD=* NOPASSWD: /usr/local/sbin/forge/run-steward.sh. This change makes the
plugin stop bypassing that launcher, which is a net tightening.

Two things reviewers should know

Mode vocabulary drift. Start sends review | auto; run-steward.sh and
task-queue-mcp's VALID_WORKFLOW_MODES take semi-auto | auto | manual-then-auto. review
is mapped explicitly to semi-auto rather than passed through — passed through, the launcher
refuses it by name (confirmed live: FATAL: invalid --workflow-mode: review). vikunja#533
covers the wider unification.

For a run-as agent, review is prompt-enforced only: run-steward.sh sets
--dangerously-skip-permissions itself and accepts no permission mode, so --permission-mode plan is not reachable. Rather than let the toast imply a tool gate that is not there, the
backend returns a note and the UI shows it. Filed as a ticket rather than widening the
launcher's argv surface in this build.

Prototype-chain lookup (found in pre-audit baseline). target_agent comes from a queue
YAML, and policy['constructor'] on a plain object is truthy — a bare if (!entry) guard
would carry a non-entry into the launch path. It failed safe at the next check, but the
ordering was load-bearing by accident. Policies are now built with a null prototype and looked
up via lookupAgent().

Also

• Launch logs move to ~/.claude/comms/artifacts/task-launches/<agent>-<task8>.log, matching
  the dispatcher. It wrote ~/.pm2/logs/agent-launch-* while this wrote <taskId>.log — two
  destinations for one concept. ~/.claude/comms is the side both can read; ~/.pm2/logs is
  not in PREVIEW_ALLOWED_PREFIXES and must not be added, since it covers every PM2 service
  log on the host. vikunja#534 depends on this.
• A refused upgrade now logs why. v0.4.0's refusals were silent on this side; the only signal
  was a 403 on the far side of the proxy, naming neither leg nor the cause.
• env:CLOUDCLI_ORIGIN added to manifest permissions.
• Version 0.5.0 in both package.json and manifest.json.

Companion changes

This half alone restores service. Two companion PRs land the other legs so neither side can
silently re-break it:

• TadMSTR/claudecodeui fix/plugin-ws-origin-2026-08 — the proxy sends an Origin;
  CLOUDCLI_ORIGIN added to PLUGIN_ENV_ALLOWLIST; recorded in PATCHES.md as a carried
  patch with a both-directions probe.
• host-forge/scripts fix/agent-launch-policy-2026-08 — agent-launch.yml itself, the
  dispatcher's loader, and CLOUDCLI_ORIGIN in cloudcli.sh.

Testing

npm run build && npm test — 41 passing, up from 12. New coverage: the upgrade guard (all
three cases, including the loopback-no-Origin one v0.4.0 broke), the reconnect schedule, and
the launch policy (every closed-set rejection, whole-document rejection, both argv shapes,
prototype-chain lookup).

15 mutations applied across ws-guard.ts, ws-client.ts and launch-policy.ts — including
restoring the exact v0.4.0 defect and making a run-as agent fall through to a claude argv —
all 15 caught.

Both loaders were run against the shipped policy file and produce byte-identical rosters.