jackin-capsule

In-container control plane for jackin❯ role containers.

In derived role images, jackin-capsule runs as PID 1 at /jackin/runtime/jackin-capsule. It owns PTYs, sessions, panes, status bar, attach socket, setup, and git trailer hook. The host jackin client attaches to that multiplexer, not container logs.

Shared behaviour: Capsule reference. This README maps crate ownership.

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). Dependencies include jackin-brand, jackin-core, jackin-diagnostics (OTLP), jackin-protocol, jackin-usage, termpane, jackin-tui, TermRock, jackin-agent-status, and jackin-build-meta (build.rs). Must not depend on host runtime (jackin-runtime) or other host binaries — 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 shell, PTY/session authority, owned state subsystems, effectful ports	`tests.rs`, `subsystems`, `ports`
`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/`	composition, chrome/input, ANSI rules, and daemon-facing compositor/input/layout adapters over TermRock and shared operator-info UI	nested; daemon-adapter integration lives in `daemon/tests.rs`
`clipboard.rs` · `clipboard/`	clipboard image staging + idle expiry	`tests.rs`
`runtime_setup.rs` · `runtime_setup/`	in-container git/auth/MCP setup	`tests.rs`
`usage_relay_proxy.rs` · `usage_relay_proxy/`	container-local scoped usage socket and host stdio tunnel	`tests.rs`
`config.rs`	`CapsuleConfig` load/validate	—
`container_context.rs`	container identity metadata and co-located tests	—
`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`	opt-in heap profiler guard	`render_allocation.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.