feat(relay): port the #16741 T1 seam (work drain, publication drain, release gate)

[OrcaWin]

	Files	Added	Deleted	Net
Test	4	$\color{#1a7f37}{\Huge{\mathbf{+}}}$​387	0	$\color{#1a7f37}{\Huge{\mathbf{+}}}$​387
Prod	5	$\color{#1a7f37}{\Huge{\mathbf{+}}}$​251	$\color{#cf222e}{\Huge{\mathbf{−}}}$​1	$\color{#1a7f37}{\Huge{\mathbf{+}}}$​250

ELI5

This is the first slice of porting #16741 (SSH and remote convergence) onto today's code. It's a small, inactive base that later slices build on: a work-drain contract, a publication drain, a call-queue retirement option, and the opt-in switch for live terminal transfer. Nothing uses it yet except tests.

What Changed

• Added:
  • pty-ownership-transfer-release-gate.ts, taken as-is.
  • runtime-rpc-call-queue with holdIdleSelectors and RuntimeRpcCallQueueBusyError.
  • relay-work-drain-contract.ts, adapted: T3's reset methods and T4's tunnel methods are left out until those contracts exist.
  • The relay publication and work drain.
• Promise.withResolvers is replaced, because the relay bundle targets node18.
• No wire changes and no behavior changes. The porting note is in the commit body.

Why

Design D9: port #16741 by subsystem, starting with the T1 seam that T2 and later tracks import. Live transfer (T7) stays out, per D9.2.

Linked Issue

Part of the Node runtime plan (Phase 3). Files were chosen from the #24137 manifest. Stacked on OrcaWin/node-rt-p2-integration.

Visual Proof

N/A. Nothing is wired to this code yet.

Testing

• 377 test lines are ported with the code, and they pass. pnpm tc and the quality gates pass.

• Next: the dispatcher-wiring and relay producer-drain slices are the first real consumers. They also need to decide whether pty.cancelDelivery belongs in the drain allowlist.

• I manually tested these changes locally

• Automated tests added/updated, or explained why not below

Agent skill upstream boundary

• Not applicable, or this change follows docs/reference/agent-skill-sharing-upstream-boundary.md and copies or mechanically translates no upstream skill-installer source, tests, fixtures, registry entries, path tables, comments, or documentation.

[greptile-apps]

Confidence Score: 5/5

[High risk] Adds work admission and drain gates to the relay runtime.

The PR appears safe to merge; no actionable new issue or outstanding previous finding was established.

Summary

The PR adds an inactive relay work-drain seam, publication-write tracking, a PTY transfer canary gate, and runtime RPC selector retirement.

• Follow-up changes give worktree.rm a separate long-wait queue lane and ensure selector retirement treats that lane as busy.

Diagram

%%{init: {'theme': 'neutral'}}%%
flowchart LR
  Request[Runtime RPC call] --> Queue{Method}
  Queue -->|worktree.rm| LongWait[Long-wait selector lane]
  Queue -->|other methods| Ordinary[Ordinary selector lane]
  LongWait --> Hold[Idle-selector retirement check]
  Ordinary --> Hold
  Hold -->|both idle| Held[Hold selector until released]

Loading

_{Reviews (4) · Last reviewed commit: "feat(relay): land the #16741 T1 seam (wo..."}

[pullfrog]

✅ No new issues found.

Reviewed changes

This is the T1 seam port of #16741 (64c6db20b0) onto the P2 integration branch: new, currently-unwired relay drain primitives plus their ported tests. I diffed every added file against the upstream source.

• relay-work-admission.ts — behavior identical to upstream; the only edit factors trackEntry out so run/runNotification avoid Promise.withResolvers for the Node 18 relay bundle.
• relay-work-drain-contract.ts — upstream allowlists minus the T3 owner-reset and T4 network-tunnel methods, as the port note says. Every kept literal matches a real registered method on this branch.
• runtime-rpc-call-queue.ts — adds RuntimeRpcCallQueueBusyError, heldSelectors, holdIdleSelectors, and the top-of-enqueue held check; identical to upstream. Inert while nothing holds a selector, so the live queue is unchanged.
• transport-publication-drain.ts — logic identical to upstream, same withResolvers removal.
• pty-ownership-transfer-release-gate.ts — taken as-is.
• Tests — 34 new tests pass; the existing queue, transport-error-agreement, and call-routing tests still pass; pnpm run check:code-quality:changed is clean.

ℹ️ The new busy code has no downstream classification yet

runtime_rpc_queue_busy is a new wire-visible structured error code, but it is not a member of RECOVERABLE_CODES and runtimeEnvironmentCallFailure only passes through RemoteRuntimeClientError / RuntimeRpcCallQueueOverloadError. Nothing is wired in this PR, so it cannot fire yet — flagging it as a gap for the dispatcher-wiring slice rather than a defect here.

Technical details

# Busy-code classification is a follow-up for the wiring slice

## Affected sites
- `src/shared/remote-runtime-client-error-classification.ts:8` — `RECOVERABLE_CODES` does not include `runtime_rpc_queue_busy`.
- `src/main/ipc/runtime-environment-connectivity-handlers.ts:205` — `runtimeEnvironmentCallFailure` returns `null` for anything that is neither `RemoteRuntimeClientError` nor `RuntimeRpcCallQueueOverloadError`, so a `RuntimeRpcCallQueueBusyError` from `enqueue`/`holdIdleSelectors` is not formatted as a structured `RuntimeRpcFailure`.

## Required outcome
- When `holdIdleSelectors` is wired into the runtime call path, decide whether busy rejections are retryable on the client (add to `RECOVERABLE_CODES` or a distinct handler) or should surface as a hard failure, and cover it in `remote-runtime-transport-error-agreement.test.ts`.

## Open questions for the human
- Should `runtime_rpc_queue_busy` be treated like `runtime_rpc_queue_overloaded` (retry) or as a permanent "routing is changing" signal?

  ^{｜ View workflow run ｜ Using DeepSeek Flash (free via Pullfrog for OSS) ｜ 𝕏}

[pullfrog]

✅ No new issues found.

Reviewed changes

Since the prior pullfrog review (215021d, ✅ no issues), one commit landed — a rebuilt c0395a8b — and its delta is confined to runtime-rpc-call-queue.ts and its retirement test.

• Made holdIdleSelectors count a selector's long-wait lane as busy, so a hold cannot be acquired while a worktree.rm call is still in flight.
• Extracted the ${selector}\0long-wait key into a shared longWaitQueueKey helper, now used by both enqueue and the busy check.
• Added a retirement test proving a selector whose only in-flight call is in the long-wait lane is refused, and becomes holdable once it settles.

This is a correct branch-specific adaptation: upstream 64c6db20b0 has no long-wait lane and checks only the plain selector key, but this base routes worktree.rm through a ${selector}\0long-wait queue, so the earlier check could acquire a hold while a long-wait call was active. The busy check remains synchronous and atomic, the new test fails without the fix, and the queue/retirement suites pass (14 tests).

  ^{｜ View workflow run ｜ Using DeepSeek Flash (free via Pullfrog for OSS) ｜ 𝕏}