Skip to content
Skills Library
Programming · Testing

remote-host-testing

/remote-host-testing

Test kolu's remote-host features (multi-host / padi-remote) in a real browser against a real remote box — the ONLY full end-to-end harness for this surface (real ssh provision, no mock). Covers the isolated nix-run invocation (or just dev, which bakes the same agent source), ssh- provisioning a real remote box without touching production or another user's box, the chrome-devtools drive sequence for host-switch / split / code-browser / per-host-canvas, PID-exact teardown, and the reproduce- first rule for any bug the feature surfaces. Triggers on "test remote hosts", "test multi-host", "test pa

Repository
kolu ↗
Licence
AGPL-3.0
Last repository change
23.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
0
URLs in SKILL.md
1
Deprecation

No signals detected. Repository changed on 23.10.2026, without references to retired models or APIs.

Licence

AGPL-3.0, copyleft: przeróbki udostępniane innym muszą mieć tę samą licencję.

What it does and when to use it

Test kolu's remote-host features (multi-host / padi-remote) in a real browser against a real remote box — the ONLY full end-to-end harness for this surface (real ssh provision, no mock). Covers the isolated nix-run invocation (or just dev, which bakes the same agent source), ssh- provisioning a real remote box without touching production or another user's box, the chrome-devtools drive sequence for host-switch / split / code-browser / per-host-canvas, PID-exact teardown, and the reproduce- first rule for any bug the feature surfaces. Triggers on "test remote hosts", "test multi-host", "test pa

Triggers from the description

test remote hoststest multi-host
Original author description

Test kolu's remote-host features (multi-host / padi-remote) in a real browser against a real remote box — the ONLY full end-to-end harness for this surface (real ssh provision, no mock). Covers the isolated nix-run invocation (or just dev, which bakes the same agent source), ssh- provisioning a real remote box without touching production or another user's box, the chrome-devtools drive sequence for host-switch / split / code-browser / per-host-canvas, PID-exact teardown, and the reproduce- first rule for any bug the feature surfaces. Triggers on "test remote hosts", "test multi-host", "test pa

How it works

  1. 0. Ask first — before touching anything remote
  2. 1. Isolation invocation — prefer nix-run; just dev is also agent-source-complete
  3. 2. The remote leg — provisioning the expendable box
  4. 3. Browser drive — instrument, act, then screenshot
  5. 4. Teardown-reap — kill your exact PID, nothing else
  6. 5. Reproduce-first — a passing unit test is not proof
  7. Acceptance (verify before declaring this testing pass done)
Original SKILL.md headings · 193 lines, 1,445 words
SKILL.md preview
---
name: remote-host-testing
description: >-
  Test kolu's remote-host features (multi-host / padi-remote) in a real
  browser against a real remote box — the ONLY full end-to-end harness for
  this surface (real ssh provision, no mock). Covers the isolated nix-run
  invocation (or just dev, which bakes the same agent source), ssh-
  provisioning a real remote box without touching production or another
  user's box, the chrome-devtools drive sequence for host-switch / split /
  code-browser / per-host-canvas, PID-exact teardown, and the reproduce-
  first rule for any bug the feature surfaces. Triggers on "test remote
  hosts", "test multi-host", "test padi-remote", "verify the host switch",
  "browser-test a remote host change", or before claiming a remote-host fix
  works.
---

# remote-host-testing — real browser, real remote box, isolated from production

Kolu's multi-host / remote-padi surface can **only** be exercised end-to-end
against a real ssh-reachable box: it's a real remote-provisioning path (nix
copies the padi closure over ssh), and no mock stands in for it. This skill is
the harness — nix-run isolation, the remote leg, the browser-drive checklist,
teardown, and the rule that a reported bug must reproduce here before you
diagnose it.

## 0. Ask first — before touching anything remote

**Before provisioning or connecting to any remote box**, use `AskUserQuestion`
to settle three things. Never guess or reuse a box name from a prior session,
a commit message, or this skill's own examples — a box is chosen at runtime,
never hardcoded:

1. **Which remote host(s) to test against** (the ssh destination(s) kolu will
   bind, e.g. `user@host` or an ssh-config alias).
2. **Which one is EXPENDABLE** — its padi/kaval daemons are yours to kill and
   replace freely during this run.
3. **Which boxes are PRODUCTION / UNTOUCHABLE** — never connect, provision,
   or run anything against these, even read-only, unless the user names them
   as the target in (1).

Only proceed to §1 once you have an explicit answer. Treat silence or "any
box" as **not** an answer — a specific host must be named.

## 1. Isolation invocation — prefer nix-run; just dev is also agent-source-complete

