Known gaps

Command surface redesign (CLI-only; deliberately diverges from the Python CLI)

The CLI has a fixed command surface that the Python CLI does not have. Python tests for the removed behavior were deleted (not skipped) and their entries removed from python-tests-to-port.txt; the replacements are named after the new behavior (tests/test_cli/test_command_surface.test.ts, test_run_command.test.ts, test_exec_command.test.ts). Differential cases under parity/diff/ that exercised removed spellings were updated or dropped; the oracle is still used for everything that did not change.

• Removed: user-configurable [shortcuts] (config keys, config init --reset-shortcuts, LazyGroup merge), top-level init and install, sandbox process start, sandbox shell-stream, sandbox run, global --profile and -t/--timeout, deploy --traditional, template.yaml custom_commands (and its placeholder substitution), the server_port reserved kwarg. Fixed top-level shortcuts: create list info kill exec connect upload download run deploy.
• Added: abx exec (--cwd --env --timeout --background --stream), abx sandbox command {list,run} and the top-level abx run, abx config init --build/--llm.
• Differences from the Python client for named commands: run prints JSON for non-string results; --server-port is an explicit option; there is no extra --key value passthrough (use --arg KEY=VALUE or --json-args).
• abx exec with several words uses exact argv quoting; use sh -c '...' for shell syntax.

agent/mcp, agent/mcp_http, agent/tools (builder agent-B)

Behaviour was checked differentially against the Python oracle (python -m agent_sandbox.agent.mcp over stdio, and the Starlette/uvicorn create_mcp_app over raw sockets): 61 HTTP request cases and 41 auth cases are byte-identical (status line, header names/order, body); the 28-line stdio script is identical except for the Python defect below. The items here are the only known differences.

• Python float/int distinction in JSON. Fixed: the MCP servers (stdio and HTTP) parse requests with utils/_pyjson.ts (floats: "py"), so whole floats stay PyFloat (id: 1.0, timeout: 30.0, 1e400 -> Infinity), big ints are bigint, and echoes match the Python server byte for byte (tests/test_agent/test_mcp_pyjson_oracle.test.ts replays 42 oracle-recorded request lines; parity/diff/mcp_toolerr.mjs sends the same lines in every platform-error mode).
• Lone surrogates. "\ud83d" in a request is echoed as the escaped text by JSON.stringify; Python keeps the raw surrogate (and then fails to UTF-8-encode it). Unreachable with real MCP clients.
• Object key order for integer-like keys. Fixed on the observable paths: _pyjson records the insertion order of parsed objects with integer-like keys in a hidden PY_KEY_ORDER symbol, and pyEntries() (used by pyRepr, pyJsonDumps, orjsonDumps, printDict and the pydantic dict validator/dumps) honours it. Not honoured: object spread / destructuring of a parsed dict (the hidden order is lost) and the orjson Connect codec (json_decode uses JSON.parse; its decoded dicts are consumed field by field and never re-printed).
• json.loads(bytes) encodings. UTF-8/UTF-8-BOM, UTF-16 and UTF-32 bodies are decoded like json.detect_encoding; surrogatepass (lone surrogates encoded in UTF-8) is not accepted (-> 400 "Invalid JSON").
• STDIO invalid UTF-8. Python's line.decode("utf-8") is outside its try, so a non-UTF-8 line crashes the server. Node answers -32700 Parse error: invalid UTF-8 in message and keeps serving.
• STDIO final line without a newline. Matches Python on purpose: a last message that EOF completes (no trailing \n) is never answered, because asyncio cancels its task before the first step (only its parse error is written). Multi-line chunks follow asyncio task order: parse / size-limit errors are written while the chunk is scanned, the answers of the valid lines follow in order (parity/diff/mcp_stdio_order.mjs, 120 random chunkings identical). Whether a request that needs network I/O is answered before later quick ones is a latency race in both runtimes.
• STDIO overlong line followed by data. Python's _discard_overlong_line clears the StreamReader buffer behind asyncio's back; with a continuously writing client the paused transport is not resumed and the next message after the Message exceeds the STDIO size limit error can be lost. Node keeps the message (the documented intent).
• Cancellation. asyncio cancels the tool coroutine; Node cannot abort an in-flight SDK call. On SIGTERM/SIGINT/EOF in-flight tool calls are abandoned without a response, and a create_sandbox that completes after shutdown() kills the sandbox it just created (Python would leak it) and answers with no result.
• STDIO from a regular file. python -m agent_sandbox.agent.mcp < file fails in Python (Pipe transport is for pipes/sockets only); the Node server reads files fine.
• Stack traces in logs (logger.error(..., exc_info=True)) are JS stacks instead of Python tracebacks.
• Allow header of /health 405s. Python joins a set (HEAD, GET or GET, HEAD depending on hash seed); Node always sends GET, HEAD.
• uvicorn identity. The Node server does not send server: uvicorn; Node adds its own connection/keep-alive headers. serveMcpApp prints uvicorn-style startup/access lines to stderr (same texts as uvicorn 0.54 at log_level="info") but does not implement uvicorn CLI options (workers, TLS, proxy headers, ...).
• ASGI module entry point. uvicorn agent_sandbox.agent.mcp_http:asgi_app has no Node meaning; use getAsgiApp() / asgiApp (a node:http listener) from src/agent/mcp_http.ts. deploy templates must target Node.
• SSE. The Python transport never streams (GET /mcp is 405), and neither does the Node one.

