feat(sdk): Phase 2b — filesystem clients, watch, waitForPort, waitForLog (CORE-58)

[AprilNEA]

Summary

CORE-58 Phase 2b — the final SDK surface gap. Client support in both SDKs for everything #582 implemented daemon-side, following the Phase 2a (#583) patterns throughout.

Filesystem path verbs — files.stat/list/mkdir/remove/move

• Wire FileStat → idiomatic DTOs: TS numbers/Date, Python frozen dataclass with int/datetime; kinds map to "file" | "directory" | "symlink" | "other" with "unknown" future-proofing.
• Python paths accept str | PurePosixPath across all files methods (a host Path qualifies on POSIX).
• mkdir is always mkdir -p — the daemon exposes no non-recursive variant (filesystem.proto), so no parents knob is offered; mode is (0 = daemon default 0755, mirroring the write-mode convention).
• Errors ride the registry, verified against feat(sandbox): implement the filesystem verbs and process-plane queries (CORE-62) #582's daemon shapes: a missing path is FileNotFoundError with path in context (ErrorInfo FILE_NOT_FOUND); a non-recursive remove of a non-empty directory keeps the FAILED_PRECONDITION routing (SandboxStateError).

files.watch(path, {recursive}) — WatchDir streaming

• Typed FsEvent (created/modified/removed/renamed); renames arrive paired in one event (path = old, renamedTo/renamed_to = new).
• Keepalives filtered; the daemon's clean SandboxFileWatchEnd (sandbox stop) terminates the iterator normally.
• Mid-stream transport drop → ConnectionLostError, no auto-reconnect — watch events cannot be replayed (same rationale as events()).
• inotify overflow surfaces as the daemon's documented re-list-and-re-watch error with its own class — never retried, never reshaped into a connection error.
• Surfaces: TS async iterable; Python AsyncFileWatch/FileWatch pair (context-manager form for early exit; sync reads genuinely block, like EventStream).

commands.list() — ListExecutions

• CommandInfo summaries (id/tty/state/timestamps, exit-as-data with the Phase 2a 128 + signal convention; error for executions that ended without an observed exit). The rediscovery path: pick an id, commands.get(id) for a live handle.

ports.waitForPort(port, {timeoutMs}) / ports.wait_for_port(port, timeout=)

