Agent API Touch-Point Inventory

Complete catalog of all GT↔agent integration points, mapped to source code and the proposed Factory Worker API endpoints.

Ref: gt-5zs8 | Companion: factory-worker-api.md

How to Read This Document

Each touch point lists:

What: What GT does through this touch point
Code: Source files and key functions (line numbers approximate after edits)
Flow: What information moves and in which direction (GT→Agent or Agent→GT)
Fragility: What breaks and why
API mapping: Which Factory Worker API endpoint replaces it

1. Prompt Delivery (tmux send-keys)

What: GT sends text to agent sessions via tmux terminal injection.

Code:

internal/tmux/tmux.go — NudgeSession() (line ~1300): 8-step protocol (serialize → find pane → exit copy mode → sanitize → chunk at 512 bytes → debounce 500ms → ESC + 600ms readline dance → Enter with retries → SIGWINCH wake)
internal/tmux/tmux.go — sendMessageToTarget() (line ~1210): splits at 512 bytes, 10ms inter-chunk delay
internal/tmux/tmux.go — sendKeysLiteralWithRetry() (line ~1253): exponential backoff (500ms→2s cap) for startup race
internal/tmux/tmux.go — sanitizeNudgeMessage() (line ~1179): strips ESC, CR, BS, DEL; replaces TAB with space
internal/tmux/tmux.go — SendKeys(), SendKeysDebounced(), SendKeysRaw(), SendKeysReplace(), SendKeysDelayed() — variant entry points
internal/cmd/nudge.go — runNudge() (line ~196), deliverNudge() (line ~129): CLI entry point, routes by mode (immediate/queue/wait-idle)

Flow: GT→Agent. Text string in, no structured response.

Fragility:

600ms ESC delay must exceed bash readline's 500ms keyseq-timeout; otherwise ESC+Enter becomes M-Enter (meta-return) = no submit
512-byte chunk size is empirical; tmux send-keys has undocumented limits
Sanitization strips control chars but cannot handle all edge cases
No delivery confirmation — GT has no way to know the agent received the message
Per-session channel semaphore (30s timeout) serializes concurrent nudges

API mapping: POST /prompt — structured JSON delivery with accepted/queued response

2. Three Delivery Modes (immediate, wait-idle, queue)

What: GT routes prompt delivery through three modes depending on urgency.

Code:

internal/cmd/nudge.go — mode constants: NudgeModeImmediate, NudgeModeQueue, NudgeModeWaitIdle (lines ~38-44)
internal/nudge/queue.go — Enqueue() (line ~86): writes JSON file to .runtime/nudge_queue/<session>/, atomic naming with nanosecond timestamp
internal/nudge/queue.go — Drain() (line ~143): atomic claim via rename to .claimed, orphan recovery for abandoned claims >5min, expiry filtering
internal/nudge/queue.go — FormatForInjection() (line ~277): formats queued nudges as `` blocks for Claude Code hook injection
internal/cmd/mail_check.go — runMailCheck() (line ~16): UserPromptSubmit hook drains queue + checks mail, outputs injection block
internal/mail/router.go — NotifyRecipient() (line ~1568): wait-idle-first strategy with 3s timeout, queue fallback

Flow: GT→Agent. Immediate: terminal injection. Queue: file→hook→injection.

Fragility:

Queue drain depends on UserPromptSubmit hook — non-Claude agents never drain
TTLs hardcoded (normal: 30min, urgent: 2hr, max depth: 50)
Idle agents never call Drain(), so queued nudges can expire unseen
Witness nudges to Refinery use immediate-only (line ~639 in handlers.go)

API mapping: POST /prompt with priority field (system/urgent/normal)

3. Idle Detection (prompt prefix + status bar)

What: GT determines if an agent is idle (waiting for input) or busy.

Code:

internal/tmux/tmux.go — matchesPromptPrefix() (line ~2261): NBSP normalization (U+00A0→space), matches DefaultReadyPromptPrefix = "❯ " (U+276F)
internal/tmux/tmux.go — IsIdle() (line ~2386): status bar parsing for ⏵⏵ (U+23F5), busy = "esc to interrupt" present
internal/tmux/tmux.go — WaitForIdle() (line ~2321): polls 200ms interval, captures 5 pane lines, returns ErrIdleTimeout
internal/tmux/tmux.go — IsAtPrompt() (line ~2359): non-blocking point-in-time check
internal/tmux/tmux.go — promptSuffixes (line ~1478): [">", "$", "%", "#", "❯"] for dialog detection