Tests not ported verbatim

• tests/test_agent/test_mcp_http.py::TestMcpHttpApp (Starlette TestClient) runs against the real node:http listener on an ephemeral loopback port through a small request helper instead of an in-process ASGI client; every collected case (120 across test_mcp/test_mcp_http/test_tools, parametrised ones included) has a same-named Node test with the same assertions.
• test_mcp_stdio.py spawns the real abx mcp start --api-key ... --api-url ... --template ... (src/bin/abx.ts, with ABX_MCP_RUNTIME_DIR), as in the original repo; src/agent/mcp_main.ts (python -m agent_sandbox.agent.mcp) is covered by test_mcp_stdio_loop and the differential harnesses.

Differential harnesses (parity/diff, need ORACLE_VENV)

• mcp_toolerr.mjs: tool-error text of both stdio servers over 97 stub platform / envd behaviours x 96 tool calls (3492 comparisons, plus the stub request logs) - identical.
• mcp_stdio_order.mjs: random chunked STDIO scripts (valid, malformed, blank, non-object, notifications) - identical.
• error_str_gen.py -> tests/fixtures/error_str_oracle.json -> tests/test_agent/test_error_str_oracle.test.ts: str() / message / code / suggestion / to_dict of every SandboxError subclass (42 classes x variants). Root cause of the former [E2000] log difference: agent/mcp.ts and agent/tools.ts formatted exc.message where Python formats str(exc); they now use pyExcStr (also for the JSON-RPC -32603 text).

api / protocol / session (builder core-B)

Everything in src/api, src/protocol, src/session is a line-by-line port; tests/test_api, tests/test_protocol and tests/test_session are ports of the client-sdk tests (438 tests). Differences and omissions:

Tests not ported (with reason)

• *SyncVariants classes and stream_sync tests (test_commands, test_files, test_code, test_sandbox, test_process): they exercise the Python make_sync/run_sync blocking wrappers. Node has no sync seam; every API is async/await.
• test_deploy.py / api/deploy.py (Sandbox.deploy, in-sandbox agent deployment): not reached by any CLI command, so not ported. Sandbox.deploy does not exist in the Node port.
• isinstance(x, float) assertions: JS numbers carry no int/float distinction; the numeric value is asserted instead.
• DeprecationWarning assertions (pytest.warns): warnings go through sandbox._seams.warn(message, category) and tests assert on that seam.

Tests adapted (same name, different mechanism)

• test_docker_builder.py::TestInjectSdkWheel: Python auto-detects a source checkout via parents[4]/server-sdk and sys.frozen. Node has neither; pip wheel is only used for an explicit project_root option or ABX_SERVER_SDK_SOURCE, otherwise the released agent-sandbox-server wheel is downloaded from PyPI through the httpx shim (trust_env: HTTP(S)_PROXY / ALL_PROXY / NO_PROXY and SSL_CERT_FILE / SSL_CERT_DIR, SHA-256 verified; stubbed in tests). A failed fetch still falls back to the Dockerfile's pip install only after that request fails, the same as Python; the download is not skipped in favour of an unpinned install when a proxy or private CA is set. "frozen binary" -> "no explicit source => never spawns pip"; "checkout is detected" -> resolves ../../python-sdk/server-sdk through the env/option.
• test_fc_template.py::TestRequireSDK: module reload with sys.modules[...] = None is replaced by making _sdkLoader.load throw. Client-class patches (patch(...client.Client)) are replaced by _sdkLoader.load returning the real @alicloud/fcsandbox20260509 models with a fake Client; request assertions use camelCase model fields (body.buildConfig.copy.image).
• test_template.py/test_sandbox.py: time.sleep / time.monotonic / uuid.uuid4 patches use the module _seams objects (protocol/template._seams.sleep, code._seams, commands._seams, fc_template._seams).
• httpx_mock (pytest-httpx) is replaced by tests/helpers/httpxMock.ts (useHttpxMock(), the single shared helper, also used by the transport/utils tests; supports add_exception), which runs the real HttpClient over core-A's MockTransport; reusable by other test suites.

Behavioural differences

• File locking: Python filelock.FileLock (flock) -> a mkdir-based lock with stale-lock recovery in src/session/local.ts; same mutual-exclusion semantics, but not released automatically if the process is SIGKILLed (stale detection takes over after the timeout).
• YAML: the yaml package (YAML 1.1 rules) in src/utils/yaml_io.ts; PyYAML's exception text is not reproduced.
• Alibaba Cloud FC SDK: npm @alicloud/fcsandbox20260509 is 1.5.1, the Python wheel is 1.6.0. Request/response models used by fc_template (CreateTemplate/UpdateTemplate/GetTemplate/ListTemplates/ListTeams) are identical in both; newer 1.6.0-only fields are not used by the CLI. All fc_template functions are async (blocking in Python). SDK exception text (Error: <code> <message> Response: <data>) is reconstructed from the Tea error fields.
• base64 decoding in process streams follows CPython binascii semantics exactly (src/protocol/_b64.ts), including "Incorrect padding" errors.
• DockerBuilder: no checkout autodetect / frozen-binary logic (see above). Proxies and SSL_CERT_FILE / SSL_CERT_DIR on the PyPI wheel download and ACR token fetch are honoured (not a gap).

