Terminal Channel Worker

Use this skill when the user wants a real terminal/TUI channel instead of the direct CLI path.

What you run:

1. attach a terminal to LionClaw,
2. type messages as a local peer,
3. see answer, reasoning, status, and error lanes in separate regions.

Under the hood, the worker:

1. restores the latest interactive session snapshot for (channel_id, peer_id),
2. posts inbound text to /v0/channels/inbound pinned to the chosen session_id,
3. long-polls /v0/channels/stream/pull,
4. renders typed outbound events in separate terminal regions,
5. starts recovery actions through /v0/sessions/action,
6. advances its consumer cursor through /v0/channels/stream/ack.

Prerequisites

• python3
• uv
• A configured LionClaw runtime if channel attach needs to start LionClaw for you

Setup

1. Register the skill and channel:

lionclaw skill add skills/channel-terminal --alias terminal
lionclaw channel add terminal --launch interactive

2. Attach your terminal to the interactive channel:

lionclaw channel attach terminal

If LionClaw is not already running, channel attach will start it for you. Passing --runtime <id> pins that attached worker's turns to the requested runtime.

For a fresh manual test home in one command:

./scripts/bootstrap-terminal-test.sh /tmp/lionclaw-terminal-e2e

That helper gives a fresh test home its own loopback bind, so it does not inherit state from another LionClaw daemon already running elsewhere on your machine.

For repeated manual testing, you can use the repo helper:

./scripts/attach-terminal-test.sh /tmp/lionclaw-terminal-e2e

Notes

• LionClaw enforces pairing. The TUI shows pending pairing state and the exact approval command to run through lionclaw channel pairing approve ....
• The worker defaults to channel_id=terminal and peer_id=$USER (falling back to $USERNAME or local-user).
• channel attach restores the latest history_policy=interactive session for that peer, renders the last 12 durable turns into the answer pane, and resumes a still-running answer stream from the last durable checkpoint when one exists.
• The TUI restores or opens the interactive session before sending, then echoes your message with a local pending state, follows live queue.* / runtime.* stream events for the active turn, and reconciles completed turns from the kernel turn_completed snapshot.
• Channel-scoped stream messages without session_id / turn_id are rendered as activity only; they must not select or pin the active interactive session.
• Slash commands are built into the TUI:
  • /continue
  • /retry
  • /reset
  • /quit
  • /exit
• The Answer pane is durable session history plus live answer deltas rendered as Markdown.
• The Thinking pane is live-only. It does not replay historical reasoning on attach.
• Runtime selection normally comes from the running LionClaw daemon, unless you pass lionclaw channel attach <id> --runtime ..., which pins that attached worker to a specific runtime.
• Attach only reuses a daemon when that daemon belongs to the same LIONCLAW_HOME, current project, and daemon-compatible config, including runtime, preset, and workspace settings.
• A shell debug harness is available in scripts/debug-worker.sh.