Flow: Agent→GT (inferred). GT scrapes terminal output; agent doesn't know.

Fragility:

Prompt prefix ❯ is a Claude Code UI string — any change breaks detection
Status bar ⏵⏵ and "esc to interrupt" are undocumented Claude Code internals
NBSP normalization was a bug fix (issues/1387) for a Claude Code rendering change
Different agents have different prompts — no universal detection
Point-in-time: race between check and state change

API mapping: POST /lifecycle with event: "idle" | "busy"

4. Rate Limit Detection (pane content scanning)

What: GT scans terminal output to detect rate-limited sessions for account rotation.

Code:

internal/quota/scan.go — Scanner struct, ScanAll() (line ~77), scanSession() (line ~99): captures 30 lines of pane content, checks bottom 20 against rate-limit regex patterns
internal/constants/constants.go — DefaultRateLimitPatterns: regex patterns for rate limit messages

Flow: Agent→GT (inferred). GT reads pane; agent doesn't participate.

Fragility:

Regex patterns must match exact rate limit error messages
Messages can change across Claude Code versions
Captures only bottom 20 of 30 lines — rate limit message must be recent
No structured signal from agent that it's rate-limited

API mapping: POST /lifecycle with event: "degraded" + rate limit metadata, or POST /telemetry with rate limit event

5. Account/Quota Management (keychain token swapping)

What: GT rotates API credentials across sessions when accounts hit rate limits.

Code:

internal/quota/keychain.go — Darwin-only (289 lines): KeychainServiceName() (line ~35): SHA-256 hash of config dir, SwapKeychainCredential() (line ~78): backup target → read source → write target, SwapOAuthAccount() (line ~121): swaps .claude.json oauthAccount field, ValidateKeychainToken() (line ~203): checks expiry (JSON, JWT, opaque)
internal/quota/scan.go — ScanAll() (line ~77): scan for rate-limited sessions
internal/quota/rotate.go — PlanRotation() (line ~42): 4-stage pipeline (scan → state manager → planner → executor)
internal/quota/executor.go — Rotator.Execute() (line ~81): atomic execution with flock, concurrent on independent sessions

Flow: GT→Agent. GT swaps credentials; agent is restarted with new token.

Fragility:

macOS-only — entire keychain subsystem is darwin-only, no Linux/Windows
Credential swap requires session restart (kill processes → respawn pane)
OAuth account field location in .claude.json is undocumented
SHA-256 keying assumes Claude Code's keychain service naming convention
No agent-side credential refresh — always a full restart

API mapping: POST /identity with credentials field — runtime applies without restart

6. Session Lifecycle (creation, restart, teardown)

What: GT creates, restarts, and tears down agent tmux sessions.

Code:

internal/session/lifecycle.go — StartSession() (line ~121): 13-step unified lifecycle (resolve config → settings → command → session → env → theme → wait → dialogs → delay → verify → respawn → PID track)
internal/polecat/session_manager.go — Start() (line ~186): polecat-specific session with zombie kill, worktree, beacon, env injection, pane-died hook
internal/witness/manager.go — Start() (line ~107): witness session with zombie grace period, role config, theme, pane-died hook
internal/dog/session_manager.go — Start() (line ~85): dog session via unified session.StartSession()
internal/tmux/tmux.go — NewSessionWithCommand(): single-command session creation, SetAutoRespawnHook() (line ~3126): pane-died auto-respawn with 3s debounce
internal/tmux/tmux.go — KillSessionWithProcesses() (line ~499): 8-step teardown (process group → tree walk → SIGTERM → 2s grace → SIGKILL → pane → session)

Flow: GT→Agent. GT controls entire lifecycle; agent is passive.

Fragility:

13-step creation has many failure points (tmux, dialogs, readiness)
Auto-respawn via pane-died hook depends on tmux's hook mechanism
Kill sequence must handle reparented processes (PPID=1 check)
Zombie cleanup has TOCTOU gap (re-verified before kill)
Session creation takes 5-60s depending on agent startup time

API mapping: POST /lifecycle (agent reports transitions), POST /identity (GT assigns identity at creation)

7. Spawn Admission Control

What: GT gates polecat creation with health checks and capacity limits.

Code:

