clauderipple 0.9.4 → 0.10.0

package/dist/router/src/reasoning.js

@@ -0,0 +1,157 @@
+// A translated reasoning model's own turn, carried through Claude Code's transcript.
+//
+// The Responses wire hands its model an opaque reasoning item — `{type:"reasoning", id, summary,
+// encrypted_content}` — and expects it back, byte for byte, in the position it came from, beside the
+// function calls of that same turn. That is not an optimisation: measured 2026-10-14 with Muse Spark
+// 1.3 at xhigh on a real tool loop, runs whose previous reasoning was not returned spent
+// 9.5k–24.5k reasoning tokens each (2,197 per step past 80k context) and one of three ran out of
+// context without ever answering, where the same loop with the items returned spent 3.2k–4.3k per
+// run (725 per step past 80k), answered in all three, and read 94% prompt cache. Dropping the reasoning is why a routed worker "thinks from
+// scratch on every tool call" and then dies. DeepSeek's own Chat API states the same rule for
+// `reasoning_content`: with `tools` present it "must be fully passed back to the API in all
+// subsequent requests", even for turns that made no tool call, and the API answers a 400 otherwise
+// (https://api-docs.deepseek.com/guides/thinking_mode/, read 2026-10-14).
+//
+// The router keeps no state of its own here. Claude Code resends the whole conversation every turn,
+// so the transcript is the storage. The carrier is a `thinking` block's `signature`, which is a
+// free-form string on the wire and is replayed with the block [measured 2026-10-14 against a fake
+// upstream: a thinking block carrying our signature comes back on the next request of a tool loop
+// with the signature byte-identical, and an *empty* thinking text is kept too — which is what a
+// Responses reasoning item with no summary looks like]. Anthropic's own signature is opaque base64
+// this router cannot forge; ours is a small envelope that names the wire, the provider, the model
+// and the vendor's own reasoning, and it is decoded and dropped by `thinking.ts` before a request
+// reaches Anthropic.
+//
+// opencodex (github.com/lidge-jun/opencodex, devlog/_fin/260711_claude_inbound/003_evidence.md
+// lines 93-118) reached the same conclusion and the same carrier — a signature on a thinking block,
+// read back out of the client's own conversation — and we rely on that as a behavioral
+// specification only; no code was copied.
+//
+// `encrypted_content` is the vendor's own sealed blob. It goes in the envelope untouched and comes
+// back untouched: re-encoding or re-signing it would be the "re-signed reasoning" mistake that cost
+// an earlier translator 12–20% cache hit (ARCHITECTURE §4, "Cache-safety decisions").
+//
+// `include:["reasoning.encrypted_content"]` is asked for on every turn where the vendor is known to
+// take it — the ChatGPT backend, as Codex asks, and a preset marked `sealedReasoning` (presets.ts),
+// as OpenCode's own client asks. A `store: false` backend that is not asked hands back nothing, so
+// waiting until a conversation already carried reasoning would never start one. For any other
+// Responses vendor it is asked for only once the conversation already carries that vendor's
+// reasoning, so a vendor never measured keeps the request it had. Measured 2026-10-14 against
+// OpenCode Go (`muse-spark-1.3-contributor`, one tool-bearing turn): the sealed item came back with
+// `include` and without it, both 1426 bytes, and replaying it in place answered 200. The same vendor
+// also accepted a tampered blob and a turn with the item dropped entirely (both 200), so the 4xx
+// retry below is a safety net for a vendor or an account that is stricter.
+/** Names an envelope as ours. Anthropic's own signatures never start with it. */
+export const ENVELOPE_PREFIX = "clauderipple.v1:";
+/** Thrown when a signature looks like ours and does not decode. */
+export class UndecodableEnvelope extends Error {
+}
+/**
+ * Our marker on a block, without decoding it: the cheap test `thinking.ts` and the request builders
+ * need before doing any work. Anthropic's own signatures are base64 and never carry this prefix.
+ */
+export function isOurSignature(signature) {
+    return typeof signature === "string" && signature.startsWith(ENVELOPE_PREFIX);
+}
+/** The `signature` of a block of ours: the envelope, base64url so it survives any signature field. */
+export function encodeEnvelope(envelope) {
+    return ENVELOPE_PREFIX + Buffer.from(JSON.stringify(envelope), "utf8").toString("base64url");
+}
+function envelope(value) {
+    if (!value || typeof value !== "object")
+        return null;
+    const e = value;
+    if (typeof e.p !== "string" || typeof e.m !== "string")
+        return null;
+    if (e.w === "chat")
+        return typeof e.f === "string" && e.f.length > 0 ? { w: "chat", p: e.p, m: e.m, f: e.f } : null;
+    if (e.w === "responses")
+        return e.r && typeof e.r === "object" ? { w: "responses", p: e.p, m: e.m, r: e.r } : null;
+    return null;
+}
+/**
+ * The envelope on a signature, or null when it is not ours. A signature that carries our prefix and
+ * does not decode is a broken carrier, not a foreign one, so it throws rather than passing silently
+ * as someone else's — the caller logs it and moves on.
+ */
+export function decodeEnvelope(signature) {
+    if (!isOurSignature(signature))
+        return null;
+    const text = signature.slice(ENVELOPE_PREFIX.length);
+    // Guard the decode: a signature is attacker-visible text and a gigabyte of base64 must not become
+    // a gigabyte of JSON. A sealed reasoning blob runs a few KB.
+    if (text.length > 512 * 1024)
+        throw new UndecodableEnvelope("envelope too large");
+    let parsed;
+    try {
+        parsed = JSON.parse(Buffer.from(text, "base64url").toString("utf8"));
+    }
+    catch {
+        throw new UndecodableEnvelope("envelope did not decode");
+    }
+    const decoded = envelope(parsed);
+    if (!decoded)
+        throw new UndecodableEnvelope("envelope was not a recognizable shape");
+    return decoded;
+}
+/**
+ * Whether a stored item is worth replaying at all. A reasoning item with no `encrypted_content`
+ * carries nothing the backend can resume — the summary is text it thinks in, not state — so it is
+ * not carried and never replayed. Measured 2026-10-14 (Codex records, 161 items across one day):
+ * every item the CLI replayed had the sealed blob, and most had an empty summary.
+ */
+export function replayableReasoning(stored) {
+    if (stored.type !== "reasoning")
+        return null;
+    const encrypted = stored.encrypted_content;
+    if (typeof encrypted !== "string" || encrypted.length === 0)
+        return null;
+    // Only the fields the wire defines are forwarded: a vendor's item may carry bookkeeping
+    // (`internal_chat_message_metadata_passthrough`) that is meaningless and unverified to send back.
+    const out = { type: "reasoning", encrypted_content: encrypted };
+    if (typeof stored.id === "string" && stored.id.length > 0)
+        out.id = stored.id;
+    if (Array.isArray(stored.summary))
+        out.summary = stored.summary;
+    return out;
+}
+/**
+ * The envelope on an assistant block, when it is ours *and* usable here: the right wire, and the
+ * same provider and model that made it. Anything else returns null as if the block were foreign —
+ * reasoning is state, and state from another model is not merely useless, it is the thing a vendor
+ * refuses. A signature that is ours but broken, or names another model, reports through `onDrop` so
+ * the caller can count it; neither is an error worth failing a turn over.
+ */
+export function envelopeFor(block, wire, env, onDrop) {
+    const b = block;
+    if (!b || typeof b !== "object" || b.type !== "thinking" || !isOurSignature(b.signature))
+        return null;
+    let decoded;
+    try {
+        const got = decodeEnvelope(b.signature);
+        if (!got)
+            return null;
+        decoded = got;
+    }
+    catch {
+        onDrop("the envelope did not decode");
+        return null;
+    }
+    if (decoded.w !== wire)
+        return null;
+    if (env && (decoded.p !== env.p || decoded.m !== env.m)) {
+        onDrop(`reasoning came from ${decoded.p}/${decoded.m}`);
+        return null;
+    }
+    return decoded;
+}
+/** `type` matters as much as the wording: a vendor that says "reasoning" is answering about this. */
+const REASONING_REFUSAL = /reasoning|encrypted|\binput\[\d+\]|\bitem\b|signature/i;
+/**
+ * Whether a 4xx refusal is about the reasoning that was replayed, and so is worth one retry without
+ * it. Only a request that carried replayed reasoning can be refused for carrying it, and a sealed
+ * blob minted on one account or one model is the thing most likely to be refused on another.
+ */
+export function refusesReplayedReasoning(status, message) {
+    return status >= 400 && status < 500 && (status === 422 || REASONING_REFUSAL.test(message));
+}

package/dist/router/src/remote-host.js

@@ -0,0 +1,320 @@
+// A remote (SSH) host that runs Claude Code for a Claude Desktop session (issue #67).
+//
+// Desktop's Code tab can run a session on a Linux host over SSH. Claude Code then runs *there*,
+// reads that host's `~/.claude/settings.json`, and has no route to this router: 127.0.0.1 on the
+// remote is the remote. Desktop opens its SSH connection with the bundled ssh2 library, which only
+// forwards local→remote and never reads `RemoteForward` from ~/.ssh/config, so the router holds its
+// own reverse tunnel (remote-tunnel.ts) and this module puts on the remote what a session there
+// needs: the CA certificate, the env that points Claude Code at the tunnel, and the worker agent
+// files. See docs/ARCHITECTURE.md "Remote (SSH) sessions".
+//
+// Everything on the remote is done by POSIX `sh` scripts fed to `ssh <host> sh -s` on stdin. No
+// node or python there, no quoting of a command line through whatever login shell the remote user
+// has, and the host name only ever travels as its own argv element — never through a local shell.
+import { spawn } from "node:child_process";
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+/** The remote port the tunnel listens on (remote 127.0.0.1) unless `--port` says otherwise. */
+export const DEFAULT_REMOTE_PORT = 18791;
+/** Our directory under the remote home: the CA copy and the record of what we put there. */
+export const REMOTE_DIR = ".clauderipple-remote";
+/** The remote settings.json is copied here once, before the first time we change it. */
+export const SETTINGS_BACKUP_SUFFIX = ".clauderipple-backup";
+/**
+ * Why `host` cannot be handed to ssh, or null when it can. An ssh alias or `user@host`, nothing
+ * else: a leading `-` would be read as an option (`-oProxyCommand=…` runs a command), and anything
+ * outside a hostname's characters has no business in one.
+ */
+export function hostProblem(host) {
+    if (typeof host !== "string" || host === "")
+        return "an ssh host is required (an ssh alias or user@host)";
+    if (host.length > 255)
+        return "the ssh host is longer than 255 characters";
+    if (host.startsWith("-"))
+        return `"${host}" starts with "-", which ssh would read as an option`;
+    if (!/^[A-Za-z0-9_.@:-]+$/.test(host))
+        return `"${host}" is not an ssh alias or user@host (letters, digits and . _ @ : - only)`;
+    return null;
+}
+export function portProblem(port) {
+    return Number.isInteger(port) && port > 0 && port < 65536 ? null : `port must be an integer from 1 to 65535`;
+}
+/** The OpenSSH client: Windows ships it as an optional feature in System32\OpenSSH. */
+export function sshExecutable() {
+    if (process.platform !== "win32")
+        return "ssh";
+    const builtIn = path.join(process.env.SystemRoot ?? "C:\\Windows", "System32", "OpenSSH", "ssh.exe");
+    return fs.existsSync(builtIn) ? builtIn : "ssh.exe";
+}
+/**
+ * Extra ssh arguments from `CLAUDERIPPLE_SSH_OPTIONS` (a JSON array of strings), placed before the
+ * host. Exists for the end-to-end test, which points ssh at a throwaway sshd with its own key and
+ * known_hosts instead of the user's ssh setup; nothing in the product sets it.
+ */
+export function extraSshOptions() {
+    const raw = process.env.CLAUDERIPPLE_SSH_OPTIONS;
+    if (!raw)
+        return [];
+    const parsed = JSON.parse(raw);
+    if (!Array.isArray(parsed) || parsed.some((a) => typeof a !== "string"))
+        throw new Error("CLAUDERIPPLE_SSH_OPTIONS must be a JSON array of strings");
+    return parsed;
+}
+/** Never ask: a prompt nobody can answer would hang the router or the CLI. */
+export const BATCH_OPTIONS = ["-o", "BatchMode=yes", "-o", "ConnectTimeout=10"];
+export const SSH_MISSING = "ssh was not found. Install the OpenSSH client (on Windows: Settings → System → Optional features → OpenSSH Client).";
+export const spawnSsh = (args, opts = {}) => new Promise((resolve) => {
+    let stdout = "";
+    let stderr = "";
+    let settled = false;
+    const done = (r) => {
+        if (settled)
+            return;
+        settled = true;
+        clearTimeout(timer);
+        resolve(r);
+    };
+    const child = spawn(sshExecutable(), args, { stdio: ["pipe", "pipe", "pipe"], windowsHide: true });
+    const timer = setTimeout(() => {
+        child.kill("SIGKILL");
+        done({ code: null, stdout, stderr, error: `ssh timed out after ${Math.round((opts.timeoutMs ?? 60_000) / 1000)}s` });
+    }, opts.timeoutMs ?? 60_000);
+    child.stdout.on("data", (d) => (stdout += d.toString("utf8")));
+    child.stderr.on("data", (d) => (stderr += d.toString("utf8")));
+    child.stdin.on("error", () => { }); // ssh gone before reading its input: the exit says why
+    child.on("error", (e) => done({ code: null, stdout, stderr, error: e.code === "ENOENT" ? SSH_MISSING : e.message }));
+    child.on("close", (code) => done({ code, stdout, stderr }));
+    child.stdin.end(opts.input ?? "");
+});
+/** The last non-empty line ssh printed, which is where it says what went wrong. */
+function lastLine(text) {
+    return text.split(/\r?\n/).map((l) => l.trim()).filter(Boolean).pop() ?? "";
+}
+/** Run a POSIX sh script on `host` and return its stdout. Throws with ssh's own words on failure. */
+export async function runRemoteScript(run, host, script, timeoutMs = 60_000) {
+    const problem = hostProblem(host);
+    if (problem)
+        throw new Error(problem);
+    const r = await run([...BATCH_OPTIONS, ...extraSshOptions(), host, "sh", "-s"], { input: script, timeoutMs });
+    if (r.error)
+        throw new Error(r.error);
+    if (r.code === 255)
+        throw new SshConnectError(host, lastLine(r.stderr) || "ssh exited with 255");
+    if (r.code !== 0)
+        throw new Error(`script on ${host} failed (exit ${r.code}): ${lastLine(r.stderr) || "no message"}`);
+    return r.stdout;
+}
+/** ssh itself could not connect or authenticate (exit 255), as opposed to our script failing. */
+export class SshConnectError extends Error {
+    host;
+    detail;
+    constructor(host, detail) {
+        super(`cannot reach ${host} over ssh: ${detail}`);
+        this.host = host;
+        this.detail = detail;
+    }
+}
+const AGENT_NAME = /^[a-z0-9][a-z0-9-]*$/;
+export function remoteCaPath(home) {
+    return `${home}/${REMOTE_DIR}/ca.pem`;
+}
+export function remoteProxyUrl(port) {
+    return `http://127.0.0.1:${port}`;
+}
+export async function inspectRemote(run, host) {
+    const m = `@@cr-${crypto.randomBytes(6).toString("hex")}`;
+    const script = [
+        `m='${m}'`,
+        `f="$HOME/.claude/settings.json"`,
+        `printf '%s home\\n' "$m"; printf '%s\\n' "$HOME"`,
+        `printf '%s settings\\n' "$m"`,
+        `if [ -e "$f" ]; then printf 'present\\n'; cat "$f" || exit 1; printf '\\n'; else printf 'missing\\n'; fi`,
+        `printf '%s sum\\n' "$m"`,
+        `if [ -e "$f" ]; then cksum < "$f" || exit 1; fi`,
+        `printf '%s backup\\n' "$m"`,
+        `if [ -e "$f${SETTINGS_BACKUP_SUFFIX}" ]; then printf 'yes\\n'; else printf 'no\\n'; fi`,
+        `printf '%s record\\n' "$m"`,
+        `if [ -e "$HOME/${REMOTE_DIR}/agents.json" ]; then cat "$HOME/${REMOTE_DIR}/agents.json"; printf '\\n'; fi`,
+        `printf '%s agents\\n' "$m"`,
+        `for x in "$HOME/.claude/agents"/*.md; do if [ -e "$x" ]; then basename "$x" .md; fi; done`,
+        `printf '%s end\\n' "$m"`,
+        `exit 0`,
+        "",
+    ].join("\n");
+    const out = await runRemoteScript(run, host, script);
+    const sections = new Map();
+    let current = null;
+    for (const line of out.split("\n")) {
+        if (line.startsWith(`${m} `)) {
+            current = [];
+            sections.set(line.slice(m.length + 1).trim(), current);
+        }
+        else
+            current?.push(line);
+    }
+    if (!sections.has("end"))
+        throw new Error(`unexpected answer from ${host} (is its shell POSIX sh?)`);
+    const text = (name) => (sections.get(name) ?? []).join("\n");
+    const home = text("home").trim();
+    if (!home.startsWith("/"))
+        throw new Error(`${host} reported HOME="${home}"; a remote host must be Linux or another POSIX system`);
+    const settingsLines = sections.get("settings") ?? [];
+    const present = settingsLines[0] === "present";
+    let record = null;
+    const recordText = text("record").trim();
+    if (recordText) {
+        try {
+            const parsed = JSON.parse(recordText);
+            record = {
+                agents: Array.isArray(parsed.agents) ? parsed.agents.filter((a) => typeof a === "string" && AGENT_NAME.test(a)) : [],
+                ...(typeof parsed.proxyUrl === "string" ? { proxyUrl: parsed.proxyUrl } : {}),
+                ...(typeof parsed.caPath === "string" ? { caPath: parsed.caPath } : {}),
+            };
+        }
+        catch {
+            record = { agents: [] }; // ours but unreadable: nothing in it can be trusted as a delete list
+        }
+    }
+    return {
+        home,
+        settings: present ? settingsLines.slice(1).join("\n") : null,
+        settingsSum: present ? text("sum").trim() || null : null,
+        backup: text("backup").trim() === "yes",
+        record,
+        agentFiles: text("agents").split("\n").map((l) => l.trim()).filter(Boolean),
+    };
+}
+// ---- Writing to the remote ----------------------------------------------------------------
+/** `"$HOME/<rel>"` for a path we built ourselves; refuses anything a shell could read differently. */
+function homePath(rel) {
+    if (!/^[A-Za-z0-9._/-]+$/.test(rel) || rel.split("/").includes(".."))
+        throw new Error(`refusing remote path "${rel}"`);
+    return `"$HOME/${rel}"`;
+}
+/**
+ * Lines that replace `$HOME/<rel>` with `content`: a quoted heredoc into a temp file, then `mv`, so
+ * a reader sees the old file or the new one. A quoted delimiter means the shell expands nothing in
+ * the body. A heredoc always ends in a newline, so content without one gains one.
+ */
+export function writeFileLines(rel, content) {
+    const body = content.endsWith("\n") ? content.slice(0, -1) : content;
+    let delim = "";
+    do
+        delim = `CLAUDERIPPLE_EOF_${crypto.randomBytes(8).toString("hex")}`;
+    while (body.split("\n").includes(delim));
+    const target = homePath(rel);
+    const tmp = homePath(`${rel}.clauderipple-tmp`);
+    return [`cat > ${tmp} <<'${delim}' || exit 1`, body, delim, `mv -f ${tmp} ${target} || exit 1`];
+}
+/**
+ * Stops the script (exit 3) when the remote settings.json is no longer the file `state` read. Put
+ * first in a script that will write it, so a refusal leaves nothing half done.
+ */
+export function settingsGuardLine(state) {
+    const f = `"$HOME/.claude/settings.json"`;
+    return state.settingsSum === null
+        ? `if [ -e ${f} ]; then echo "~/.claude/settings.json appeared while it was being edited; run the command again" >&2; exit 3; fi`
+        : `if [ "$(cksum < ${f})" != '${state.settingsSum.replace(/'/g, "")}' ]; then echo "~/.claude/settings.json changed while it was being edited; run the command again" >&2; exit 3; fi`;
+}
+/**
+ * Lines that write the remote settings.json, but only if it is still the file `state` read: a
+ * session or the user may have changed it in between, and that change must not be overwritten.
+ * The first time we change it, the original is copied to `settings.json.clauderipple-backup`.
+ */
+export function settingsWriteLines(state, content) {
+    const f = `"$HOME/.claude/settings.json"`;
+    return [
+        `mkdir -p "$HOME/.claude" || exit 1`,
+        settingsGuardLine(state),
+        `if [ -e ${f} ] && [ ! -e "$HOME/.claude/settings.json${SETTINGS_BACKUP_SUFFIX}" ]; then cp -p ${f} "$HOME/.claude/settings.json${SETTINGS_BACKUP_SUFFIX}" || exit 1; fi`,
+        ...writeFileLines(".claude/settings.json", content),
+    ];
+}
+/**
+ * The router's CA certificate — the file the local install points NODE_EXTRA_CA_CERTS at,
+ * `<home>/ca.pem` (cli/src/settings.ts via certPaths) — and the agent files this router generated,
+ * as `<home>/generated-agents.json` lists them (agents.ts). Only the public certificate: the file
+ * is checked to be one, so a key can never travel by mistake.
+ */
+export function readLocalAssets(opts) {
+    const caFile = path.join(opts.home, "ca.pem");
+    let caPem;
+    try {
+        caPem = fs.readFileSync(caFile, "utf8");
+    }
+    catch {
+        throw new Error(`no CA certificate at ${caFile}; run \`clauderipple install\` first`);
+    }
+    if (!caPem.includes("-----BEGIN CERTIFICATE-----") || /PRIVATE KEY/.test(caPem))
+        throw new Error(`${caFile} is not a certificate; refusing to copy it`);
+    let names = [];
+    try {
+        const parsed = JSON.parse(fs.readFileSync(path.join(opts.home, "generated-agents.json"), "utf8"));
+        if (Array.isArray(parsed.agents))
+            names = parsed.agents.filter((a) => typeof a === "string" && AGENT_NAME.test(a));
+    }
+    catch {
+        /* no generated agents yet */
+    }
+    const agents = [];
+    for (const name of [...names].sort()) {
+        try {
+            agents.push({ name, content: fs.readFileSync(path.join(opts.agentDir, `${name}.md`), "utf8") });
+        }
+        catch {
+            /* listed but gone: the router removes it from the manifest on its next sync */
+        }
+    }
+    return { caPem, agents };
+}
+/** Changes whenever what a remote should hold changes; a tunnel re-syncs only on a new value. */
+export function assetsFingerprint(a) {
+    const h = crypto.createHash("sha256").update(a.caPem);
+    for (const agent of a.agents)
+        h.update(`\0${agent.name}\0${agent.content}`);
+    return h.digest("hex");
+}
+/**
+ * Which agent files to write and remove on the remote. A remote file of the same name that we did
+ * not put there is someone's own agent and is left alone; a file we put there whose worker is no
+ * longer generated here goes.
+ */
+export function planAgents(local, state) {
+    const ours = new Set(state.record?.agents ?? []);
+    const present = new Set(state.agentFiles);
+    const write = local.filter((n) => !present.has(n) || ours.has(n));
+    const skipped = local.filter((n) => present.has(n) && !ours.has(n));
+    const remove = [...ours].filter((n) => !local.includes(n));
+    return { write, skipped, remove };
+}
+/** Lines that put the CA and the planned agent files on the remote and record what we own. */
+export function assetLines(assets, plan, record) {
+    const lines = [`mkdir -p "$HOME/${REMOTE_DIR}" "$HOME/.claude/agents" || exit 1`, ...writeFileLines(`${REMOTE_DIR}/ca.pem`, assets.caPem)];
+    for (const name of plan.write) {
+        const agent = assets.agents.find((a) => a.name === name);
+        if (agent && AGENT_NAME.test(name))
+            lines.push(...writeFileLines(`.claude/agents/${name}.md`, agent.content));
+    }
+    for (const name of plan.remove)
+        if (AGENT_NAME.test(name))
+            lines.push(`rm -f ${homePath(`.claude/agents/${name}.md`)}`);
+    const next = { agents: [...plan.write].sort(), ...record };
+    lines.push(...writeFileLines(`${REMOTE_DIR}/agents.json`, JSON.stringify(next, null, 2) + "\n"));
+    return lines;
+}
+export function script(lines) {
+    return ["umask 077", ...lines, "exit 0", ""].join("\n");
+}
+/**
+ * Bring the CA and agent files on `host` in step with this machine. What the tunnel runs each time
+ * it comes up and whenever the router regenerates the agent files; settings.json is not touched
+ * (that is `remote add`'s job, once).
+ */
+export async function syncRemoteAssets(run, host, assets) {
+    const state = await inspectRemote(run, host);
+    const plan = planAgents(assets.agents.map((a) => a.name), state);
+    const { agents: _agents, ...kept } = state.record ?? { agents: [] };
+    await runRemoteScript(run, host, script(assetLines(assets, plan, kept)));
+    return { home: state.home, plan };
+}