Extension UI in daemon/RPC mode: setWidget component factories silently dropped, worker theme uninitialized, no terminal width available

[denkhaus]

Context: I initially filed this as issue #2064, which was auto-closed per the vouched-users policy - reposting here as the correct intake channel. All findings reproduced on 0.8.1, daemon-attached TUI.

Extension UI degradation in daemon/RPC mode is under-documented; three remaining gaps

Context

Extensions in daemon-attached sessions run in worker processes. The RPC
extension UI bridge (rpc-extension-ui-context.js) can only forward what is
serializable. This was already acknowledged in #690, #697, #885, and #1806
(thanks for those fixes). However, the current docs (extensions.md, main
branch) still say only: "Some TUI-specific methods are no-ops or return
defaults" - without naming which ones. Three gaps remain that cost hours of
debugging and are not documented anywhere:

1. setWidget silently drops component factories (analogous to #885)

ctx.ui.setWidget(key, (tui, theme) => component) is a documented form and
works in interactive mode. Under daemon/RPC it is silently dropped:

// rpc-extension-ui-context.js
setWidget: (widgetKey, content, options) => {
    if (content === undefined || Array.isArray(content)) {
        fireAndForget({ ... });   // factories never reach the client
    }
},

#885 fixed exactly this pattern for ctx.ui.custom() by rejecting loudly.
The same treatment (throw, or at least warn) would apply here. Alternatively,
document prominently: "In daemon-attached sessions, only the string-array
form of setWidget is forwarded."

Repro: run any TUI daemon-attached, register a factory-widget extension,
/reload - no widget, no error, no log line.

2. ctx.ui.theme is imported but uninitialized in workers

ctx.ui.theme exists in RPC mode (getter returns the shared theme module),
but the worker never calls initTheme(). Every theme.fg(...) call throws:

Error: Theme not initialized. Call initTheme() first.

Extensions that colorize widget strings per the docs will fail in every
daemon-attached session. Either initialize the theme in workers, or export a
worker-safe API (e.g. ctx.ui.themeOr(null)), or document that color calls
must guard with try/catch and fall back to raw ANSI codes.

3. No terminal width available to extensions in daemon mode

There is no way for an extension to learn the client terminal width:

• client env allowlist (DAEMON_CLIENT_ENV_KEYS) carries only HERDR_*
• TUI processes have no COLUMNS in their environment
• the worker has no tty (process.stdout.columns undefined)
• string widgets are rendered by the TUI (new Text(line, 1, 0), always
  left-aligned), so right-aligning a widget line - e.g. to line up with the
  built-in heartbeat tray label - is impossible through the public API

We ended up detecting the session's TUI via /proc (match comm=prime-agent
processes whose cwd equals the session cwd, rank by utime) and reading the
winsize via TIOCGWINSZ with a python3 helper. That works but is obviously
not the intended path. Suggestions:

• forward the client terminal width in the attach payload and expose it
  (e.g. ctx.ui.terminalColumns, refreshed on resize), or
• add an align: "left" | "right" option to ExtensionWidgetOptions and
  let the TUI align string-widget lines

Suggested documentation fix (minimum)

In extensions.md, extend the RPC paragraph of ctx.hasUI with a table of
which UI methods degrade in daemon/RPC mode:

Method	Daemon/RPC behavior
setWidget (string array)	forwarded, rendered by client TUI
setWidget (component factory)	silently dropped
custom / setFooter / setHeader	no-op (#885 rejects custom loudly)
theme	present but uninitialized; fg() throws
setStatus	forwarded, but built-in footer renders nothing
terminal width	not available

Environment: prime-agent 0.8.1, daemon-attached TUI, extensions auto-loaded
from ~/.prime/agent/extensions/.