[playb0t]

Description

Depends on #544; this branch is on top of it.

Cleanup commands now share one 5 s budget, which leaves 1 s under the sandbox's 6 s outer guard to join killed children. Each command gets the smaller of its own 5 s limit and what is left of the budget; once the budget is spent, no further cleanup command starts and cleanup reports a failure. A timed-out command is killed and its promise settles on close, so the caller cannot move on while the CLI is alive. On POSIX the CLI runs in its own process group and the existing killChildTree helper kills the group.

The README's host section now describes the budget, and says that an exhausted budget is a cleanup failure that can leave resources for operator recovery.

Fixes #546

Trade-off to decide: the 5 s budget can reject a cleanup that used to succeed between 5 and 6 s. If you prefer another split under the guard, it is the two constants at the top of podman.ts.

Overlap: #431 adds a shared cleanup-deadline contract of its own (cleanupDeadlineMs → terminate), with an immediate timeout rejection and a direct-child kill; the two need to be reconciled if both land. #495 shares the CHANGELOG, the README and the sandbox tests.

Type of change

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)
• This change requires a documentation update (README host section, included)

How Has This Been Tested?

• Two new regression tests in test/sandbox.test.ts fail before the change and pass after it.
• The full package suite under c8 on top of the JS-COMPAT branch on main e75013f9: 163 passed, 0 failed, 0 skipped; line coverage 94.06%. buf generate, tsc -p tsconfig.build.json and tsc --noEmit pass.
• Real rootless Podman 5.7.0 with the MCP TypeScript SDK 1.32.0 client, the same cases before (with fix(oci-javascript): use supported Podman network cleanup #544 only) and after. These runs were on the earlier base bc096453; the files they exercise are byte-identical on e75013f9:
  • ordinary call and a single 3 s cleanup delay: the result 42 in both;
  • three cleanup commands delayed by 2.4 s: before, the reply arrived with the network rm CLI still alive; after, no cleanup CLI was alive at the reply, and the network was left for explicit recovery, reported as a cleanup failure;
  • a 3 s execution deadline: timed_out: true in both;
  • a cleanup CLI held for 5.5 s: after the change it was gone before the reply.

Test Configuration:

• Toolchain: Node 26.8.1, npm 11.12.1, rootless Podman 5.7.0 (WSL2 Ubuntu, cgroup v2)
• SDK: MCP TypeScript SDK 1.32.0

Not run: Windows (no process group), D-state processes, a failing kill, other Podman versions, the Moon wrapper.

Checklist:

• My code follows the style guidelines of this project
• I have performed a self-review of my own code
• I have commented my code, particularly in hard-to-understand areas
• I have made corresponding changes to the documentation (README and CHANGELOG)
• My changes generate no new warnings
• I have added tests that prove my fix is effective or that my feature works
• New and existing unit tests pass locally with my changes
• Any dependent changes have been merged and published in downstream modules (depends on fix(oci-javascript): use supported Podman network cleanup #544)

[oracle-contributor-agreement]

Thank you for your pull request and welcome to our community! To contribute, please sign the Oracle Contributor Agreement (OCA).
The following contributors of this PR have not signed the OCA:

• PR author: playb0t
• w0rldlogic.0point@proton.me (@playb0t)

To sign the OCA, please create an Oracle account and sign the OCA in Oracle's Contributor Agreement Application.

When signing the OCA, please provide your GitHub username. After signing the OCA and getting an OCA approval from Oracle, this PR will be automatically updated.

If you are an Oracle employee, please make sure that you are a member of the main Oracle GitHub organization, and your membership in this organization is public.