agent/qwen_code, clarify, codegen, adopt, coding_agent, template_guide, dockerfile_sources (builder agent-A)

Intentional changes

• template_guide: provider template profile. The guide, the codegen prompt, and abx template init describe one selected provider profile (cli/src/providers/template_profile.ts), not the old single Python prompt. alicloud-express uses the FC base image and platform start_cmd (no Dockerfile CMD / ENTRYPOINT). Any other provider uses the generic profile (python:3.12-slim, CMD ["python3", "commands.py"]) unless abx-provider.toml has a [template] table. A missing profile is announced and is never the FC image. The install snippet names agent-sandbox-server. commands.py calls serve() only under if __name__ == "__main__". The prompt is no longer byte-identical to tests/fixtures/agent/golden.json.

Behavioural differences

• All QwenCodeBackend methods are async: backend delegation uses dynamic import() (keeps coding_agent import-light; proven by an esbuild import-closure test). generateTemplateFiles, runResearch, evaluate, runQwenCodeHeadless, downloadAndInstallStandalone are async too; prepareWorkdir, validateTemplateWorkspace, the adopt functions and buildTemplateGuide are sync.
• Python syntax check (commands.py in generated templates): pythonSyntaxCheck spawns a real interpreter (python3, then python, then py -3) running ast.parse and maps SyntaxError to the same message shape. The lexical fallback lexicalSyntaxCheck is used ONLY when no interpreter can be run. It emits CPython 3.11-style messages for: NUL bytes, unterminated strings, unterminated triple-quoted strings, bracket mismatch/unclosed brackets, trailing backslash at EOF, unexpected indent and unindent mismatch. It does NOT check the grammar (e.g. x = = 1 passes). With an interpreter the SyntaxError text is that of the host Python version.
• NUL bytes in a Python source are always reported as invalid (Python 3.11 raises an uncaught ValueError).
• Archives: .tar.gz/.tgz/.tar and .zip only; bz2/xz tarballs are unsupported. Absolute names, .. escapes, escaping/absolute symlinks and device nodes are rejected exactly like Python's _validate_tar_members.
• YAML (src/utils/yaml_io.ts): yaml package; parse errors read differently from PyYAML's. validateTemplateWorkspace returns plain data (use dumpYaml to write it back).
• OSError text uses Node errno messages; spawn failures are mapped to Python-style [Errno N] ....
• Integral JSON floats ({"result": 1.0} in headless output) become 1 (JS has no int/float distinction), so json.dumps of such a value differs from Python (1.0 vs 1). The golden case uses 1.5.
• Proxies: macOS/Windows system proxy settings are not read (env vars only).
• ResearchOutcome has no JS truthiness: use .ok / researchSucceeded.
• Dockerfile EXPOSE: superscript digits are not treated as digits (Python's Unicode-aware str.isdigit() accepts them).
• Windows Path normalisation is approximate.
• KeyboardInterrupt is exported from agent/qwen_code; the CLI must map it to exit code 130.

Test environment

• test_template_guide (capability groups, __all__, serve port, reference commands.py run) and the CPython cross-checks of test_codegen (TestPythonSyntaxCheck) are skipped, with a [tests] SKIPPED ... notice on stderr, when python3 / the Python server SDK source is unavailable. golden.json stays the default oracle (the TestGuideGolden tests need nothing). See "Optional Python oracle in the test suite" in docs/PORTING.md.

models / utils / transport (builder core-A)

• tests/test_utils/test_async_bridge.py (not ported, whole file). run_sync/make_sync bridge sync callers onto an asyncio loop. There is no async_bridge module in the Node port (run_sync/make_sync were intentionally not ported; everything is already async), and utils/index.ts does not export them.
• TestEnvdStreamStreaming::test_cancellation_closes_stream_and_client. JS has no asyncio task cancellation; the test cancels with gen.return() while next() is pending and asserts the response and client are closed.
• test_equivalence_random_three_way_splits. random.Random(42) is replaced by a deterministic mulberry32 PRNG (same split-point logic, different sequence).
• pytest fixtures replaced by local helpers in tests/_support/ (caplog.ts for caplog, env.ts for the autouse conftest isolation, patch.ts for patch("httpx.AsyncClient"), tar.ts; pytest-httpx lives in tests/helpers/httpxMock.ts). The assertions are unchanged.
• CommandArg (server dataclass used by test_coerce) is reproduced locally in the test.
• Pydantic. Models are zod schemas (src/models/base.ts); the pydantic error text is not reproduced (a ValidationError lists the offending fields). Numbers and booleans still accept their string forms and dates accept ISO text or epoch seconds/milliseconds.
• httpx. src/transport/_httpx.ts is an httpx 0.28 shim over fetch/node:http; HTTP/2 and httpx connection-pool limits are not reproduced.

Integration verification (cross-slice, after all four slices existed)

parity/diff/mcp_toolerr.mjs (needs ORACLE_VENV) drives the Python oracle MCP stdio server and the Node one with 96 malformed / unauthorized / missing-sandbox / unreachable tool calls against 36 stub platform+envd behaviours (401/403/404/409/422/429/5xx, garbage/empty/array/null bodies, socket reset, closed port, DNS failure, envd failing in the same ways, undecodable file bytes): 3492 response lines and all stub request logs (method, path, body, auth headers) are byte-identical after port/multipart-boundary normalisation. Defects found and fixed by it: array-valued Host header rejected by node:http (every real request failed), connect failures worded [Errno 111] ... instead of anyio's All connection attempts failed, float(timeout) / .encode() / bytes.decode(encoding) / multipart-file type errors surfacing as Node errors, and json_decode using V8 error text instead of orjson.JSONDecodeError.

Remaining known differences of those areas:

• orjson decoder (transport/codec.ts): error text/position follows orjson 3.13 for all 44k mutation-fuzz cases; not reproduced: the recursion/allocation limits for pathologically nested input (failed to allocate memory) and integers/floats beyond the double range other than the infinity check.
• bytes.decode(encoding) (protocol/filesystem.ts): exact UnicodeDecodeError/LookupError/TypeError text for utf-8 (+aliases, utf-8-sig), ascii and latin-1; other codecs (utf-16, cp125x, ...) use Node's TextDecoder and their error text is approximate.
• TCP connect errors: every OS-level connect failure (refused, unreachable, timed out, ...) is reported as anyio does (All connection attempts failed); DNS failures keep [Errno -2] Name or service not known. Success paths of the envd Connect/stream tools were not covered by the differential script (only failure/malformed paths).
• Integer-like JSON keys inside tool arguments, floats such as timeout: 30.0 echoing as 30: see the MCP section.

cli command layer and output (src/cli/{main,kit,types,prompts,errors,io,output,formatters,table,region,repl,scaffold}.ts, src/bin/abx.ts)

Commands are parsed and rendered by commander (declared through src/cli/kit.ts), tables are plain text (src/cli/table.ts) and colours come from picocolors; none of this is byte-compatible with Click 8.5 or Rich any more. The scaffold templates remain byte-identical to render_scaffold. The items below are the known differences.

• Ctrl+R / readline details. abx connect line editing uses Node's readline (Up/Down history, Emacs keys). Python's GNU readline additionally offers reverse incremental search (Ctrl+R) and its inputrc customisations; Node's readline does not. History lives only in memory for the process (as in Python, which never wrote a history file either).
• SIGINT outside the REPL. src/bin/abx.ts prints Aborted! and calls process.exit(1) on SIGINT. Python raises KeyboardInterrupt inside the running coroutine, so finally/async with cleanup blocks run; in Node they do not (the Node event loop cannot be interrupted at an arbitrary await). Exit code and message are the same.
• Module loading. Lazy specs are "commands/<module>:<attr>" and loaded with dynamic import() through mainSeams.importModule; Python used importlib.import_module(...). A missing attribute raises AttributeError with the Python message text.
• renderScaffold returns a Map (insertion order = file render order) instead of a dict; OutputFormatter JSON output also uses Map where key order matters.
• No run_sync bridge. Everything is async/await; the Python tests that patch agent_sandbox.utils.async_bridge.run_sync are ported by spying on the Sandbox static methods instead.
• OutputManager options accept the camelCase names (jsonMode, noColor, logLevel) and the Python snake_case names as aliases; json_mode / no_color are also readable properties. Method names are camelCase (startActivity, liveSpinner, ...); spinner/activity take a callback instead of being context managers.
• str(exc) for non-SDK exceptions. pyStr mimics Python's str() for SDK errors, httpx errors and the common built-ins; for arbitrary JS Errors it uses message, which differs from Python's text for exotic exception types.
• Node fs errors. Only the errno codes in toOSError's table are translated to the Python OSError message text ([Errno 2] No such file or directory: ... and friends); any other code surfaces the Node message.
• Rich and Click are gone. Help pages follow commander's layout (Usage: abx sandbox exec [options] <SANDBOX_ID> <COMMAND...>, no paragraph re-wrapping), tables are plain aligned text with a two-space gutter and no wrapping, and usage errors keep Click's wording only where kit.ts rewrites them (No such option, Missing argument, Invalid value for, No such command). Exit codes are unchanged (2 for usage errors, including UsageError raised in a callback). Prompts (src/cli/prompts.ts) use @inquirer/prompts on a terminal and a one-line-per-answer fallback for piped input.
• Importing main.ts has side effects (it may create ~/.abx/config.toml on a fresh install, as Python does at import of cli.main). Tests therefore import tests/_support/isolatedHome.ts first.

Sandbox sub-commands (sandbox_files, sandbox_process, sandbox_system)

Differential harness: ORACLE_VENV=$ORACLE_VENV node parity/diff/sandbox_subcmds.mjs (264 cases against stub control-plane/envd servers: help text, errors, exit codes, --json/--quiet, interactive confirm, request logs). Result: 0 differing cases; 2 cases marked KNOWN (first item below).

• --verbose / --log-level DEBUG lose SDK log lines (root-command seam, not owned by the sandbox sub-commands). The Node main.ts import chain configures the SDK loggers before OutputManager installs its root bridge; Python imports the SDK lazily after the bridge exists. The sandbox sub-commands already import the SDK lazily (_connectSandbox), but the fix has to land in main.ts / utils/logging.ts.
• --json / orjson float handling (fixed). formatters._printJson serialises through src/cli/_orjson.ts (orjsonDumps): NaN/Infinity become null, float exponents match orjson 3.13, and integers outside the 64-bit range raise. Sandbox modules still pass Map / PyFloat / bigint so integral floats keep a trailing .0.
• sandbox_system keeps a module-local float-preserving JSON loader (_jsonLoads, validated with pyJsonLoads) so system metrics renders 1.0 / 2.50 exactly as Python; and emulates Python's rich/quiet-mode errors for non-str table cells (item N index and message) in system packages.
• exec wraps execution_time in PyFloat so JSON output keeps Python float rendering.
• The sandbox sub-command modules import Sandbox lazily through _connectSandbox; tests spy on Sandbox.connect, as the Python tests patch Sandbox.connect.

Main sandbox commands (sandbox.ts, _coding_agent.ts)

Differential harness: ORACLE_VENV=$ORACLE_VENV node parity/diff/sandbox_cmds.mjs [--only <substr>] [--verbose] [--show] (~560 cases against stub platform/envd servers incl. Connect-framed envd, an https stub for the in-sandbox SandboxServer (throw-away openssl cert, exact SANs), a scripted Qwen Code binary and a pty driver parity/diff/pty_run.py for tty prompts / Ctrl-C / Ctrl-D / connect: help text, errors, exit codes, --json/--quiet/--verbose combos, prompts, NL create pipeline, run (mechanism A and B), upload/download edge cases, region/timeout precedence, kill --all per HTTP failure class, request logs). Result: 538 cases, 5 differing (all the run mechanism-B SDK JSON-parse gap below); the timing-based request-timeout cases can flake when the machine is loaded (re-run --only request-timeout).

• No run_sync bridge: Python tests patching run_sync / Sandbox.create / Sandbox.connect use vi.spyOn(Sandbox, ...); module-attribute patches became seam objects: sandboxSeams {stdinIsatty, access, discoverImport}, codingAgentSeams {stdinIsatty, resolveBackend} (read at call time).
• Filesystem order (resolved): Python's Path.rglob("*") (used by create --upload and upload) yields raw os.scandir order, pre-order, symlinked dirs listed but not followed; _rglob reproduces it with fs.opendirSync().readSync() (Node's readdirSync sorts). discover sorts by code point like Python's sorted(). Covered by differential cases "upload many files raw order" / "create upload many files raw order" / symlink trees.
• _activity_kwargs signature introspection is impossible in TS: _activityKwargs always passes onActivity when a live status line exists (the Python helper only drops it for callables without the parameter). Checked at all four call sites: the only callee that can lack the parameter is a test double; every in-repo backend accepts on_activity.
• _discover_registered_commands cannot import and execute Python modules. The default sandboxSeams.discoverImport is a no-op (the helper is not called by any Python command path either); tests inject their own importer.
• test_run_command_server: the declarative.decorator.sandbox._registry patch is dropped (no equivalent registry in Node).
• run wraps execution_time / float JSON values in PyFloat so 1.0 renders like Python.
• _coding_agent.ts reads config_cmd._effectiveValue results as unknown and casts them to string | null | undefined.
• test_create_route_guard_and_unknown_cmd: the mocked sandbox gained id/status/url/info members because the TS create reads them directly (Python used MagicMock).