internal/cmd/polecat_spawn.go — SpawnPolecatForSling() (line ~62): Dolt health check, connection capacity, polecat count cap (25), per-bead respawn circuit breaker, per-rig directory cap (30), idle polecat reuse
internal/polecat/manager.go — CheckDoltHealth() (line ~223): retry with exponential backoff + jitter; CheckDoltServerCapacity() (line ~276): connection count admission gate
internal/witness/spawn_count.go — ShouldBlockRespawn() (line ~74): circuit breaker after 3 respawns per bead, RecordBeadRespawn() (line ~104): flock'd cross-process counter

Flow: GT internal. Admission decisions don't involve the agent.

Fragility:

Polecat cap (25) and dir cap (30) are hardcoded
Circuit breaker state in JSON file (bead-respawn-counts.json)
Dolt health check adds latency to every spawn

API mapping: Internal to GT orchestration — not part of agent-facing API

8. Agent Identity (env vars + preset registry)

What: GT assigns identity to agents via environment variables and a preset registry.

Code:

internal/config/env.go — AgentEnv() (line ~65): generates 30+ env vars including GT_ROLE, GT_RIG, GT_POLECAT, GT_CREW, BD_ACTOR, GIT_AUTHOR_NAME, GT_ROOT, GT_AGENT, GT_SESSION, plus OTEL and credential passthrough
internal/config/agents.go — builtinPresets (line ~164): 10 agent presets (Claude, Gemini, Codex, Cursor, Auggie, AMP, OpenCode, Copilot, Pi, OMP) with 21 fields each (Command, Args, ProcessNames, SessionIDEnv, etc.)
internal/session/identity.go — ParseSessionName() (line ~84), ParseAddress() (line ~30), SessionName() (line ~163): identity parsing and formatting
internal/constants/constants.go — role constants (lines ~196-215): RoleMayor, RoleDeacon, RoleWitness, RoleRefinery, RolePolecat, RoleCrew

Flow: GT→Agent. GT sets env vars; agent reads them.

Fragility:

30+ env vars must be kept in sync across tmux SetEnvironment and exec-env
Three propagation mechanisms (tmux SetEnvironment, PrependEnv inline, cmd.Env) can diverge
Agent preset discovery relies on GT_AGENT or GT_PROCESS_NAMES env vars
Role detection hierarchy (env → CWD → fallback) can produce mismatches

API mapping: POST /identity — structured identity assignment with all fields

9. Priming (context injection)

What: GT injects role context, work assignments, and system state at session start.

Code:

internal/cmd/prime.go — runPrime() (line ~101): full prime or compact/resume path
internal/cmd/prime_output.go — outputPrimeContext() (line ~22): role-specific context rendering; role functions: outputMayorContext(), outputWitnessContext(), outputRefineryContext(), outputPolecatContext(), outputCrewContext(), etc.
internal/cmd/prime_session.go — handlePrimeHookMode() (line ~266): SessionStart hook integration, reads session ID from stdin JSON, persists to disk
internal/cmd/prime_session.go — detectSessionState() (line ~202): returns "normal" | "post-handoff" | "crash-recovery" | "autonomous"
internal/cmd/prime.go — checkSlungWork() (line ~421): detects hooked work, outputAutonomousDirective() (line ~542): "AUTONOMOUS WORK MODE" output
internal/cmd/prime_molecule.go — outputMoleculeContext() (line ~182): molecule progress and step display

Flow: GT→Agent. 10-section output: beacon, handoff warning, role context, CONTEXT.md, handoff content, attachment status, autonomous directive, molecule context, checkpoint, startup directive.

Fragility:

Non-Claude agents without hooks lose automatic priming entirely
Compact/resume path must be lighter to prevent re-initialization loops
Session state detection depends on handoff marker files
Role template rendering uses Go text/template — errors silent

API mapping: POST /context with sections array and mode (full/compact/resume)

10. Hooks (settings.json installation)

What: GT installs hook configurations into agent runtime settings files.

Code:

internal/hooks/config.go — HooksConfig (line ~28): 8 event types (PreToolUse, PostToolUse, SessionStart, Stop, PreCompact, UserPromptSubmit, WorktreeCreate, WorktreeRemove)
internal/hooks/config.go — DefaultBase() (line ~711): base hooks including PR-workflow guard, dangerous-command guard, SessionStart → gt prime --hook, UserPromptSubmit → gt mail check --inject, Stop → gt costs record
internal/hooks/config.go — DefaultOverrides() (line ~199): role-specific overrides (crew PreCompact → handoff cycle, witness/deacon/refinery patrol guards)
internal/hooks/merge.go — MergeHooks() (line ~24): applies overrides in specificity order
internal/cmd/hooks_install.go — runHooksInstall() (line ~48): installs hooks from registry to worktrees, installHookTo() (line ~245): loads, merges, writes settings.json
internal/hooks/config.go — DiscoverTargets() (line ~382): finds all settings files (mayor, deacon, crew, polecats, witness, refinery per rig)
internal/runtime/runtime.go — hook installer registration for 6 providers: claude, gemini, opencode, copilot, omp, pi

