jackin-capsule

In-container control plane for jackin❯ role containers.

jackin-capsule is copied into derived role images and runs as PID 1 under /jackin/runtime/jackin-capsule. It owns the terminal sessions, PTYs, pane layout, status bar, attach socket, runtime setup, and the in-container git trailer hook. The host jackin binary starts containers detached and attaches through the Capsule client so the operator sees the multiplexer instead of raw container logs.

Design rationale and cross-cutting capsule behaviour live under Capsule reference — this README is the crate orientation record only.

What this crate owns

PID 1 + the in-container multiplexer daemon (session/PTY supervision, attach socket, status bar, control protocol).
Host-side capsule client (stdin/stdout forward, resize, host-affordance bridge).
In-container runtime setup (git/GitHub init, trailer hooks, agent home seeding, auth handoff, Claude MCP registration).
Capsule TUI surfaces, clipboard image staging, firewall/sudo-provision helpers, and usage/telemetry re-exports from jackin-usage.

Not responsible for: protocol encoding (jackin-protocol), host-side launch orchestration (jackin-runtime), or config schema migration.

Architecture tier and allowed dependencies

L4 entry/glue (binary + lib). Allowed workspace dependencies: jackin-core, jackin-diagnostics (OTLP), jackin-protocol, jackin-usage, jackin-term, jackin-tui, jackin-agent-status, jackin-build-meta (build.rs). Must not depend on host-side runtime (jackin-runtime) or other host binary crates — the capsule is a different process tree.

Structure

Module	Owns	Tests
`lib.rs`	crate root, logging/usage re-exports	—
`main.rs`	binary entry (PID 1 / client / exec subcommands)	—
`daemon.rs` · `daemon/`	multiplexer daemon event loop	`tests.rs`
`session.rs` · `session/`	per-agent PTY sessions	`tests.rs`
`client.rs` · `client/`	host-side attach client	`tests.rs`
`client_writer.rs`	sole attach-socket writer	—
`attach_context.rs`	single host-connection state	—
`attach_protocol.rs`	attach lifecycle helpers	—
`protocol.rs` · `protocol/`	capsule wire framing helpers	—
`tui.rs` · `tui/`	in-container TUI render/input	nested
`clipboard.rs` · `clipboard/`	clipboard image staging + idle expiry	`tests.rs`
`runtime_setup.rs` · `runtime_setup/`	in-container git/auth/MCP setup	`tests.rs`
`config.rs`	`CapsuleConfig` load/validate	—
`container_context.rs` · `container_context/`	container identity metadata	`tests.rs`
`agent_status.rs` · `agent_status/`	capsule-facing status hooks	nested
`pid1.rs` · `pid1/`	reaper + signal forward	`tests.rs`
`exec.rs` · `exec/`	`jackin-exec` / capsule exec	`tests.rs`
`firewall.rs` · `firewall/`	allowlist egress apply	`tests.rs`
`sudo_provision.rs` · `sudo_provision/`	per-profile sudo grant	`tests.rs`
`exit_assess.rs` · `exit_assess/`	dirty-exit modal assessment	`tests.rs`
`git_context.rs`	branch/dirty/PR for status bar	—
`pr_context.rs`	GitHub PR lookup	—
`pull_request.rs` · `pull_request/`	PR snapshots for TUI	`tests.rs`
`socket.rs` · `socket/`	Unix attach socket helpers	`tests.rs`
`mcp_server.rs`	MCP stdio for `jackin_exec`	—
`output.rs`	plain stdout/stderr writers	—
`services.rs` · `services/`	side-effect adapters	—
`util.rs` · `util/`	shared bounded helpers	`tests.rs`
`wordlist.rs` · `wordlist/`	tab codenames	`tests.rs`
`alloc_telemetry.rs` · `alloc_telemetry/`	opt-in heap telemetry	`tests.rs`
`debug_panic.rs` · `debug_panic/`	force-panic debug hook	`tests.rs`

Public API

tui::pane_snapshot exposes pane_content_from_damagegrid and range-scoped pane_content_range_from_damagegrid for content-coordinate row materialization (bench + selection/link paths).

Library surface for integration tests and the binary: daemon, client, config, session, tui, protocol, runtime_setup, plus logging/telemetry/usage re-exports from jackin-usage. Most modules are pub so tests/ and the binary can call them without spawning a PTY; production consumers outside this crate should not depend on capsule internals.

How to verify

cargo nextest run -p jackin-capsule
cargo clippy -p jackin-capsule --all-targets -- -D warnings

Capsule e2e/smoke is a CI mandate under .github/ — any PR that touches this crate must note the smoke block.