SENPAI Console integration + Phase 2 steer/watch hooks

[morganmcg1]

Coordinated change-set so the SENPAI Console (see its PR #1) can index this fleet and steer agents near-live. Everything is additive and inert by default — nothing changes unless the new env vars are set.

Runtime reality

The console build plan frames Phase 2 around an OpenHands openhands-agent-server (Surface B). This fleet runs Claude Code (k8s/run-senpai-claude.sh), not OpenHands — there is no senpai_agent/openhands_runner.py on main. So Phase 2 is implemented in terms of the real Claude-Code runtime:

Build-plan concept	This fleet's mechanism
Live event stream	SENPAI_EVENT_DIR — mirror Claude Code --output-format stream-json to a stable per-iteration event file the console tails
send_message() mid-run steer	SENPAI_CONSOLE_INBOX_DIR — console drops a directive file; the entrypoint drains it into the next heartbeat's prompt
pause/interrupt	not native under claude -p; watchdogs + GitHub-mediated controls remain

What changed (additive / inert by default)

• Markers (P0-S2): advisor writes SENPAI-EXP (lineage/queue/taste) + SENPAI-ADVISOR (heartbeat status); student note that the experiment id comes from SENPAI-EXP. Single-line valid JSON; the console degrades loudly on malformed markers.
• system_instructions/CLAUDE-SUPERVISOR.md: the console's control-agent role. It runs in the console backend today; an in-fleet pod is a documented future option.
• Live event mirroring: k8s/run-senpai-claude.sh mirrors stream-json to $SENPAI_EVENT_DIR/event-*.jsonl when set.
• Console → agent inbox: k8s/senpai-console-inbox.sh (senpai_drain_inbox); advisor/student entrypoints drain $SENPAI_CONSOLE_INBOX_DIR directives into the next prompt under a # Console directives header and archive them. An inbox directive also wakes the advisor when nothing else is actionable.
• k8s/launch.py: --event_dir / --console_inbox_dir threaded into both ConfigMaps (default empty = disabled).
• Docs: CONSOLE-INTEGRATION.md.

Enable

python k8s/launch.py --tag <tag> --target_repo_url <url> --advisor true \
  --event_dir /mnt/new-pvc/senpai-events/<tag> \
  --console_inbox_dir /mnt/new-pvc/senpai-inbox/<tag>

Leave both unset to keep the fleet exactly as it is today.

Verification

• bash k8s/test-senpai-console-inbox.sh — unit-tests senpai_drain_inbox (inert-when-unset, drains+archives, second drain empty). Passes.
• bash -n clean on all modified scripts.
• python k8s/launch.py --dry_run true … renders SENPAI_EVENT_DIR / SENPAI_CONSOLE_INBOX_DIR into every ConfigMap.

Draft because

The entrypoint wiring + event mirroring are additive and inert, but not cluster-tested. Verify on a scratch tag before relying on them. Marked draft pending that check.

🤖 Generated with Claude Code