Flow: GT→Agent (at install time). Agent reads settings.json; GT wrote it.

Fragility:

Each agent vendor has different hook formats (settings.json, plugins, extensions)
6 different hook providers, each with different file locations
Non-hook agents (no framework) get no hooks at all
Hook merging logic (base → role → rig+role) is complex

API mapping: POST /authorize (replaces PreToolUse guards), POST /context (replaces SessionStart/PreCompact priming), POST /telemetry (replaces Stop cost recording)

11. Guard Scripts (command blocking)

What: GT blocks dangerous or policy-violating commands via PreToolUse hooks.

Code:

internal/cmd/tap_guard.go — runTapGuardPRWorkflow() (line ~34): blocks gh pr create, git checkout -b, git switch -c in Gas Town agent contexts; isGasTownAgentContext() (line ~103) checks GT_* env vars and CWD paths
internal/cmd/tap_guard_dangerous.go — runTapGuardDangerous() (line ~66): blocks 5 patterns: rm -rf /, git push --force, git push -f, git reset --hard, git clean -f; extractCommand() (line ~104) parses Claude Code JSON hook input
Exit code convention: 2 = BLOCK

Flow: Agent→GT→Agent. Agent calls hook → GT evaluates → exit 0 (allow) or 2 (block).

Fragility:

