Skip to content

Demo: surface the remote-sandbox vignettes deferred from #174 #198

Description

@pdettori

Follow-up to #174, which PR #195 closed on its acceptance criteria — all five boxes —
while deliberately leaving out that issue's "Features worth surfacing" list. This issue is
that list, reconciled against what #195 actually shipped rather than against what #174
originally asked for, because four of the eight bullets turned out to be delivered already
and filing all eight would send someone re-implementing them.

None of this is capability work. Every item below is implemented and unit-tested today
(packages/k8s-sandbox/test/{grpc-relay-transport,live-relay,persistent-exec}*.test.ts, plus
the remote-worker Go tests). What is missing is a visible demonstration — the reason
#174 wanted them in the first place, since a passing test suite does not show a skeptic
anything.

Already surfaced by demo-remote-worker.sh — do not redo

  • Inverted connectivity. Step 6 echoes the literal docker run line before running it,
    so the absence of -p is on screen rather than asserted in prose.
  • Transport swappability. Step 10's flip is this: same request, same contract,
    different machine, and the summary table puts the two verdicts side by side.
  • Presence mirror — but only half of it. See item 5 below.
  • Trust model — documented, not demonstrated. See item 6 below.

Worth doing, in rough priority order

  1. Live streaming. A long bash whose chunks arrive as produced rather than batched at
    completion. This is the vignette that most needs to be watched rather than asserted:
    the difference between streamed and buffered output is invisible in a final transcript,
    which is exactly why a test can cover it and still not demonstrate it.

  2. Abort mid-stream. Kill a runaway and show the process group dying — a backgrounded
    grandchild stops too. Demo: one-command laptop showcase — harness on kind, remote worker as a docker container #174 singled this out as "the part that is easy to get wrong," and
    it is the one item here whose correctness a viewer cannot take on faith from a green
    check, because the interesting failure mode is a survivor rather than an error.

  3. Reconnect → dedup. docker stop the worker mid-flight, restart it, watch it reattach
    and not re-run the redelivered exec. This is the vignette that most benefits from the
    host-container topology feat(deploy): one-command laptop demo — harness on kind, remote worker as a host container #195 built: docker stop / docker start is the natural gesture,
    and the in-cluster gate cannot show it nearly as legibly with a pod deletion.

  4. Dual-ended timeout. timeout_s enforced worker-side, timeout:<n> surfaced to the
    caller. Lowest drama of the four, but it is the one that documents a contract between
    two ends rather than a behaviour of one.

Smaller

  1. The presence mirror is asserted in one direction only. Step 7 calls assert_presence,
    so the demo proves a record appears. assert_presence_gone already exists in
    lib-relay.sh:123 and is already called by the gate (relay-leaf-smoke.sh:260) — but not
    by the demo, so the demo never shows the record vanishing when the stream closes. Demo: one-command laptop showcase — harness on kind, remote worker as a docker container #174
    asked for HGETALL before and after, and the after is the half that proves registration
    is the live stream rather than a row someone wrote. One call in the cleanup path.

  2. The trust model is documented but never run. README-worker.md gives the
    docker inspect command and demo-remote-worker.sh:140 mentions it in a comment, but the
    demo does not execute it — so the one claim a viewer would most want to verify with their
    own eyes ("no LLM key, no kubeconfig") is the one thing they have to go and check by hand.
    Printing the container's env in step 6, right after the docker run line, costs one
    command and closes the gap.

Sizing and placement

These were the bulk of #174's line count as originally scoped, and each adds wall-clock and
failure surface to a demo whose current value is that it is one fast command. Worth
considering an opt-in flag (--vignettes, or separate make targets) rather than extending
the default path, so the A/B stays the thing make demo-remote-sandbox does.

Items 5 and 6 are the exception — both are one-line additions to the existing default flow
and neither can fail in a new way.

Assisted-By: Claude Code

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions