feat(shell): enable manual harness and runtime shell resumption

[nborges-aws]

Description

This PR enables resumption of shell sessions, via a --shell-id flag. Both harness and runtime now accept --shell-id in parallel to --session-id to connect to a shell. Upon connection, the shell ID is printed alongside a reconnect command, with populated flags (and reminds users to reprovide bearer token where needed).

Also updates command documentation and associated shell tests.

Verification

#### TERMINAL A (initial connection to shell)
nickdb@7cf34dd82df3 SimpleRuntimeProject % ac-dev runtime shell --id <REDACTED_RUNTIME_ID> --qualifier DEFAULT --region us-west-2
Connecting to Runtime <REDACTED_RUNTIME_ID> (DEFAULT)...
Connected - session <REDACTED_SESSION_ID> - shell <REDACTED_SHELL_ID> - Ctrl+D or 'exit' to quit
To reconnect: agentcore runtime shell --id <REDACTED_ID> --qualifier DEFAULT --session-id <REDACTED_SESSION_ID> --shell-id <REDACTED_SHELL_ID> --region us-west-2
[agentcore-runtime-user@localhost /]$ export SMOKE_TEST='connected to shell in new window!'
[agentcore-runtime-user@localhost /]$
Shell attached from another client.


#### TERMINAL B (reconnection to shell)
nickdb@7cf34dd82df3 SimpleRuntimeProject % ac-dev runtime shell --id <REDACTED_RUNTIME_ID> --qualifier DEFAULT --session-id <REDACTED_SESSION_ID> --shell-id <REDACTED_SHELL_ID> --region us-west-2
Connecting to Runtime <REDACTED_RUNTIME_ID> (DEFAULT)...
Connected - session <REDACTED_SESSION_ID> - shell <REDACTED_SHELL_ID> - Ctrl+D or 'exit' to quit
To reconnect: agentcore runtime shell --id <REDACTED_RUNTIME_ID> --qualifier DEFAULT --session-id <REDACTED_SESSION_ID> --shell-id <REDACTED_SHELL_ID> --region us-west-2
[agentcore-runtime-user@localhost /]$ echo $SMOKE_TEST
connected to shell in new window!

Type of Change

• Bug fix
• New feature
• Breaking change
• Documentation update
• Other (please describe):

Testing

How have you tested the change?
Manual smoke testing with verification posted above. Also added tests focused around shell resumption behavior, all passing.

• bun run test (4579 pass, 0 fail)
• I ran npm run test:unit and npm run test:integ
• I ran npm run typecheck
• I ran npm run lint
• If I modified src/assets/, I ran npm run test:update-snapshots and committed the updated snapshots

Checklist

• I have read the CONTRIBUTING document
• I have added any necessary tests that prove my fix is effective or my feature works
• I have updated the documentation accordingly
• I have added an appropriate example to the documentation to outline the feature, or no new docs are needed
• My changes generate no new warnings
• Any dependent changes have been merged and published

---

By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the
terms of your choice.

[agentcore-devx-automation]

Claude Security Review: no high-confidence findings. (run)

[agentcore-devx-automation]

AgentCore Harness Review

Verdict: Looks good

Reviewed the diff for feat(shell): enable manual harness and runtime shell resumption. The implementation is clean and symmetric across the runtime and harness paths:

• A new --shell-id flag is added to both agentcore runtime shell and agentcore harness shell, validated with a shared shellIdSchema, and gated behind --session-id with a clear InputValidationError.
• shellId is threaded end-to-end: handler flags → launch context → request normalizer → core opener → SDK input, and the server-assigned shellId is surfaced back on RuntimeShellSession.
• ShellOperation.run now prints a copy-paste reconnect command (and reminds the user to re-supply --bearer-token), which is a nice UX win. The bearer token is intentionally omitted from the reconnect string — good.
• TUI deep-linking only forwards the launchContext when launch.runtimeId === runtimeId, so a user switching runtimes via the picker won't accidentally send a stale shellId.
• Tests cover the new flag plumbing, the --shell-id without --session-id validation, bearer-token omission in the reconnect hint, and the end-to-end CLI → endpoint-picker → openShell path.

No telemetry gap worth flagging — telemetry in this repo lives at the router layer, not inside shell handlers.

Nothing I'd block the merge on.

[codecov-commenter]

Codecov Report

❌ Patch coverage is 93.87755% with 3 lines in your changes missing coverage. Please review.
✅ Project coverage is 96.60%. Comparing base (fdf9cf2) to head (1e4db55).

Files with missing lines	Patch %	Lines
src/core/runtimeShell.ts	40.00%	3 Missing ⚠️

Additional details and impacted files

@@             Coverage Diff              @@
##           refactor    #2607      +/-   ##
============================================
+ Coverage     96.58%   96.60%   +0.01%     
============================================
  Files           700      700              
  Lines         57638    57681      +43     
============================================
+ Hits          55672    55723      +51     
+ Misses         1966     1958       -8     

☔ 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.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[notgitika]

LGTM