• Helpers exported for the template builder: _phaseStatus(out, msg, body) (callback form of the Python context manager), _generateLocalTemplate, _activityKwargs, and from _coding_agent: resolveCodingAgentBackend, ensureCodingAgentBinary, resolveCodingAgentCredentials.

• Minimal edits outside the owned files (needed for Ctrl-C parity, verified by pty cases): src/cli/repl.ts inputInterrupts plus ^C/^D echo (Python asyncio.run swallows the first Ctrl-C while input() blocks, the second raises inside input() -> Disconnected.; a swallowed first Ctrl-C surfaces as Aborted!/exit 1 when the coroutine returns or before the next command is run).

• run mechanism B values come from the SDK's response.json() (transport/_httpx.ts uses JSON.parse): floats with integral value (2.0), integers beyond 2**53 and a top-level JSON array body differed from Python (2 / 12345678901234567000 / exit 0 + blank line, instead of 2.0 / 12345678901234567890 / "Unexpected error: 'list' object has no attribute 'get'"). Fixing it needs a float/bigint-preserving parse (e.g. the Map/PyFloat parser already in sandbox_system.ts/mcp.ts) in api/sandbox.ts _callServerCommand plus a non-dict check in _custom; SDK owner. dict/list/None/bool values are rendered with Python str() in the CLI. Differential cases "run B result float|big|json array body" still differ (5 cases).
• create --request-timeout <= 0: the CLI raises the SDK's ValueError itself with the Python float repr (got 0.0), because the SDK only sees a JS number (got 0).
• api/capability.ts template rglob ordering is still sorted (not owned here).

