feat(execd): add bounded command inventory

[cwj2001]

Summary

• add additive, bounded GET /command inventory for commands retained by the current execd controller
• provide running filtering, opaque filter-bound cursor pagination, terminal-entry cap/TTL retention, and bounded JSON responses
• publish the OpenAPI contract and C#, Go, JavaScript, Kotlin, and Python SDK surfaces
• add deterministic smoke helpers, CI gates, runtime/controller/router coverage, and operational documentation

Closes #1308

Contract

This is a runtime-local observation API, not durable command history or audit storage. It exposes no command content, environment, stdin, output, or log paths.

• Cursors are opaque, tied to the exact running filter and current controller instance. Preserve the filter for every page; after restart/controller replacement or a different instance, omit the cursor and restart pagination.
• Pagination is weakly consistent. Retention bounds terminal observations; it does not replace existing status/log endpoints.
• All inventory responses, including handler and authentication errors, use Cache-Control: no-store.
• No SSE/subscription/replay/backpressure surface and no process-group remediation are included.

Known compatibility boundary

The inventory TTL/cap applies only to its metadata index. Existing known-ID status/log/interrupt compatibility still uses commandClientMap, whose terminal kernels can retain command content for the controller lifetime. That legacy retention is not presented as solved here; it is tracked separately in #1403.

Verification

• Execd package, inventory lifecycle, controller/router, race, smoke-helper, shell-syntax, and diff-whitespace checks
• Cross-platform expiry smoke regression: observe running inventory, terminal inventory, and eviction before checking legacy compatibility; smoke TTL uses a 2-second scheduling margin while runtime exact-TTL boundaries remain unit-tested
• Python inventory tests (83), Pyright, and reproducible --target execd generated-client synchronization
• Go SDK test, vet, and build
• JavaScript typecheck, lint, generated contract synchronization, and inventory tests (10)
• Kotlin Spotless and sandbox tests
• Documentation build and repository license verification
• Independent review of runtime/API, SDK contract, cache policy, generated JavaScript API docs, and public documentation

Generated Python OpenAPI models are intentionally excluded from canonical Ruff/Pyright checks. The checked-in Execd endpoint docs are regenerated through the tested, failure-safe uv run python scripts/generate_api.py --target execd path; generator-format findings are not hand-edited.

Compatibility

• Additive API; existing command routes and payloads are unchanged
• No breaking changes

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: e6ad87e11b

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[cwj2001]

Follow-up: the original unfiltered GET /command shape is being revised before merge. It exposes an unbounded process-lifetime retained registry while the issue described no history. The target is now a filtered, bounded, cursor-paginated query over process-local retained metadata. Rationale and recovery boundaries are documented in issue #1308; no merge is requested until the revised contract, tests, Windows evidence, generated clients, and CI are complete.

[cwj2001]

The PR is being reduced before merge to an active-only bounded query (GET /command?limit=&cursor=). The broader retained-metadata filter/history direction is intentionally deferred; see the latest issue #1308 update for the recovery rationale and scope boundary.

[cwj2001]

Marked draft while the implementation is narrowed. The next revision will address the concrete review items without expanding this PR into retained-command history management:

• replace the unbounded retained-map enumeration with bounded active-command discovery using limit and cursor;
• preserve existing known-ID status/log/interrupt behavior;
• remove the dead optional-runner fallback and test-only production hook;
• align the new identifier field with the established session naming;
• add the requested registration/list concurrency coverage and race evidence.

The existing process-lifetime retention of terminal commandClientMap entries (including command content) is a separate lifecycle-retention question. This draft will not add LRU/TTL/metrics without an explicit design decision, so it does not silently change existing status/log compatibility.

[cwj2001]

Superseded the prior active-only snapshot proposal and force-updated this Draft PR to the bounded Command Inventory contract: running filter, opaque filter-bound cursor pagination, terminal cap/TTL retention, five SDKs, smoke/CI coverage, and documentation. The PR remains Draft pending upstream CI.

[cwj2001]

Revised while Draft after independent review: removed the unused Python generator target and JS/Kotlin leap-second scope; added no-store coverage for handler and unauthorized inventory errors; clarified filter-bound cursor behavior in OpenAPI, generated JS IntelliSense, and all SDK guides; restored a working Jupyter quick start. The bounded inventory core and #1403 legacy-retention boundary are unchanged. Local focused verification is documented in the PR body. Returning this PR to Ready for review now.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 0bed5b4c0d

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: a0b5f3dd6a

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 4c01f4d2df

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[cwj2001]

Rewrote the Draft branch history into four coherent review commits without changing the final patch (verified byte-equivalent to the pre-compression branch): core feature/API/SDK surfaces; tests and CI; targeted Python generation support; and human-facing documentation. This removes transient add/revert and iterative bot-fix commits so each remaining commit is independently reviewable.