Guards read hook input from stdin in Claude Code's JSON format — format change breaks
Pattern matching is substring-based — can miss variations
Guards fail-open on stdin errors (can't parse = allow)
Only 3 guard scripts; coverage is incomplete

API mapping: POST /authorize — GT evaluates tool calls with full context, returns allow/deny with reason

12. Conversation Log Access (JSONL scraping)

What: GT reads Claude Code's conversation transcripts for cost and session data.

Code:

internal/cmd/costs.go — getClaudeProjectDir() (line ~704): maps workdir to ~/.claude/projects/{slug}/; findLatestTranscript() (line ~717): finds most recent .jsonl; parseTranscriptUsage() (line ~751): line-by-line JSONL scan summing token usage
internal/cmd/seance.go — session discovery from .events.jsonl (line ~61), fallback scan of ~/.claude/projects/ (line ~513), sessions-index.json (line ~674)
Data structure: TranscriptMessage with Type, SessionId, Message.Model, Message.Usage.{InputTokens, CacheCreationInputTokens, CacheReadInputTokens, OutputTokens}

Flow: Agent→GT (inferred). Claude Code writes JSONL; GT scrapes filesystem.

Fragility:

Path encoding convention (slashes→dashes) is undocumented Claude Code internal
JSONL message format, usage field nesting can change without notice
Three independent JSONL parsers (agentlog, costs.go, seance) — no shared code
sessions-index.json format is Claude Code internal
Non-Claude agents don't produce JSONL transcripts

API mapping: POST /telemetry — agent pushes structured usage events

13. Token Usage & Cost Tracking

What: GT computes session costs from transcript token counts and hardcoded pricing.

Code:

internal/cmd/costs.go — 1516 lines total: calculateCost() (line ~801): token→USD using modelPricing map, extractCostFromWorkDir() (line ~823): extract from Claude transcript, runCostsRecord() (line ~956): Stop hook appends to ~/.gt/costs.jsonl, runCostsDigest() (line ~1155): daily digest bead from costs.jsonl
internal/cmd/costs.go — modelPricing (line ~222): hardcoded table (Opus: $15/$75, Sonnet: $3/$15, Haiku: $1/$5 per million tokens, cache read 90% discount, cache create 25% premium)
internal/config/cost_tier.go — CostTierRoleAgents() (line ~44): maps roles to models per cost tier (standard/economy/budget)

Flow: Agent→GT (inferred). GT reads transcripts at session end.

Fragility:

Pricing table is hardcoded — must be updated when Anthropic changes pricing
Cost computed at session end via Stop hook, not real-time
No per-bead cost attribution
Model ID matching is fragile (substring matching against model names)
Non-Claude agents have no cost tracking

API mapping: POST /telemetry with usage.cost_usd — runtime reports cost at source

14. Process Liveness Detection

What: GT checks if an agent process is actually running inside a tmux session.

Code:

internal/tmux/tmux.go — IsAgentAlive() (line ~2157): preferred method, delegates to IsRuntimeRunning() (line ~2091) with session process names
internal/tmux/tmux.go — resolveSessionProcessNames() (line ~2164): priority GT_PROCESS_NAMES env → GT_AGENT env → config fallback
internal/tmux/tmux.go — GetPaneCommand() (line ~1579): #{pane_current_command} via tmux format
internal/tmux/tmux.go — hasDescendantWithNames() (line ~1823): recursive pgrep -P <pid> -l tree walk (maxDepth=10)
internal/tmux/tmux.go — processMatchesNames() (line ~1800): ps -p <pid> -o comm=
internal/tmux/tmux.go — getAllDescendants() (line ~681): deepest-first process tree for safe cleanup
internal/tmux/process_group_unix.go — getProcessGroupMembers() (line ~38), getParentPID() (line ~20), getProcessGroupID() (line ~30)
internal/config/agents.go — ProcessNames per preset: Claude=["node","claude"], Gemini=["gemini"], etc.

Flow: Agent→GT (inferred). GT walks process tree; agent doesn't know.

Fragility:

Process name detection relies on exact binary names
Shell wrappers (e.g., c2claude) require descendant tree walking
pgrep and ps output parsing is platform-dependent
Process can exit between check and action (TOCTOU)

API mapping: GET /health — agent reports its own liveness status

15. Three-Level Health Check

What: GT performs a 3-level health assessment of agent sessions.

Code:

internal/tmux/tmux.go — CheckSessionHealth() (line ~1771): Level 1: HasSession() (tmux session exists?), Level 2: IsAgentAlive() (agent process running?), Level 3: GetSessionActivity() (activity within maxInactivity?)
internal/tmux/tmux.go — ZombieStatus (line ~1723): enum with SessionHealthy, SessionDead, AgentDead, AgentHung; IsZombie() returns true for AgentDead or AgentHung

Flow: GT→GT (internal health assessment).

Fragility:

HungSessionThreshold = 30 minutes (hardcoded default)
Activity timestamp from tmux #{session_activity} — measures any terminal activity, not meaningful agent work
A sleeping agent with no output looks hung even if healthy

API mapping: GET /health — agent reports status, context_usage, last_activity

16. Heartbeat Files

What: GT uses heartbeat files for liveness detection outside tmux.

Code:

internal/polecat/heartbeat.go — TouchSessionHeartbeat() (line ~34): writes JSON to .runtime/heartbeats/<session>.json, IsSessionHeartbeatStale() (line ~74): 3-minute threshold, ReadSessionHeartbeat() (line ~54), RemoveSessionHeartbeat()
internal/deacon/heartbeat.go — WriteHeartbeat() (line ~52): deacon heartbeat at deacon/heartbeat.json with cycle count, health stats; IsFresh() (<5min), IsStale() (5-15min), IsVeryStale() (>15min)

Flow: Agent→GT (implicit). Agent command writes file; GT reads it.

Fragility:

File-based — no notification on write, must poll
Stale threshold (3min) chosen empirically
Heartbeat touch depends on GT commands being called (not agent-initiated)

API mapping: GET /health — agent reports liveness directly; no files needed

17. Working Directory Detection

What: GT determines an agent's working directory through multiple methods.

Code:

internal/tmux/tmux.go — GetPaneWorkDir() (line ~1676): #{pane_current_path} via tmux
internal/workspace/find.go — Find() (line ~29): walks up from CWD looking for mayor/town.json marker; handles worktree paths (polecats/, crew/); FindFromCwdWithFallback() (line ~113): GT_TOWN_ROOT env fallback for deleted worktrees
internal/config/env.go — GT_ROOT env var set in AgentEnv()

Flow: GT→GT (detection) and GT→Agent (env var).

Fragility:

5 detection methods can disagree (tmux CWD, env vars, path parsing, git worktree)
Worktree deletion leaves agent with no valid CWD
GT_TOWN_ROOT fallback exists specifically because worktree cleanup breaks CWD

API mapping: Part of POST /identity — GT assigns working directory

18. Permission Bypass (YOLO flags)

What: GT starts all agents with vendor-specific permission bypass flags.

Code:

internal/config/agents.go — per-preset Args:
- Claude: --dangerously-skip-permissions
- Gemini: --approval-mode yolo
- Codex: --dangerously-bypass-approvals-and-sandbox
- Cursor: -f
- Auggie: --allow-indexing
- AMP: --dangerously-allow-all --no-ide
- OpenCode: env OPENCODE_PERMISSION={"*":"allow"}
- Copilot: --yolo
internal/tmux/tmux.go — AcceptBypassPermissionsWarning() (line ~1509): polls for "Bypass Permissions mode" dialog, sends Down+Enter; DismissStartupDialogsBlind() (line ~1558): blind key sequence fallback

Flow: GT→Agent (at startup). Always-on, no per-role granularity.

Fragility:

10 different flag names across 10 agents — each is a different string
All-or-nothing: no per-role permission granularity
Claude's permission warning dialog detection depends on exact text
No opt-out — every agent runs with full bypass

API mapping: POST /authorize — per-call authorization with role-based rules

19. Non-Interactive Mode

What: GT runs agents in non-interactive mode for specific tasks.

Code:

internal/config/agents.go — NonInteractiveConfig (line ~92): ExecSubcommand (e.g., "exec"), PromptFlag (e.g., "-p"), OutputFormatFlag (e.g., "--output-format json")
internal/config/agents.go — PromptMode (line ~98): "arg" or "none"

Flow: GT→Agent. GT constructs CLI invocation with flags.

Fragility:

Exec subcommand and flag names differ per agent
Output format parsing depends on agent's output structure
Not all agents support non-interactive execution

API mapping: POST /prompt with structured I/O replaces CLI flag composition

20. Session Resume/Fork

What: GT resumes prior sessions or forks them for conversation recall.

Code:

internal/config/agents.go — ResumeFlag, ContinueFlag, ResumeStyle ("flag" vs "subcommand") per preset; BuildResumeCommand() (line ~534)
internal/cmd/seance.go — runSeance() (line ~85): spawns claude --fork-session --resume <id> for predecessor recall
internal/session/startup.go — FormatStartupBeacon() (line ~69): [GAS TOWN] recipient <- sender • timestamp • topic format

Flow: GT→Agent. GT constructs resume command with session ID.

Fragility:

Resume semantics differ per agent (flag vs subcommand)
--fork-session is Claude Code specific
Session ID stored in env vars and files — multiple sources of truth
Beacon format parsed by LLMs — format changes affect comprehension

API mapping: POST /context with mode: "resume" and session history

21. Config Directory Isolation

What: GT isolates agent configuration per account to support credential rotation.

Code:

internal/config/agents.go — ConfigDirEnv (e.g., "CLAUDE_CONFIG_DIR"), ConfigDir (e.g., ".claude") per preset
internal/config/env.go — CLAUDE_CONFIG_DIR set in AgentEnv() (line ~148)
internal/quota/keychain.go — KeychainServiceName() (line ~35): SHA-256 hash of config dir for per-account keychain isolation
Account directory pattern: ~/.claude-accounts/<handle>/

Flow: GT→Agent. GT sets config dir env; agent uses it for all settings.

Fragility:

Config dir layout is Claude Code internal
Symlink switching between accounts is fragile
SHA-256 keying of keychain service names depends on Claude Code convention

API mapping: POST /identity with credentials — runtime manages its own config

22. Theme/Display (tmux status bar)

What: GT applies role-specific tmux status bar themes.

Code:

internal/cmd/theme.go — runTheme(): applies role/rig-specific tmux status line formatting
Applied during StartSession() step in internal/session/lifecycle.go

Flow: GT→tmux. Display-only, doesn't affect agent behavior.

Fragility:

Purely cosmetic — but theme strings used in idle detection (⏵⏵)
Theme depends on tmux being the terminal multiplexer

API mapping: Not part of agent API — display concern stays in GT

23. Agent Output Capture (tmux capture-pane)

What: GT reads agent terminal output for various purposes.

Code:

internal/tmux/tmux.go — CapturePaneTrimmed(), CapturePaneLines(): captures N lines from agent's terminal
Used by: idle detection (5 lines), rate limit scanning (30 lines), dialog detection, readiness polling, nudge verification
internal/telemetry/recorder.go — RecordPaneRead() (line ~266): OTel event for every capture-pane call

Flow: Agent→GT (inferred). GT reads terminal; agent doesn't know.

Fragility:

Terminal content is unstructured text — parsing is always regex/heuristic
Capture-pane only gets visible terminal buffer — scrollback limited
Multi-pane sessions require FindAgentPane() first

API mapping: Eliminated — POST /lifecycle and POST /telemetry provide structured data; no need to scrape terminal

24. Done/Exit Signaling

What: Agent signals work completion through GT commands and intent files.

Code:

internal/cmd/done.go — runDone() (line ~81): persistent polecat model, transitions to IDLE with sandbox preserved; exit constants: ExitCompleted, ExitEscalated, ExitDeferred (line ~65)
internal/cmd/signal_stop.go — runSignalStop() (line ~47): Stop hook handler, checks unread mail and hooked work, returns JSON {"decision":"block"|"approve","reason":"..."}
internal/witness/handlers.go — HandlePolecatDone() (line ~110): processes POLECAT_DONE messages

Flow: Agent→GT. Agent calls gt done; GT processes exit type.

Fragility:

Done detection relies on agent calling gt done (a GT CLI command)
Stop hook must parse Claude Code's expected JSON format
4 exit types but no structured error reporting
Stop state tracking (in /tmp) to prevent infinite block loops

API mapping: POST /lifecycle with event: "stopping" + exit metadata

25. Environment Variable Injection

What: GT injects 30+ env vars into agent sessions via tmux.

Code:

internal/config/env.go — AgentEnv() (line ~65): generates full env map (GT_, BD_, GIT_, CLAUDE_, OTEL_*, credential passthrough)
Three propagation mechanisms:
1. tmux.SetEnvironment() — session-level via set-environment
2. config.PrependEnv() — inline export K=V && before command
3. config.EnvForExecCommand() — cmd.Env append for subprocess
Safety guards: NODE_OPTIONS="" (clears VSCode debugger), CLAUDECODE="" (prevents nested session detection)
Credential passthrough: 40+ cloud API vars (Anthropic, AWS, Google, proxy, mTLS)

Flow: GT→Agent. GT sets env; agent inherits.

Fragility:

Three propagation mechanisms can diverge
env vars visible to any process in the session (security concern)
Credential passthrough list must be manually maintained
tmux SetEnvironment only affects new shell invocations, not running processes

API mapping: POST /identity with env map — single structured delivery

26. Telemetry (OTel integration)

What: GT emits OpenTelemetry metrics and logs for all agent operations.

Code:

internal/telemetry/telemetry.go — Init() (line ~104): OTel provider setup, VictoriaMetrics/VictoriaLogs endpoints, 30s export interval
internal/telemetry/recorder.go — 18 event types: RecordSessionStart(), RecordSessionStop(), RecordPromptSend(), RecordPaneRead(), RecordPrime(), RecordAgentStateChange(), RecordPolecatSpawn(), RecordPolecatRemove(), RecordSling(), RecordMail(), RecordNudge(), RecordDone(), RecordDaemonRestart(), RecordFormulaInstantiate(), RecordConvoyCreate(), RecordPaneOutput(), RecordBDCall(), RecordPrimeContext()
17 OTel Int64Counter metrics (gastown.session.starts.total, etc.)
internal/telemetry/subprocess.go — SetProcessOTELAttrs(): propagates OTEL_RESOURCE_ATTRIBUTES to subprocesses

Flow: GT→Metrics backend. Agent operations tracked by GT, not agent.

Fragility:

OTel export depends on VictoriaMetrics/Logs being available
No correlation ID threads through all events (PR #2068 proposed run.id)
Agent has no say in what's recorded or how

API mapping: POST /telemetry — agent pushes its own events with run_id

27. Event Logging (.events.jsonl)

What: GT logs all significant events to a JSONL file.

Code:

internal/events/events.go — Log() (line ~85), LogFeed() (line ~98), LogAudit() (line ~103): append to .events.jsonl with flock
Event types (lines ~36-77): sling, handoff, done, hook, unhook, spawn, kill, boot, halt, session_start, session_end, session_death, mass_death, patrol_, merge_, scheduler_*
internal/tui/feed/events.go — GtEventsSource (line ~216): tails .events.jsonl for TUI feed display

Flow: GT→File. Events from GT operations, not agent-reported.

Fragility:

Single JSONL file for all events — no rotation or size management
flock serialization can contend under high concurrency
No correlation ID linking events to specific agent runs

API mapping: POST /telemetry events supersede GT-side logging for agent-reported data

28. Zombie Detection & Recovery

What: GT detects and recovers from zombie sessions (tmux alive, agent dead).

Code:

internal/doctor/zombie_check.go — ZombieSessionCheck.Run() (line ~33): filters known GT sessions, excludes crew, calls IsAgentAlive(); ZombieSessionCheck.Fix() (line ~113): re-verifies before kill (TOCTOU guard), never kills crew sessions
internal/daemon/wisp_reaper.go — wisp reaper for stale wisp cleanup
internal/witness/handlers.go — witness patrol with restart-first policy (not nuke-first)
internal/dog/health.go — HealthChecker.Check() (line ~46): dog-specific health check using CheckSessionHealth()
internal/witness/spawn_count.go — spawn storm circuit breaker: ShouldBlockRespawn() (line ~74), escalates to mayor after threshold

Flow: GT→GT. Internal monitoring, agent is passive subject.

Fragility:

Zombie detection depends on process tree walking (platform-specific)
Grace periods and thresholds are empirical (zombie kill grace, hung threshold)
TOCTOU gap between detection and action
Circuit breaker state in JSON file

API mapping: GET /health — agent reports status directly; zombie detection becomes trivial (no response = dead)

Cross-Cutting Themes

Correlation Gap

No single ID connects: OTel event ↔ conversation transcript ↔ cost entry ↔ session event ↔ bead. run_id in the Factory Worker API solves this.

Claude Code Coupling

17 of 28 touch points depend on Claude Code internals:

Prompt prefix (❯), status bar (⏵⏵), JSONL format, config dir layout, keychain service naming, session index, hook JSON format, permission dialog text, bypass flag name, resume flag semantics, sessions-index.json, transcript message structure, usage field nesting.

Agent Parity Gap

Non-Claude agents lose:

Hooks (no automatic priming, guards, or mail injection)
Conversation log access (no JSONL transcripts)
Cost tracking (no transcript to parse)
Resume/fork (different or no mechanism)
Permission dialog handling (different UI)

The Factory Worker API eliminates this — one API, all agents.

Push vs Scrape

Current: GT scrapes 6+ sources (tmux pane, JSONL files, process tree, heartbeat files, keychain, config dirs). Proposed: Agent pushes lifecycle events, telemetry, and health — GT never scrapes.

Summary: Touch Points → API Endpoints

#	Touch Point	Current Mechanism	API Endpoint
1	Prompt delivery	tmux send-keys 8-step	`POST /prompt`
2	Delivery modes	immediate/queue/wait-idle	`POST /prompt` priority
3	Idle detection	prompt prefix + status bar	`POST /lifecycle`
4	Rate limit detection	pane content regex	`POST /lifecycle`
5	Account rotation	macOS keychain swap	`POST /identity`
6	Session lifecycle	13-step tmux create	`POST /lifecycle`
7	Spawn admission	capacity gates	Internal (not agent-facing)
8	Agent identity	30+ env vars	`POST /identity`
9	Priming	10-section text output	`POST /context`
10	Hooks	settings.json install	Multiple endpoints
11	Guard scripts	PreToolUse exit code 2	`POST /authorize`
12	JSONL scraping	filesystem transcript read	`POST /telemetry`
13	Cost tracking	hardcoded pricing table	`POST /telemetry`
14	Process liveness	pgrep tree walk	`GET /health`
15	Health check	3-level tmux check	`GET /health`
16	Heartbeat files	JSON file write/poll	`GET /health`
17	Working dir detection	5 methods (tmux, env, path)	`POST /identity`
18	Permission bypass	10 vendor-specific flags	`POST /authorize`
19	Non-interactive mode	CLI flag composition	`POST /prompt`
20	Session resume/fork	--resume/--fork flags	`POST /context`
21	Config dir isolation	CLAUDE_CONFIG_DIR env	`POST /identity`
22	Theme/display	tmux status bar	Not agent-facing
23	Output capture	tmux capture-pane	Eliminated
24	Done/exit signaling	gt done CLI call	`POST /lifecycle`
25	Env var injection	3 propagation mechanisms	`POST /identity`
26	OTel telemetry	GT-side recording	`POST /telemetry`
27	Event logging	.events.jsonl append	`POST /telemetry`
28	Zombie detection	process tree + thresholds	`GET /health`

28 touch points → 7 API endpoints. Every hack replaced by structured communication.