Skip to content

session(feat): Track fresh program lifetimes - #833

Draft
tony wants to merge 28 commits into
masterfrom
feat/823-program-lifecycle
Draft

tony wants to merge 28 commits into
masterfrom
feat/823-program-lifecycle

Conversation

@tony

@tony tony commented Nov 6, 2026 •

Copy link
Copy Markdown
Member

A creation reply does not establish program exit, and a short-lived program can disappear before its status or output is read. The new lifecycle handle establishes retention and observation before launch.

Session.start_program(argv) returns an owned handle after pane retention and native exit observation are ready. Call wait() for immutable exit evidence, send_text() for literal terminal input, collect() for a bounded rendered capture, terminate() to close the owned pane and PTY, and cleanup() to remove a completed pane. Session.run_program(argv) owns that sequence and returns a ProgramResult containing exit evidence and the final screen. Both factories accept cwd, environment and terminal geometry. Cancelling a wait leaves the program and observers usable. The borrowed parent session and unrelated panes survive cleanup.

Program.recovery reports whether creation was never submitted, a receipt is unavailable, the original pane was recorded, or removal was verified. Its immutable snapshot also reports pending native-client or capture-buffer cleanup. Partial-start and capability-probe failures retain unclosed clients for retry. Retrying client cleanup rechecks cancellation and the deadline before another command is dispatched. A missing receipt does not authorize numeric pane reacquisition or prove creation failed.

The feature requires a connected tmux 3.8+ daemon; libtmux's core minimum remains 3.2a. Server.capabilities() reports the connected daemon identity, daemon version and named feature support. Unknown versions and 3.8 prereleases refuse program operations before effects. Original creation installs the ownership nonce. A generation observer distinguishes the launched program from a later respawn, and destructive commands consume its pending registration in the same native queue as pane removal. Input replaces its observer before consuming the previous registration. Missing or changed evidence refuses the operation and retains the operation and cleanup failures. Custom dispatchers that cannot honor the bound are refused before effects.

Capture contains rendered retained history and screen, with separate decoded-text and transport limits. An attributed temporary buffer excludes hook output, validates the captured byte count and preserves unrelated buffers. Failed buffer cleanup retains the validated screen and pending cleanup evidence for retry. Capture is not a lossless program byte stream. Termination establishes pane removal, not the exit of every descendant process. This synchronous API requires multi-element argv and one caller at a time; handles cannot be reused after fork. Controller-crash cleanup remains undelivered. Existing creation methods and Server.wait_for retain their behavior; this branch imports no unmerged waiter, engine or ownership implementation.

The runnable example creates an isolated server without caller configuration or attachment variables, cancels and retries observation, sends literal input, asserts status 7 and rendered output, preserves its parent through job cleanup, and keeps operation and cleanup failures together. A separate blocking CI job builds the pinned stable tmux 3.8 source without a version-only binary cache. Existing build and release jobs are unchanged.

Native client errors and debug records now omit command payloads. The original exception retains command elements for explicit inspection. This keeps argv and environment values out of implicit error formatting without replacing typed native failure evidence.

Native evidence: tmux 3.8 registers and filters event waits, identifies the exited pane in its event payload, and refuses to wake a missing waiter. A control command reply is registration evidence, not program completion.

Validation at 4cdc8da33dbb93bc5b4c45292e2d44501b08c6a6:

  • PASS: 61 native program/capability cases on stable tmux 3.8, with one platform-specific skip. They cover exit/signal evidence, replacement programs, cancellation, input, capture attribution and retained cleanup obligations.
  • PASS: Ruff, formatting, full-project mypy and support-script typing pass. Warning-free Sphinx and an isolated Python 3.11 wheel consumer pass for the command-payload source; all 36 packaged files match. The final two commits change only a test type refinement and CI token permissions.
  • PASS: causal regressions reject dispatch after retired-client cleanup observes cancellation or exhausts the deadline. A real child closes both pipes before exiting; the old empty-selector wait fails the new guard, and the bounded process-exit wait passes without changing deadlines.
  • PASS: deliberate breaks expose stale daemon discovery, replacement input, capture contamination, lost creation receipts and forgotten pending native clients. An independent native probe confirms plain and hooked capture return the same application output.
  • PARTIAL: the intermediate full 3.8 lane exceeded the standalone example's one-second subprocess limit after retries. Paired native traces subsequently found repeated 50 ms empty-selector delays and show that bounded process waits remove those delays. The timeout itself was not reproduced, so this does not establish its sole cause. The original failure remains recorded and the limit is unchanged.
  • PASS: the current matrix and second matrix run pass every daemon lane and the dedicated tmux 3.8 job at this head; release was skipped. The first correction exposed a test-only mypy inference error, reproduced locally and fixed. One duplicate 3.7a job reached its CI time limit; its targeted rerun passed without a source or timeout change. The cancellation remains recorded.
  • PASS: independent follow-up review accepts the synchronous/recovery contract and command-payload correction at this exact head. Every applicable dimension meets 9.5/10. Real stderr, control-error and process-wait cases preserve typed failure evidence without implicitly formatting the submitted command payload.