config_cmd (commands/config_cmd.ts, utils/_tomllib.ts)

Differential harness: ORACLE_VENV=$ORACLE_VENV node parity/diff/config_cmds.mjs [--only <substr>] [--verbose] [--jobs N] (~1450 cases incl. ~58 pty wizard / masked-input cases, 78 warn-transport cases that drive sandbox list to print the transport loader's WARNING: Failed to load <config.toml>: <tomllib message> line; isolated HOME and cwd, no real credentials, ABX_NO_KEYCHAIN=1). Result: 0 differing cases and no output normalisation other than the temp-dir path.

• utils/_tomllib.ts: faithful port of CPython 3.11 tomllib (table order, floats, exact TOMLDecodeError / UnicodeDecodeError messages). Used by config_cmd and by transport/config.ts _loadTomlFile (smol-toml is no longer imported by src/). The transport loader also reproduces dict.update / in errors for a non-table transport value, [Errno 13] Permission denied texts, and date/time reprs (datetime.date(2024, 1, 1)) in pydantic messages. models/_pydantic.ts was touched minimally: int accepts PyFloat (integral value OK, fractional -> int_from_float) and pyTypeName honours __pytype__.
• No import cycle: config_cmd resolves main.handleErrors lazily when a command runs. Import order no longer matters.
• Seams: module attributes tests monkeypatch in Python are the mutable configSeams object (_ABX_DIR, _CONFIG_FILE, _ENV_FILE, sys, loadConfigDict, readEnvVar, writeEnvVar, _promptSecret, _configFileExists, _createDefaultConfig), read at call time.
• Masked input: Node raw mode vs Python cbreak: Ctrl-Z is treated as EOF (Python raises SIGTSTP); on Windows raw mode replaces msvcrt. The top-level SIGINT handler in abx.ts prints a newline when Ctrl-C hits a visible click prompt. Real-pty tests drive a Python helper (no node-pty) and skip with a warning when python3/pty is unavailable.
• LLM defaults come from the single agent/qwen_code.ts constants (as in Python, which imports them lazily).
• Not differentially testable: truly concurrent writers (outcome is a race in Python too; sequential writers are covered) and OS keychains (Python config_cmd never uses one; ABX_NO_KEYCHAIN variants are covered).
• test_create_backend / test_create_nl mock config_cmd with async stubs; they belong to the sandbox builder.
• Exports for other builders: _effectiveValue, readEnvVar, writeEnvVar, removeEnvVar, _removeTomlKey, _businessDefault, _promptSecret, resolveGithubToken, loadConfigDict, _configFileExists, _createDefaultConfig, _maskValue, _maskSupported, _feedMasked, _readMaskedLine.

commands/mcp (builder mcp-cmd)

parity/diff/mcp_cmds.mjs (needs ORACLE_VENV; --only <substr>, --verbose) compares the oracle and the port in isolated HOME / cwd / run dirs against a stub platform server: 216 cases (install per target and edge inputs incl. unicode / floats / invalid UTF-8, status text+JSON, stop, start validation, deploy option matrix and generated artifact, STDIO over a stdin script, SIGTERM/SIGINT, second start refused, HTTP foreground with probes, port in use, unresolvable host, --background start/status/stop, background child dying early). All identical after normalising temp dirs, pids, ports, tokens, the launcher in IDE configs and the items below.

• Launcher. Python writes sys.executable -m agent_sandbox.cli.main style launchers; the port self-launches (process.execPath + this CLI's entry). install therefore records a different command/args prefix (the final args are still mcp start); the --background child is the same CLI re-run with mcp start --http ....
• HTTP server. uvicorn.run is replaced by _serveUvicorn (node:http): same banner / lifecycle lines on stderr, access lines on stdout written when the response starts, exit status 3 plus ERROR: [Errno 98] error while attempting to bind ... on a bind failure, graceful shutdown on the first SIGINT/SIGTERM, immediate exit on the second. After SIGTERM the process re-raises the signal (as uvicorn does), so the pid file stays behind exactly like the original; SIGINT removes it. Bind failures other than EADDRINUSE/EACCES/EADDRNOTAVAIL/ENOTFOUND/EAI_AGAIN use the generic OSError text.
• Deploy artifact. runtime: python3.10, handler app.app and requirements.txt (agent-sandbox[mcp], uvicorn>=0.29) are unchanged on purpose: the FC function runs the Python SDK from PyPI, not the Node CLI.
• Huge --memory. INT yields an exact bigint beyond 2**53; the generated config.yaml is not differential-tested for such values (not reachable with real FC memory sizes).
• Background readiness race. When the child dies on a bind error right after claiming the pid file, whether the 0.1 s poll reports "running in the background" or "exited before it was ready" is a race in Python as well; the harness compares the outcome class and the child's log for that case.
• Findings for other owners (resolved in agent/mcp.ts / agent/tools.ts by agent-B, see that section). (1) agent/mcp.ts STDIO: when several lines arrive in one chunk, Python answers a malformed line (Parse error) before the tasks of the preceding valid lines, the Node reader answers it after them; clients that wait for answers do not see it. (2) agent/tools.ts logs Tool run_code failed: unavailable where the original logs Tool run_code failed: [E2000] unavailable (exception str() vs bare message), plus traceback frames that are inherently different; the harness elides that stderr tail.

commands/template, _adopt, deploy (builder template-cmd)

parity/diff/template_cmds.mjs (needs ORACLE_VENV; --only <substr>, --verbose) compares the oracle and the port in an isolated HOME / work dir against a stub server (platform /templates, /index.yaml, GitHub tarballs via --registry-url) and a fake docker on PATH: 241 cases (help, list/info/delete incl. HTTP errors, create/push/build/deploy/top-level deploy option matrix, search/install from index / local / GitHub tarball / bare name, init cases / --from / natural language, adopt offline paths). Compared: exit code, stdout, stderr, stub request log, docker invocations, resulting work-dir tree. All identical after normalising temp names/ports/timings and the items below (cases with a known marker).

• YAML parser messages. Resolved: the parser is a port of PyYAML's, so detail lines (context / problem / snippet, or the file name without snippet for open() streams) are identical (search bad yaml, install invalid yaml).
• SDK wheel injection. Python builds the wheel from the local source tree (pip wheel); the port downloads the matching agent-sandbox-server wheel from PyPI. When neither is available both warn and continue; the warning texts differ (normalised in the harness). The pip hint targets agent-sandbox-server (split).
• Alibaba SDK errors. ListTeams / ACR failures surface the text of the Node Tea SDK (Error: Code Code: code: 404 ...) instead of the Python SDK's; the [E5000] prefix, suggestion and exit code are identical. The requests/urllib3 DEBUG lines of the Python -v output have no Node counterpart.
• HTTP user agent. abx-node-httpx/<version> instead of python-httpx/<version> (framework-wide).
• questionary -> @inquirer/prompts. The arrow-key case picker of template init uses select; the numbered fallback and the non-TTY behaviour are unchanged. Tests either vi.mock("@inquirer/prompts") or force templateSeams._tryArrowCasePicker to return null.
• difflib.unified_diff. _adopt.ts builds the diff with the diff package (structuredPatch); hunk grouping can differ from CPython on inputs with several equally good alignments.
• Sandbox.deploy / run_sync. Not ported (no Python-only bridge); the natural-language template init/create paths call sandbox._generateLocalTemplate directly.
• _StepReporter. The use_activity_line branch writes through the same OutputManager activity line as Python; the repaint ticker is a setInterval with unref() instead of a daemon thread (templateSeams._STEP_TICK_SECONDS).
• assert name in template init --from. Raised as a bare Error("") (same Unexpected error: output, unreachable in practice).
• Doc-consistency tests (test_agent_guide, test_byo_agent_docs, test_skill_installation_docs) are ported against the CLI repo's own docs / SKILL.md: shared-token lists follow agent-sandbox/agent-sandbox (npm install commands instead of pip install).
• Not covered by the differential harness. Paths that need a real TTY (confirmation prompts, the arrow picker, the live activity line), a real model run (template init --adopt after the dry run, natural-language generation) and real docker/ACR/Aliyun; these are covered by the ported unit tests with stubs (test_template_branches.test.ts adds the prompt / legacy-pipeline / response-shape branches).

Unowned ledger entries: local install, evidence snapshots, template guide, integration (builder "unowned")

• test_local_install.py (22): ported to tests/test_templates/test_local_install.test.ts (+ conftest.ts). The offline guard is a tripwire on dns.lookup / net.connect / net.createConnection (Python patches socket); template.ts needed no change.
• Evidence snapshots (tests/test_cli_evidence/, 100 cases, byte for byte against the unchanged golden files). The case registry and the mocks live in evidence_cases.ts (including the fixed API key / fixed IDE-config map of the mcp cases), so the old test_mcp_evidence.test.ts was deleted as subsumed. Comparison uses stdout only (the interleaved output would hide a stdout/stderr split regression). golden/ holds 103 files for 100 registry cases: three are stale leftovers from the Python repository and are not asserted. Refresh with ABX_UPDATE_EVIDENCE=1; docs in tests/test_cli_evidence/README.md.
• scripts/capture-cli-evidence.mjs replaces scripts/capture_cli_evidence.py. It runs the same registry inside vitest (spies cannot cross a process boundary): --live (needs E2B_API_KEY), --command PREFIX, --out DIR. When the output directory already has a hand-written README.md (as .agents/evidence/ does) it writes README.generated.md; the stale generator reference in .agents/evidence/README.md (repo-layout audit) is still to be fixed by the docs owner.
• test_template_guide.py cross-checks are no longer skipped: they read python-sdk/server-sdk/src when the monorepo is checked out next to the CLI and skip with a clear message otherwise. They exposed one real drift: the server SDK has a new opt-in capability group AGENTS that docs/.../template-guide does not describe, so test_describes_every_capability_group exempts AGENTS (marked in the test). Remove the exemption when the guide is updated (cli-followups §5); the guide itself was not changed.
• Integration policy (tests/integration/README.md). The files Python marks @pytest.mark.integration (test_cli_e2e, test_nl_template_init_e2e) are excluded from npm test (explicit list in the test script) and run with npm run test:integration; the unmarked ones (progress_activity, adopt_deploy, credential_priority, workflow CLICompleteness) run in CI in Python and therefore stay in the default run. None needs credentials or a pty: everything is offline (CliRunner with stubbed seams, or a real abx process with a temp HOME), so no node-pty / script fallback was necessary. parity:coverage runs the integration directory too.
• Moved to python-sdk. 18 test_workflow_e2e.py entries (TestTemplateDefinition, TestCapabilityResolution, TestImageChainBuilder, TestDeclarativeServerBridge) test the Python SDK; they exist in python-sdk/client-sdk/tests/integration/test_workflow_e2e.py and are listed in parity/moved-to-python-sdk.txt. scripts/parity-coverage.mjs reports them as "moved" and verifies class + function in the monorepo when it is present (it fails if one disappeared). test_credential_priority_e2e.py also asserts resolve_llm_env (SDK function, covered by client-sdk/tests/test_api/test_deploy.py); that assertion was intentionally not ported.
• Seam substitutions in the integration ports: Sandbox.create / connect spies replace run_sync; qwen_code.seams.runQwenCodeHeadless / codegen.seams.runQwenCodeHeadless replace the run_qwen_code_headless patches; Python's module sys fakes are the outputSeams.sys, sandboxSeams.stdinIsatty and codingAgentSeams.stdinIsatty seams.

Follow-up fixes (JSON / YAML / int parsing) and what remains

• Server JSON (httpx.Response.json(), utils/_pyjson.ts): parsed like json.loads(bytes) with CPython's error texts; whole-number floats are PyFloat (2.0 stays 2.0), ints beyond 2**53 are bigint, undecodable bytes raise UnicodeDecodeError (a ValueError, so Sandbox._callServerCommand still maps it to the "non-JSON response" path). The Connect codec (json_decode) follows orjson's number model (exact up to 64 bits, floats beyond). Integer-like object keys keep their insertion order (see the MCP section above for the paths that do not).
• YAML: see src/utils/yaml_io.ts (the yaml package, YAML 1.1 rules, unknown tags and control characters rejected).
• rglob: Path.rglob("template.yaml") (capability resolution) and the upload walker share utils/_pyos.ts (scandirEntries/rglobName/rglobAll), iterating in raw readdir order like os.scandir.
• int() parsing (utils/_py.ts::parseIntStrict): Unicode decimal digits (CPython 3.11 / Unicode 14 table), single underscores, Unicode whitespace (not U+001C..U+001F) and the 4300-digit limit follow CPython. Results beyond +-(253 - 1) are exact bigints (smaller ones stay number), and INT/IntRange convert to the same. Huge values are reachable (create -t 99999999999999999999 -> the SDK's pydantic range error shows the exact input_value; exec -t -> float(timeout); process signal --signal -> orjson Integer exceeds 64-bit range); each is differential-tested (sandbox_cmds / sandbox_subcmds / template_cmds "253" / "20 digits" / "huge" cases). float(bigint) past the double range raises OverflowError: int too large to convert to float, and transport/_httpx.ts clamps timers to 2**31-1 ms (Node's setTimeout would otherwise fire after 1 ms; Python waits effectively forever for such timeouts).

Adversarial review fixes: agent / template (builder agent-template-fix)

Review: parity/review/agent-template.md (12 BUG, 4 GAP-UNJUSTIFIED). Every item is fixed except the two noted below; the ADV tests became tests/test_templates/adv_*.test.ts, tests/test_agent/adv_*.test.ts, tests/test_utils/adv_pyos_parity.test.ts.

• MCP HTTP request-head limit (AT-03), approximate. uvicorn+h11 accepts a request head of any size that arrives in a single recv and answers 400 Invalid HTTP request received. otherwise (h11's 16 KiB incomplete-event cap), so the real limit depends on kernel/loopback chunking: on loopback the oracle accepted heads up to 127 589 bytes. createUvicornLikeServer sets maxHeaderSize to that value and answers oversized heads with the same 400 body. Heads between ~16 KiB and the limit are accepted by both on loopback; a slow or fragmenting client can be rejected by Python and accepted by the port.
• STDIO EOF (AT-11). The EOF path waits until the tasks of the last batch are done or provably blocked (a new socket / timer / process resource, or a tools/call behind a running one), capped at 2 s. asyncio cancels exactly the tasks suspended on I/O, so a one-shot printf request | abx mcp start is always answered now (6/6, was 0/6); a task parked on something that is neither I/O nor finishing is abandoned after the 2 s cap. tests/test_agent/adv_mcp_stdio_eof.test.ts is the deterministic stress test.
• Negative per-call timeout (AT-12). Fixed in src/transport: httpx.Timeout(<= 0) expires as ConnectTimeout before any bytes, and envd streaming does not rewrite that into ConnectionError_. The MCP tool result is {"error": "ConnectTimeout"}.
• --alias ../x. Install keeps Path / alias semantics: Cached <home>/.abx/templates/../x and the copy lands at <home>/.abx/x, exactly like the oracle (its path handling is itself unsafe; fixing it needs a decision shared with the Python project).
• shutil.copytree. template install and template init --from use pyCopytree (entries snapshotted before the destination is created, symlinks followed, per-entry failures collected into shutil.Error). shutil.copystat is limited to mode and atime/mtime (no xattrs / file flags); atime/mtime are copied with microsecond precision.
• Tar directory modes (AT-04). qwen standalone extraction creates directories with the default mkdir mode (umask applied), like extractall(filter="data") (mode None).
• UnicodeDecodeError texts. readTextPy reports 'utf-8' codec can't decode byte 0xNN in position N: ...; the .env reader (utils/_dotenv.ts) and the Connect codec still use the short 'utf-8' codec can't decode bytes (other areas).
• httpx.Response.text keeps a UTF-8 BOM (httpx decodes with utf-8, not utf-8-sig), so the template-index cache stores the served bytes verbatim; .dockerignore is read without stripping a BOM (first pattern then does not match, as in Python).