28 lines
2.9 KiB
Markdown
28 lines
2.9 KiB
Markdown
|
---
|
||
|
|
id: "0036"
|
||
|
|
date: 2026-07-13
|
||
|
|
status: Accepted
|
||
|
|
supersedes:
|
||
|
|
superseded-by:
|
||
|
|
affected-paths: [plugins/os-backlog/bin/wakeup-poll, plugins/os-backlog/lib/backlog/wakeup.rb]
|
||
|
|
affected-components: [os-backlog]
|
||
|
|
---
|
||
|
|
|
||
|
|
# 0036 — tmux session convention for AI-run sessions: cc-<project>-<purpose>
|
||
|
|
|
||
|
|
## Context
|
||
|
|
|
||
|
|
Issue #28 chose tmux (not headless claude -p / Agent SDK) as the execution surface for issue-triggered wakeup (ADR-0035), because the human must be able to discover, inspect, and take over an AI-run session. The naming/lifecycle convention is useful beyond wakeup — any long-running or unattended AI session benefits — so it is recorded as its own ADR. No existing tmux naming habit to preserve (no tmux server was running at spike time).
|
||
|
|
|
||
|
|
## Decision
|
||
|
|
|
||
|
|
(1) Naming: AI-run sessions are named `cc-<project>-<purpose>[-<n>]` — `cc-` prefix marks Claude-operated sessions, `<project>` is the index-row project name (ADR-0034), `<purpose>` is short kebab-case (wakeup sessions use `issue<N>`, e.g. `cc-llf-schema-issue12`), `-<n>` only disambiguates collisions. Human personal sessions never take the `cc-` prefix. (2) Creation: whoever needs the session creates it — the wakeup poller (ADR-0035) for issue wakeups, a human for anything else — via `tmux new-session -d -s <name> -c <project-root> ...` so the pane starts in the project. (3) Lifecycle: a session is killed after clean completion once its closing artifact exists (for wakeups: the triage/summary comment posted on the issue); it is kept alive on error or whenever hitl input is needed, so the evidence and the takeover point are the same pane. Discovery is `tmux ls` — the `cc-` prefix makes AI sessions self-listing; an os-backlog-adjacent listing command is an explicit non-goal for now. (4) Attach/takeover: attaching pauses nothing — the pane runs an interactive Claude Code session, so a human who attaches can simply type into it; there is no separate handover protocol.
|
||
|
|
|
||
|
|
## Consequences
|
||
|
|
|
||
|
|
Easier: one glanceable namespace (`tmux ls | grep ^cc-`) for everything the AI is running on a machine; takeover is native tmux attach, no tooling. Harder: kill-on-clean-completion means a successful session leaves no scrollback — the issue comment is the record, so sessions must actually post it before exiting (the wakeup prompt makes this the final required step); session names carry no timestamp, so a stale kept-alive session must be triaged by attaching, not by name.
|
||
|
|
|
||
|
|
## Alternatives rejected
|
||
|
|
|
||
|
|
1) Headless execution (claude -p / Agent SDK) — rejected by the human for this stage: no inspection or takeover surface; may return later for pure afk-ready work once trust is established. 2) Timestamped session names (cc-<project>-20260713-...) — rejected: names become unreadable in tmux ls and collisions are rare enough for -<n>. 3) Keep every completed session for audit — rejected: the durable record belongs on the issue/card (ADR-0033 spirit), and dead sessions accumulate into noise.
|