Repository navigation
Description
Summary
The JVM libraries need an owned terminal-application API shared by Java, Kotlin, Clojure and every current Scala variant. Existing pane creation, shell-command completion and output subscriptions provide useful pieces, but callers still assemble application execution, input, exact exit and cleanup themselves.
Motivation
A Java consumer should run a literal executable/argv application through a scoped owner and receive a bounded result after cleanup. Kotlin coroutines, Clojure tasks and Scala effect scopes need their own native interfaces to the same responsibility. Cancelling an owning run must settle its application; cancelling an output reader or exit observation must leave the owner reachable.
Evidence
Current shared core and facade boundaries
Pane.runcompletes commands in an existing POSIX shell. Its timeout/interruption contract leaves the command running.- Kotlin
Pane.runadapts that behavior through interruptible Java calls. Coroutine cancellation does not add application ownership. Capabilitiesis the canonical feature registry. Expose the capability map through the public API #164 already tracks exposing it publicly, and Add a capability manifest andLIBTMUX_test rules for Clojure #153 tracks Clojure capability projections and test rules.settings.gradle.ktsdeclares the native facade modules, including Scala direct, Cats and Ox, plus Clojure and its optional core.async adapter. These share one Java engine.
This is a source-based proposal. The managed application contract has not been qualified through these public JVM surfaces. #143 provides private server startup, which is adjacent to application ownership.
Proposal
Add a shared immutable ProgramSpec, ProgramResult and typed ProgramExit, plus an owning Java Program with AutoCloseable and Server.runProgram:
- Accept literal executable/argv, including zero arguments, cwd, environment and terminal geometry. Validate before dispatch; distinguish setup/exec failure, normal nonzero exit, signal, cancellation, timeout and uncertain observation.
- Register ownership and exit observation before launch. Provide literal input, bounded rendered screen/output, observation-only waits and explicit termination. Finish the final output drain before completing the result.
- Make owning run interruption, timeout and scope release terminate and settle owned work. Preserve interruption and the primary failure, carrying cleanup failure and reachable recovery separately. Borrowed sessions, panes and control clients must survive.
- Reuse the existing command transport, control client, byte subscriptions and generation/receipt machinery. Keep blocking explicit in Java; use bounded execution and notification callbacks for nonblocking callers. Cancelling a
CompletableFuturemust not be treated as proof that its responsible worker or terminal application exited. - Gate every composed application feature from the canonical table using the actual accepted daemon version and generation. Refuse unavailable features before creating panes, files or waiters; a newer client executable cannot enable an older daemon. Public native discovery, generated capability metadata and MCP must disclose the same decisions and any intentional fallback.
One shared initial PR must include native APIs, examples and acceptance for all these facades:
- Kotlin: suspend
runProgram,spawnProgramand an owningwithProgramscope, with sealed outcomes and boundedFlowobservation. Parent cancellation awaits cleanup through the existing bounded I/O policy; cancelling a collector closes only its subscription. - Clojure:
run-program!,start-program!,wait-program!,terminate-program!andwith-program, checked option maps, immutable namespaced result data and one opaque owner. Route owning task cancellation to core termination; keep blocking work outside core.asyncgoblocks. Namespace loading must stay free of processes and executors. - Scala direct: scoped opaque Program handles, native options/outcome ADTs and
Usingortry/finallythat preserve primary and close failures. - Scala Cats/FS2:
Resourceacquisition and release through the bounded execution policy, cancellation-safe awaited cleanup, and bounded byte/gap streams whose consumer release leaves the Program owner alive. - Scala Ox: a supervised owning scope and
Flowobservation with explicit subscription cleanup and interruption behavior. Qualify its release behavior independently from Cats.
The initial PR should state its delivered subset. Continue with byte-bounded streaming and explicit gaps, incremental decoding/final flush, readiness predicates, controller-crash leases/recovery and structured MCP start/input/read/wait/terminate tools. Keep rendered screen state separate from byte output. All facades reuse the Java gates and protocol implementation; they need native usability proof rather than separate engines.
Acceptance needs complete programs and critical tests in every listed facade: zero-argument/Unicode argv, arbitrary output bytes, fast exit, final-burst output, interactive input, slow readers, early stream release, owning cancellation during acquisition/run/cleanup, paired failures, external respawn, daemon replacement and borrowed-resource survival. Prove old-daemon/new-client refusal before effects, release/patch/RC boundaries, generated forwarder/metadata drift and deliberate disabled-gate controls. Test current supported JDK/package consumers; experimental variants absent from the registered build must retain an explicit unqualified status.
References
- Add Server.start and drop run.sh from the API examples #143: private-server startup foundation.
- Expose the capability map through the public API #164 and Add a capability manifest and
LIBTMUX_test rules for Clojure #153: public core discovery and Clojure capability projections. - Close the release, facade and error gaps an adoption review found in Clojure #151: existing Clojure release, facade and error gaps.
- Add a standalone, CI-run example program for each core capability #129: complete native capability examples.
Activity