Both the packaged wrapper and `just dev` / `just dev-auto` bake
`SURFACE_AGENT_FLAKE_REF` (the latter by sourcing `.#agent-flake-env` before
the dev fork), so either path can resolve and provision a remote padi. Prefer
the **nix-built binary** for this harness: it is production-shaped and pairs
with the isolation env below. Use `just dev-auto` (see the **dev-server**
skill) when you need HMR against a remote host — still apply the same
state-dir / port isolation discipline. Both paths bake the **git-tracked** tree,
so an uncommitted edit to a tracked file does reach the provisioned padi, but a
brand-new file must be `git add`ed first, and the bake resolves once at start —
restart the dev server to pick up an agent-tree edit.

```sh
nix build .#default
```

Then launch the built binary, isolated from any locally-running production
kolu:

```sh
port=$(nix shell nixpkgs#python3 --command python3 -c \
  'import socket; s=socket.socket(); s.bind(("",0)); print(s.getsockname()[1]); s.close()')
KOLU_STATE_DIR=$(mktemp -d) \
KOLU_PADI_STATE_DIR="$KOLU_STATE_DIR/padi" \
KOLU_PADI_HOST="<remote-from-§0>" \
result/bin/kolu --host 127.0.0.1 --port "$port" &
kolu_pid=$!
```

**Why this isolates from production, mechanically:**

- `packages/server/src/state.ts` **throws** if `KOLU_STATE_DIR` is unset
  ("`KOLU_STATE_DIR` must be set to an absolute directory") — there is no
  silent fallback to `~/.config/kolu` (that was #1414; it's fixed). An
  explicit `mktemp -d` is respected, so your instance's config/session state
  never touches production's.
- `--port "$port"` (random, free) keeps the browser-facing HTTP/WS server off
  production's fixed port.
- `KOLU_PADI_STATE_DIR` retargets padi's **state-root**, and every padi/kaval
  unix-socket rendezvous path is a **digest of that state-root**
  (`padi-<digest>/`, `kaval-<digest>/` — see `packages/padi/src/stateRoot.ts`).
  A temp state-root therefore yields a digest production's default
  (`~/.local/state/padi`) never collides with — the whole padi+kaval pair is
  isolated, not just the listen port.
- **Never set `$HOME` to fake isolation.** `KOLU_STATE_DIR` /
  `KOLU_PADI_STATE_DIR` are the sanctioned levers precisely because padi's
  state-root default is deliberately `$HOME`-anchored and env-insensitive
  everywhere else (see the doc comment on `defaultPadiStateRoot`) —
  overriding `$HOME` corrupts the real user environment for every other tool
  in the shell, not just kolu.

## 2. The remote leg — provisioning the expendable box

Your isolated kolu provisions the box named in §0(1) over ssh: it nix-copies
the padi closure to the remote. This needs the ssh user in the remote nix
daemon's `trusted-users` (or the daemon's `require-sigs` off) to accept an
unsigned closure copied with `--no-check-sigs`. Verify before you start,
don't discover it mid-run:

```sh
ssh <remote-from-§0> nix show-config | grep trusted-users
```

**Fences — read these against §0's answers before every remote action:**

- Never connect to, provision, or run anything against a box the user marked
  PRODUCTION/UNTOUCHABLE, even read-only (an OOM or a stray daemon counts as
  touching it — see §4).
- The "kill/replace freely" license from §0(2) covers **your own instance's**
  padi/kaval on the expendable box only. If the box is shared, don't stomp
  another kolu's padi there unless the user said the whole box — not just
  your slice of it — is expendable.

## 3. Browser drive — instrument, act, then screenshot

Point chrome-devtools at `http://127.0.0.1:$port`. For each leg below,
**instrument before you act** so a permanent defect (state never recovers) is
distinguishable from a transient one (state recovers a beat later): inject a
`MutationObserver` via `evaluate_script` that logs xterm mount/unmount and
per-tile size/collapsed state to a `window` array, reset the baseline array,
perform the action, then read the trace **and** `take_screenshot` before
concluding anything. A screenshot alone can't tell you whether a collapse was
transient-then-recovered or latched shut — the trace can.

The remote-relevant legs to exercise:

1. **Create a terminal on the remote host** — New terminal → In current
   directory.
2. **Type into it** — fill the "Terminal input" textarea, press Enter, confirm
   output round-trips over the real ssh/padi link.
3. **Split** — Toggle split; confirm a sub-pane appears.
4. **Host-switch A→B→A** — click the host chips to leave the remote host, land
   on another, then switch back. Acceptance: the split survives, tile focus
   survives, and MRU (most-recently-used tile ordering) survives the round
   trip; the code browser re-keys to each host's own repo; the canvas shows
   each host's own tiles, not a stale mix. This exact path (a split silently
   collapsing on switch-back, its metadata arriving a beat late) is the
   canonical example of a bug this harness catches and a unit test alone
   didn't — see §5.
5. **Code browser** — `cd` into a git repo on the remote host, confirm the
   file tree populates with git-status decoration, open a file, confirm
   content renders.
6. **Per-host canvas** — confirm each host's tile layout is genuinely
   per-host state, not shared/overwritten across hosts.

## 4. Teardown-reap — kill your exact PID, nothing else

Capture the spawned PID **at launch** (`$!`, already done in §1) and reap by
that exact PID on a trap/finally — never a name/pattern match:

```sh
trap 'kill "$kolu_pid" 2>/dev/null; rm -rf "$KOLU_STATE_DIR"' EXIT
```

**Never `pkill -f <substring>`** — a substring match (`kolu`, a source path,
a socket path) matches production too; this is the exact mistake that has
killed production `kolu.service` and production's kaval daemon before (see
the `dev-server` skill's teardown section for the full incident list). If you
can't resolve your own PID, leave the process for the user/OS rather than
guess.

**Post-run zero-leak assertion** — confirm before declaring done:

- Production kolu's PID **and** uptime are unchanged from before your run
  (`systemctl --user status kolu` locally, if applicable) — an OOM counts as
  touching it even if nothing you ran named it.
- No orphaned padi/kaval process is left running on the remote box:

  ```sh
  ssh <remote> 'pgrep -fa "padi|kaval"'
  ```

  Anything still alive there after your `kill "$kolu_pid"` is a leaked
  daemon — reap it by its own exact PID, not a pattern.

## 5. Reproduce-first — a passing unit test is not proof

A bug the remote-host feature surfaces **must be reproduced in this exact
harness** (isolated nix-run kolu + a real remote box + a real browser) before
you diagnose or fix it. A green unit test around your hypothesis is not
sufficient proof on its own — it can stay green while the real thing is still
broken, because the failure mode lives in real timing (network round-trips,
metadata arriving a beat after a re-render) that a unit-level pin can't
reproduce. The split-survives-host-switch-back bug is the concrete precedent:
the root cause was a UI library (Corvu) persisting a transient collapse
because sub-terminal metadata re-arrived a beat after the tile re-rendered —
a race that only showed up driving the real switch-back in a real browser
against a real second host, never in an isolated component pin. Confirm the
fix against the SAME repro (steps in §3) before calling it done.

## Acceptance (verify before declaring this testing pass done)

- §0 was answered explicitly — no hardcoded box name, no "any box" guess.
- Launched via `nix build .#default` + `result/bin/kolu` (preferred) or
  `just dev-auto` with the same isolation env — both bake the agent source.
- `KOLU_STATE_DIR` was an explicit `mktemp -d` (never unset, never `$HOME`
  overridden).
- Every browser-drive leg in §3 was instrumented (baseline reset → act →
  trace + screenshot), not screenshot-only.
- Teardown killed the exact captured PID; the remote box has zero orphaned
  padi/kaval afterward; production (if present locally) shows the same PID
  and uptime as before.
- Any bug found was reproduced in this harness before it was called fixed.

Versions

The database has no other skills named remote-host-testing.

Database snapshot: 13.11.2026 · package version 7eea5ea1fe60 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100dev-server
    Launch the kolu dev server on two RANDOM free ports so it never collides with the running production `kolu.service`, remember the ports for the rest of the session, and tear down only the dev instance. Load before running the app locally — for evidence capture, driving a live…
  • 100browser-testing-with-devtools
    Real browser testing via Chrome DevTools MCP — DOM inspection, console analysis, network requests, performance profiling. Use when debugging anything browser-rendered. Requires the chrome-devtools MCP server.
  • 100browser-testing-with-devtools
    Real browser testing via Chrome DevTools MCP — DOM inspection, console analysis, network requests, performance profiling. Use when debugging anything browser-rendered. Requires the chrome-devtools MCP server.
  • 100browser-testing-with-devtools
    在真实浏览器中测试。构建或调试任何在浏览器中运行的内容时使用。当你需要通过 Chrome DevTools MCP 检查 DOM、捕获 console 错误、分析网络请求、分析性能,或用真实运行时数据验证视觉输出时使用。需要已配置 chrome-devtools MCP server。
  • 95browser-testing-with-devtools
    Tests in real browsers via Chrome DevTools MCP. Use when building or debugging anything that runs in a browser. Use when you need to inspect the DOM, capture console errors, analyze network requests, profile performance, or verify visual output with real runtime data. Requires…
  • 100browser-testing-with-devtools
    Tests in real browsers via Chrome DevTools MCP. Use when building or debugging anything that runs in a browser. Use when you need to inspect the DOM, capture console errors, analyze network requests, profile performance, or verify visual output with real runtime data. Requires…

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.