• New ports namespace over the WaitForPort RPC (guest listen-table watch; no client polling). 0 on the wire = daemon default 30 s; the daemon's 600 s cap is mirrored client-side for the grace deadline (effective + 5 s, exempt from the per-RPC knob like waitForExit).
• A deadline expiry — the daemon's DEADLINE_EXCEEDED or the client grace bound — surfaces as a TimeoutError naming the waitForPort knob, mirroring connect()'s discipline (never RequestTimeoutError's wrong suggestion).

handle.waitForLog(pattern, {timeoutMs}) / wait_for_log(pattern, timeout=)

• Purely SDK-side per the design doc — no new RPC. The offset-addressed output replays from offset 0 through the Phase 2a resumable attach loop, so a line printed before the call matches immediately and transport drops resume seamlessly from the delivered offsets.
• Line-oriented matching (substring or regex per complete line; the unterminated tail is tested at exit) with per-channel buffers — chunk-split lines and UTF-8 boundaries are safe, memory is bounded by the longest line.
• Exit without a match is a typed non-timeout ArcBoxError. Deadline → TimeoutError naming the knob. TS aborts the attach with an AbortSignal (exact); Python observes the deadline per stream frame (keepalive cadence bounds the lag — the honest semantics for a genuinely-blocking sync tree, kept identical in the async twin), and an exhausted re-attach budget past the deadline resolves to the timeout, not stream death.

Tests

• Mock-transport unit tests for every verb, the watch stream (typed mapping, rename pairing, clean end, overflow, drop-after-frames vs dial-failure), waitForPort (wire fields, deadline reshaping), waitForLog (chunk-split match, regex, replay, resume-across-drop with offset assertion, timeout, exit-without-match, daemon-typed error passthrough). TS 94 passing / Py 139 passing, no daemon needed.
• Gated e2e suites extended: mkdir→write→stat→list→move→remove roundtrip (with both error guards), a recursive watch observing a marker write, waitForPort against a background nc -l (plus the no-listener timeout), commands.list rediscovery, and waitForLog catching a delayed echo while the command keeps running.

Live e2e (VZ, isolated daemon, hardware)

• cargo test -p arcbox-e2e --test sdk_ts -- --ignored: green — vitest 4/4 (incl. the new 2b test), 12.7 s.
• cargo test -p arcbox-e2e --test sdk_py -- --ignored: green — pytest 6/6 (incl. test_sync_phase_2b_surface + test_async_watch_observes_a_write), 13.0 s.

Gates (exit 0 on every commit)

• TS: lint / format:check / test / typecheck / build
• Py: ruff check / ruff format --check / pyright / gen_sync.py --check / pytest

Both README feature tables updated; Template statics remain the only deferral.

[linear-code]

CORE-58

[pullfrog]

Your Claude subscription has hit its usage limit. It resets at 12am (UTC). Re-trigger Pullfrog after the reset, or add an ANTHROPIC_API_KEY repo secret — Pullfrog routes around an exhausted subscription automatically when one is present.

Add repo secret → · Model settings → · Setup docs → · Ask in Discord →

  ^{｜ Rerun failed job ➔ ｜ View workflow run ｜ via Pullfrog ｜ Using Claude Opus ｜ 𝕏}

[pullfrog]

Your Claude subscription has hit its usage limit. It resets at 12am (UTC). Re-trigger Pullfrog after the reset, or add an ANTHROPIC_API_KEY repo secret — Pullfrog routes around an exhausted subscription automatically when one is present.

Add repo secret → · Model settings → · Setup docs → · Ask in Discord →

  ^{｜ Rerun failed job ➔ ｜ View workflow run ｜ via Pullfrog ｜ Using Claude Opus ｜ 𝕏}

[greptile-apps]

Greptile Summary

The PR completes the Phase 2b SDK surface in both Python and TypeScript.

• Adds filesystem metadata and mutation operations, typed filesystem watches, command discovery, port readiness waits, and line-oriented log waits.
• Exposes corresponding public types and namespaces and adds unit and end-to-end coverage across both SDKs.
• The follow-up changes validate nonsensical port-wait budgets before transport while retaining documented whole-second rounding.

Confidence Score: 5/5

The PR appears safe to merge.

No blocking failure remains; the previously reported explicit-zero timeout collision is prevented at each SDK boundary before any request is sent, while fractional rounding is documented intentional behavior.

Important Files Changed

Filename	Overview
sdk/python/src/arcbox/_async/ports.py	Adds asynchronous port readiness waiting with boundary validation, daemon-budget clamping, and timeout-error normalization; the prior explicit-zero issue is fixed.
sdk/python/src/arcbox/_sync/ports.py	Provides the generated synchronous equivalent of port readiness waiting and its corrected timeout validation.
sdk/typescript/src/ports.ts	Adds the TypeScript ports namespace with pre-transport timeout validation and documented whole-second wire conversion.
sdk/python/src/arcbox/_async/files.py	Adds typed filesystem verbs and non-replayable asynchronous filesystem watch handling.
sdk/typescript/src/files.ts	Adds TypeScript filesystem metadata, mutation, and watch surfaces.
sdk/python/src/arcbox/_async/commands.py	Adds command listing and resumable, line-oriented wait-for-log support.
sdk/typescript/src/commands.ts	Adds command discovery and wait-for-log behavior to the TypeScript SDK.
sdk/python/tests/test_list_port.py	Verifies invalid port-wait budgets are rejected without issuing transport requests.
sdk/typescript/test/list-port.test.ts	Covers port-wait request mapping, timeout handling, and corrected invalid-budget rejection.

_{Reviews (7): Last reviewed commit: "test(sdk): pin the inf-disables-the-boun..." | Re-trigger Greptile}

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 00e37ffa0d

ℹ️ 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".

[pullfrog]

ℹ️ Three cross-SDK parity nits, all non-blocking. No defects found.

Scope note. The push delta since the last synchronize (00e37ff..35f34a9) is lint-only — a noop import, a loop-condition reorder, and an extracted watched binding in sdk/typescript/test/e2e.test.ts. But this PR has never had a Pullfrog review (only greptile-apps and chatgpt-codex-connector), so I read the full diff end-to-end rather than just the delta: 10 commits, 28 files, +3259/-58.

The 2b surface lands cleanly and the two SDKs track each other closely. Worth calling out as verified rather than assumed:

• Both scanners handle a multi-byte UTF-8 sequence split across chunk boundaries — TS via a per-channel TextDecoder with { stream: true }, Python by buffering bytes per channel and decoding only complete lines. TS also resets pattern.lastIndex, so a global/sticky regex doesn't skip lines.
• Open proto3 enums have "unknown" fallbacks on both FileKind and FsEventKind, with tests feeding 99 through each.
• scripts/gen_sync.py picked up both new classes (AsyncFileWatch, AsyncPorts), so the generated sync tree isn't silently stale.
• The tests assert exact values (stat.size == 8, stat.mode == 0o644, (137, "SIGKILL"), full context dicts) rather than shape — real coverage.

The three items below are all places where the two SDKs answer the same wire situation differently. None blocks the merge; the deadline one (first comment) is the only one I'd want a decision on rather than a shrug.

  ^{｜ Fix all ➔ ｜ Fix 👍s ➔ ｜ View workflow run ｜ Using Claude Opus ｜ 𝕏}

[pullfrog]

Reviewed changes

• Verified all three round-1 parity findings against the code rather than against the reply text: the wait_for_log deadline now bounds a silent stream, files.watch classifies a zero-frame drop the way TS does, and waitForPort rejects nonsensical budgets in both SDKs.

• Traced the new attach read-gap plumbing from wait_for_log through _attach_events and ServerStream into httpx.Timeout, checking which exception types survive each hop.

• Checked the daemon and guest sources against the docstrings this round added — the WatchDir immediate keepalive and the five-minute exited-execution retention are both real.

• Confirmed the round-2 tests fail without their fixes, including the one that reads back the recorded per-request read timeout.

ℹ️ One follow-on from the round-2 fix, inline. Non-blocking — the three round-1 threads are genuinely closed.

Scope note. incrementalDiffPath covered 2bc44cb..2302fb9 only, which skips 2bc44cba even though the prior Pullfrog review sat at 35f34a92. I reviewed the real delta, 35f34a92..2302fb92 — 15 files, +296/-69, commits 2bc44cba ("review round 1") and 2302fb92 ("review round 2").

Both rounds went further than the review asked, and the extra reach is the part worth calling out:

• Fix 2 was applied to _stream_events as well as _stream_watch. _stream_events is a Phase 2a surface nobody flagged, and it carried the same headers-based flag — so the fix closed a divergence that was never reported.

• The commands.list() retention docstring is now specific ("five minutes guest-side"), and it matches EXITED_RETENTION = Duration::from_secs(5 * 60) in virt/arcbox-vm/src/sandbox/execution.rs:25. The delivered-on-first-frame reasoning is likewise backed by the guest: write_watch_keepalive runs before the event loop (guest/arcbox-agent/src/sandbox/files.rs:225,294), so a WatchDir stream really does confirm itself with an immediate frame.

• test_the_attach_read_gap_is_bounded_by_the_remaining_budget asserts on request.extensions["timeout"]["read"] — it pins the plumbing at the transport boundary rather than at the SDK's own abstraction, which is what makes it able to fail.

One asymmetry I checked and am deliberately not raising as a defect: Events has no immediate keepalive (with_keepalive only fires after 15 s idle, app/arcbox-api/src/connect/mod.rs), so an established _stream_events subscription that drops inside that window is now reported as ConnectionFailedError — "daemon unreachable" — even though the HTTP 200 proves it was reached. Blast radius is small since ConnectionLostError subclasses ConnectionFailedError, and this is the direction the round-1 review recommended; flagging it now would just be flip-flopping. Recording it so it reads as a known trade-off rather than an oversight.

  ^{｜ Fix all ➔ ｜ Fix 👍s ➔ ｜ View workflow run ｜ Using Claude Opus ｜ 𝕏}

[pullfrog]

Reviewed changes

The delta since the round-2 review at 2302fb92 — two commits, 7 files, the waitForPort docstring and the wait_for_log NaN/infinity fix.

• 896a68bb (docs only) adds the fractional-budget sentence to waitForPort/wait_for_port in both SDKs. Checked it against the code rather than taking it at face value: math.ceil(timeout) and Math.ceil(timeoutMs / 1000) do round up, so a sub-second budget can never land on the reserved 0 — the sentence is accurate.

• d95e3f9d fixes the round-2 finding. NaN is rejected inside wrap_errors, so the raised InvalidArgumentError carries the commands.wait_for_log operation stamp the new test asserts on; math.inf maps to deadline = None, which is the disabled bound rather than a bound of infinity. Both the async source and the generated sync twin carry the fix and the two new imports (math, InvalidArgumentError), so gen_sync was re-run.

Checked rather than assumed:

• I measured the socket.settimeout overflow boundary on this box instead of reasoning about it: it raises OverflowError: timestamp out of range for platform time_t above ~9.2e9 seconds, not the OSError/EINVAL one might expect. That leaves Python without TS's 2**31 - 1 ceiling on a finite budget — but the gap only opens at ~292 years, so a guard for it would be bloat. Recording it, not raising it.

• All four prior Pullfrog threads were re-read against the current code and are genuinely closed; the author had already resolved each one, so there was no reply work this round.

• I am deliberately not re-raising the wait_for_log timeout <= 0 / -inf divergence from TS. The author answered it explicitly on the resolved _async/ports.py:46 thread — wait_for_log has no wire sentinel to collide with, so a ≤0 budget there means "already expired", consistent with wait_for_exit's deadline arithmetic. That is a settled design decision, and the -inf → TimeoutError assertion codifies it on purpose.

One nitpick inline on the new test. Non-blocking — the fix itself is correct and complete for what it set out to do.

ℹ️ Nitpicks

See the inline comment on sdk/python/tests/test_wait_for_log.py.

  ^{｜ Fix all ➔ ｜ Fix 👍s ➔ ｜ View workflow run ｜ Using Claude Opus ｜ 𝕏}

[pullfrog]

✅ No new issues found.

Reviewed changes

The delta since the round-3 review at d95e3f9d is a single test-only commit — 3a6bec41, one file, +30/-14, all in sdk/python/tests/test_wait_for_log.py. It closes the round-3 nitpick.

• Hoisted the recorder: the previously function-nested Recorder subclass plus its module-local read_timeouts list became a module-level RecordingAttach(FlakyAttach) with a per-instance read_timeouts. Both deadline tests now share it, and test_the_attach_read_gap_is_bounded_by_the_remaining_budget reads its own instance's list rather than a list shared across three daemons — the unbounded case tightened from read_timeouts[-1] is None to the exact unbounded.read_timeouts == [None] in the process.

• Verified the new inf assertion is actually fix-sensitive, which is precisely what round 3 said the old one was not. Traced it through rather than trusting the commit message: pre-fix, timeout=float("inf") gave deadline = inf → read_timeout = max(inf - now, 0.05) == inf → httpx.Timeout(inf) → request.extensions["timeout"]["read"] == inf, so assert daemon.read_timeouts[-1] is None fails. Post-fix, timeout == math.inf maps to deadline = None, _attach is handed read_timeout=None, ServerStream passes timeout=None to httpx.Client.stream, and the extension carries None. The assertion now pins the math.inf → deadline = None branch specifically.

• assert daemon.read_timeouts == [] is a genuine addition too: it pins that the NaN rejection happens at the boundary inside wrap_errors, before any dial reaches the transport, rather than merely raising at some point during the call.

Checked rather than assumed:

• The recurring scope caveat from rounds 2 and 3 did not recur — git diff --stat d95e3f9d..3a6bec41 matches the supplied incremental diff exactly (1 file, 30 insertions, 14 deletions), so the incremental base and the prior review head agree this round. I still read the authoritative full diff end-to-end; nothing outside the delta changed disposition.

• All four prior Pullfrog threads across rounds 1–3 were re-read against the current code and are genuinely closed; the author had already resolved each, so there was no reply work this round.

• Considered and dropped one consistency nit: line 231 uses read_timeouts[-1] is None where its neighbour at line 250 uses the exact == [None]. With die_after unset FlakyAttach serves exactly one dial per handle, so the two are equivalent here — raising it would be a style preference dressed as a finding.

  ^{｜ View workflow run ｜ Using Claude Opus ｜ 𝕏}