Async ownership, raw streaming, readiness predicates, descendant completion and controller-crash leases remain separate portfolio work. MCP integration is being developed against an explicit source pin in its own repository. Earlier failed and over-budget runs retain their original dispositions.

Refs #823. Existing interactive-shell command execution, lossless byte streaming, whole-process-tree termination and older-version event adapters remain separate contracts.

The earlier blocking native-3.8 job and cache correction in #825 remain historical evidence. This branch changes no coverage threshold. The initial contract remains a draft for maintainer integration; the broader portfolio is incomplete.

@codecov

codecov Bot commented Nov 6, 2026 •

Copy link
Copy Markdown

Codecov Report

❌ Patch coverage is 66.62321% with 256 lines in your changes missing coverage. Please review.
✅ Project coverage is 54.62%. Comparing base (9d30fe2) to head (4cdc8da).
⚠️ Report is 1 commits behind head on master.

Files with missing lines Patch % Lines
src/libtmux/program.py 67.41% 173 Missing and 46 partials ⚠️
src/libtmux/capabilities.py 51.35% 18 Missing ⚠️
examples/owned_program.py 70.21% 11 Missing and 3 partials ⚠️
src/libtmux/session.py 57.14% 3 Missing ⚠️
src/libtmux/server.py 50.00% 2 Missing ⚠️
Additional details and impacted files
@@            Coverage Diff             @@
##           master     #833      +/-   ##
==========================================
+ Coverage   52.09%   54.62%   +2.53%     
==========================================
  Files          26       29       +3     
  Lines        3751     4518     +767     
  Branches      747      878     +131     
==========================================
+ Hits         1954     2468     +514     
- Misses       1493     1697     +204     
- Partials      304      353      +49     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

tony added 2 commits November 6, 2026 20:20
why: Creation replies do not establish program exit, and short-lived
programs can disappear before callers read their status or output.

what:
- Retain fresh program panes and register native observers before launch
- Separate exit waits, bounded capture, termination, and owned cleanup
- Guard destructive commands with creation and program lifetime evidence
- Preserve cancellation, original causes, and paired cleanup failures
- Add native regressions, documentation, and a blocking tmux 3.8 CI job
why: The stable tmux feature job executes native lifecycle tests but
omits their coverage from the repository report.

what:
- Collect coverage XML from the program lifecycle tests
- Upload it with the existing Codecov action and token
- Preserve legacy jobs and coverage thresholds
@tony
tony force-pushed the feat/823-program-lifecycle branch from 544261c to a344534 Compare November 7, 2026 02:20
tony added 6 commits November 6, 2026 20:45
why: Keep development and CI linting on the same Ruff release,
including corrected f-string conversions and safer lint fixes.

what:
- Raise Ruff floors in the development and lint dependency groups
- Lock Ruff 0.17.3 with its published source and wheel hashes

Ruff release notes:
https://github.com/astral-sh/ruff/releases/tag/0.17.2
https://github.com/astral-sh/ruff/releases/tag/0.17.3
why: Contributors need the lint-tool requirement alongside other
development environment changes.

what:
- Document the Ruff 0.17.3 minimum for development and lint checks
why: The program lifecycle PR must build against the current library
without depending on experimental engines.

what:
- Preserve native program ownership while taking current trunk changes
- Resolve the Python floor and dependency lock conflicts
- Keep changelog reconciliation in a separate commit
why: Readers need both the current release notes and the program
lifecycle contract after the branch incorporates trunk.

what:
- Preserve current trunk changelog entries
- Describe the owned program handle under its delivering PR
why: A client version and a numeric prefix do not establish whether
the connected daemon has the released program lifecycle primitives.

what:
- Expose immutable daemon identity and feature decisions
- Share release ranking between discovery and program admission
- Refuse unknown spellings and prereleases before pane creation
- Document discovery and cover release boundaries
why: The Python3.11 floor makes the cleanup-loop performance
suppression unnecessary, and Ruff rejects unused suppressions.

what:
- Retain the broad-exception annotation used for cleanup evidence
- Remove only the unused performance annotation
tony added 16 commits November 15, 2026 14:22
why: Strict type checking rejects reusing integer version variables for
the string fields returned by the release pattern.
what:
- Keep next-release integer fields separate from matched release fields.
- Preserve the existing version ordering and capability decisions.
why: A short observation budget can expire before the capture client
starts, leaving its cleanup behavior untested.

what:
- Expire the deadline only after the real capture client is acquired
- Retain original interruption identity and verify client cleanup
- Reap captured clients even when a cleanup assertion fails
why: Callers need separate owning runs and interactive lifetimes, with
recoverable failures and output attributed to the launched program.
what:
- Export Program and immutable exit, screen and completion results.
- Add working directory, environment, geometry and guarded literal input.
- Capture through an owned buffer so hook output cannot enter the result.
- Preserve capture and cleanup errors for retry without replacing ownership.
- Update callers, executable examples, API docs and the tmux 3.8 CI lane.
why: The release notes must distinguish owning completion from an
interactive handle and state the cleanup boundary.
what:
- Describe configuration, input, structured results and capture ownership.
- Record connected-daemon capability discovery and the feature minimum.
why: The program candidate must include the current Python trunk.
what:
- Merge the upstream uv 0.13.8 pin without changing program behavior.
why: Callers need a runnable recovery path that distinguishes cancelling
an observation from terminating its program.
what:
- Cancel a wait, clear its event, submit literal input and wait again.
- Assert the program completes and the borrowed parent survives cleanup.
- Update the standalone output fixture and interactive documentation.
why: Server.capabilities is a callable discovery operation.
what:
- Use its method reference in the program release note.
why: The standalone example needlessly launched a second application to
show cancellation, pushing its CI fixture past the existing process budget.
what:
- Use one interactive program for cancellation, literal input and status 7.
- Assert its rendered reply and preserve the same cleanup checks.
- Keep the standalone fixture's one-second limit.
why: Adapters must retain unresolved ownership without treating every
partial-start failure as a leaked pane or discarding unclosed clients.
what:
- Export immutable pane disposition and cleanup status snapshots
- Retain native clients until their close operation succeeds
- Retry pre-creation client cleanup without querying a nonexistent pane
- Cover missing receipts, client close failures and public recovery docs
why: Callers need to distinguish partial-start ownership from verified
cleanup when handling a failed program operation.
what:
- Document creation disposition and retained native client cleanup
why: A failed native client close can outlive a capability probe, so
callers need its original owner to retry cleanup without losing the client.
what:
- Attach recovery evidence when capability probe clients remain unclosed
- Preserve ordinary capability error types when cleanup has settled
- Exercise constructor and query-close failures through the public probe
why: Probe callers need to retain failed native-client cleanup owners.
what:
- Document capability probe ownership on cleanup failure
why: Retrying an unclosed native client can exhaust the request deadline or observe cancellation before the next command is admitted.
what:
- Recheck the deadline and cancellation flag after retired clients settle.
- Prove both boundaries using a retained native client and refuse a later dispatch.
why: The program recovery contract also applies to retrying native client cleanup.
what:
- Document the deadline and cancellation check before a subsequent command.
why: An empty selector cannot observe child exit and can spend the remaining polling interval asleep after the native client has finished.
what:
- Wait on the child with the existing bounded interval once both pipes reach EOF.
- Keep timeout and cancellation budgets unchanged.
- Exercise real pipe EOF before child exit and reject empty-selector waits.
why: Program completion no longer waits on an empty selector after pipe EOF.
what:
- Describe the bounded process-exit wait and unchanged operation deadlines.
tony added 2 commits November 15, 2026 20:27
why: Native command failures and debug records can otherwise render
application argv and environment values in downstream logs.

what:
- Keep tuple command elements available through explicit inspection
- Redact automatic command representations and debug metadata
- Use the same protected tuple for subprocess timeout failures
- Exercise real stderr, control-frame and process-wait failures
why: Program error and debug output must describe its payload policy.

what:
- Distinguish redacted messages from explicit command inspection
tony added 2 commits November 15, 2026 20:47
why: The shared subprocess base type does not expose command payloads to type checkers.
what:
- Refine both native failure types before checking their retained command
why: The native program job only needs to check out source.
what:
- Set explicit read-only contents permission for the tmux 3.8 job

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant