feat: recursive spawn tree passback (#3023)

* feat: pull child spawn history back to parent for `spawn tree`

When the interactive session ends (or headless mode completes), the
parent downloads the child VM's history.json and merges records into
local history. Before downloading, it runs `spawn pull-history` on the
child, which recursively pulls from all grandchildren — so the full
tree collapses up to the root regardless of depth.

Changes:
- Add getParentFields() — sets parent_id/depth on saveSpawnRecord calls
- Add pullChildHistory() — downloads + merges child history after session
- Add `spawn pull-history` command for recursive SSH-based history pull
- Add 11 tests for parseAndMergeChildHistory

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* chore: trigger CI recompute

Agent: pr-maintainer
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* fix(security): validate user/ip params before SSH exec in pull-history

Agent: pr-maintainer
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* fix(security): use shared validators for SSH params in pull-history and delete

Replace inline regex checks in pull-history.ts with validateUsername()
and validateConnectionIP() from security.ts, matching the pattern used
across connect.ts, fix.ts, and link.ts. Also add the same validation
to delete.ts:pullChildHistory which had no SSH parameter validation.

orchestrate.ts uses the runner abstraction (not raw user@ip), so its
SSH params come from the cloud provider, not untrusted history records.

Agent: pr-maintainer
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

---------

Co-authored-by: Ahmed Abushagur <ahmed@abushagur.com>
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Co-authored-by: B <6723574+louisgv@users.noreply.github.com>

Author: 4 people

packages/cli/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openrouter/spawn",
-  "version": "0.26.13",
+  "version": "0.27.0",
   "type": "module",
   "bin": {
     "spawn": "cli.js"

packages/cli/src/__tests__/pull-history.test.ts

@@ -0,0 +1,253 @@
+import { afterEach, beforeEach, describe, expect, it, spyOn } from "bun:test";
+import { mkdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { cmdPullHistory, parseAndMergeChildHistory } from "../commands/pull-history.js";
+import * as historyModule from "../history.js";
+import { loadHistory } from "../history.js";
+
+// ─── parseAndMergeChildHistory tests ─────────────────────────────────────────
+
+describe("parseAndMergeChildHistory", () => {
+  let origSpawnHome: string | undefined;
+
+  beforeEach(() => {
+    origSpawnHome = process.env.SPAWN_HOME;
+    // Use isolated temp dir for history (preload sets HOME to a temp dir)
+    const tmpHome = process.env.HOME ?? "/tmp";
+    const spawnDir = join(tmpHome, `.spawn-test-${Date.now()}-${Math.random()}`);
+    mkdirSync(spawnDir, {
+      recursive: true,
+    });
+    process.env.SPAWN_HOME = spawnDir;
+    // Write empty history
+    writeFileSync(
+      join(spawnDir, "history.json"),
+      JSON.stringify({
+        version: 1,
+        records: [],
+      }),
+    );
+  });
+
+  afterEach(() => {
+    if (origSpawnHome === undefined) {
+      delete process.env.SPAWN_HOME;
+    } else {
+      process.env.SPAWN_HOME = origSpawnHome;
+    }
+  });
+
+  it("returns 0 for empty string", () => {
+    expect(parseAndMergeChildHistory("", "parent-123")).toBe(0);
+  });
+
+  it("returns 0 for empty object", () => {
+    expect(parseAndMergeChildHistory("{}", "parent-123")).toBe(0);
+  });
+
+  it("returns 0 for invalid JSON", () => {
+    expect(parseAndMergeChildHistory("not json", "parent-123")).toBe(0);
+  });
+
+  it("returns 0 for empty records array", () => {
+    const json = JSON.stringify({
+      version: 1,
+      records: [],
+    });
+    expect(parseAndMergeChildHistory(json, "parent-123")).toBe(0);
+  });
+
+  it("parses and merges valid child records", () => {
+    const json = JSON.stringify({
+      version: 1,
+      records: [
+        {
+          id: "child-1",
+          agent: "claude",
+          cloud: "hetzner",
+          timestamp: "2026-03-26T00:00:00Z",
+        },
+        {
+          id: "child-2",
+          agent: "codex",
+          cloud: "digitalocean",
+          timestamp: "2026-03-26T00:01:00Z",
+          name: "test-spawn",
+        },
+      ],
+    });
+
+    const count = parseAndMergeChildHistory(json, "parent-123");
+    expect(count).toBe(2);
+
+    // Verify records were merged into history
+    const history = loadHistory();
+    const child1 = history.find((r) => r.id === "child-1");
+    const child2 = history.find((r) => r.id === "child-2");
+    expect(child1).toBeDefined();
+    expect(child1!.agent).toBe("claude");
+    expect(child1!.parent_id).toBe("parent-123");
+    expect(child2).toBeDefined();
+    expect(child2!.name).toBe("test-spawn");
+    expect(child2!.parent_id).toBe("parent-123");
+  });
+
+  it("preserves existing parent_id from child records", () => {
+    const json = JSON.stringify({
+      version: 1,
+      records: [
+        {
+          id: "grandchild-1",
+          agent: "claude",
+          cloud: "aws",
+          timestamp: "2026-03-26T00:00:00Z",
+          parent_id: "child-abc",
+          depth: 2,
+        },
+      ],
+    });
+
+    const count = parseAndMergeChildHistory(json, "parent-123");
+    expect(count).toBe(1);
+
+    const history = loadHistory();
+    const gc = history.find((r) => r.id === "grandchild-1");
+    expect(gc).toBeDefined();
+    // parent_id should be preserved from the child record, not overwritten
+    // (mergeChildHistory only sets parent_id if it's not already set)
+    expect(gc!.parent_id).toBe("child-abc");
+    expect(gc!.depth).toBe(2);
+  });
+
+  it("skips records without an id", () => {
+    const json = JSON.stringify({
+      version: 1,
+      records: [
+        {
+          agent: "claude",
+          cloud: "hetzner",
+          timestamp: "2026-03-26T00:00:00Z",
+        },
+        {
+          id: "valid-1",
+          agent: "codex",
+          cloud: "gcp",
+          timestamp: "2026-03-26T00:01:00Z",
+        },
+      ],
+    });
+
+    const count = parseAndMergeChildHistory(json, "parent-123");
+    expect(count).toBe(1);
+  });
+
+  it("preserves connection info from child records", () => {
+    const json = JSON.stringify({
+      version: 1,
+      records: [
+        {
+          id: "child-conn",
+          agent: "claude",
+          cloud: "digitalocean",
+          timestamp: "2026-03-26T00:00:00Z",
+          connection: {
+            ip: "10.0.0.1",
+            user: "root",
+            server_id: "12345",
+          },
+        },
+      ],
+    });
+
+    const count = parseAndMergeChildHistory(json, "parent-123");
+    expect(count).toBe(1);
+
+    const history = loadHistory();
+    const child = history.find((r) => r.id === "child-conn");
+    expect(child!.connection?.ip).toBe("10.0.0.1");
+    expect(child!.connection?.server_id).toBe("12345");
+  });
+
+  it("deduplicates — calling twice with same records only merges once", () => {
+    const json = JSON.stringify({
+      version: 1,
+      records: [
+        {
+          id: "dedup-1",
+          agent: "claude",
+          cloud: "hetzner",
+          timestamp: "2026-03-26T00:00:00Z",
+        },
+      ],
+    });
+
+    parseAndMergeChildHistory(json, "parent-123");
+    parseAndMergeChildHistory(json, "parent-123");
+
+    const history = loadHistory();
+    const matches = history.filter((r) => r.id === "dedup-1");
+    expect(matches.length).toBe(1);
+  });
+
+  it("handles whitespace-only input", () => {
+    expect(parseAndMergeChildHistory("   \n  ", "parent-123")).toBe(0);
+  });
+
+  it("handles history without version field", () => {
+    const json = JSON.stringify({
+      records: [
+        {
+          id: "no-version",
+          agent: "hermes",
+          cloud: "sprite",
+          timestamp: "2026-03-26T00:00:00Z",
+        },
+      ],
+    });
+
+    const count = parseAndMergeChildHistory(json, "parent-123");
+    expect(count).toBe(1);
+  });
+});
+
+// ─── cmdPullHistory tests ───────────────────────────────────────────────────
+
+describe("cmdPullHistory", () => {
+  it("returns immediately when no active servers", async () => {
+    const spy = spyOn(historyModule, "getActiveServers").mockReturnValue([]);
+    await cmdPullHistory();
+    expect(spy).toHaveBeenCalledTimes(1);
+    spy.mockRestore();
+  });
+
+  it("skips servers without connection info", async () => {
+    const spy = spyOn(historyModule, "getActiveServers").mockReturnValue([
+      {
+        id: "test-1",
+        agent: "claude",
+        cloud: "hetzner",
+        timestamp: "2026-03-26T00:00:00Z",
+      },
+    ]);
+    // Should not throw — just skips the record with no connection
+    await cmdPullHistory();
+    spy.mockRestore();
+  });
+
+  it("skips servers with missing ip", async () => {
+    const spy = spyOn(historyModule, "getActiveServers").mockReturnValue([
+      {
+        id: "test-2",
+        agent: "claude",
+        cloud: "hetzner",
+        timestamp: "2026-03-26T00:00:00Z",
+        connection: {
+          ip: "",
+          user: "root",
+        },
+      },
+    ]);
+    await cmdPullHistory();
+    spy.mockRestore();
+  });
+});

packages/cli/src/commands/delete.ts

@@ -16,7 +16,12 @@ import {
 import { ensureHcloudToken, destroyServer as hetznerDestroyServer } from "../hetzner/hetzner.js";
 import { getActiveServers, loadHistory, markRecordDeleted, mergeChildHistory, SpawnRecordSchema } from "../history.js";
 import { loadManifest } from "../manifest.js";
-import { validateMetadataValue, validateServerIdentifier } from "../security.js";
+import {
+  validateConnectionIP,
+  validateMetadataValue,
+  validateServerIdentifier,
+  validateUsername,
+} from "../security.js";
 import { getHistoryPath } from "../shared/paths.js";
 import { asyncTryCatch, asyncTryCatchIf, isNetworkError, tryCatch } from "../shared/result.js";
 import { ensureSpriteAuthenticated, ensureSpriteCli, destroyServer as spriteDestroyServer } from "../sprite/sprite.js";
@@ -250,6 +255,14 @@ export async function pullChildHistory(record: SpawnRecord): Promise<void> {
     return;
   }
 
+  const connValidation = tryCatch(() => {
+    validateUsername(conn.user);
+    validateConnectionIP(conn.ip);
+  });
+  if (!connValidation.ok) {
+    return;
+  }
+
   const { ensureSshKeys, getSshKeyOpts } = await import("../shared/ssh-keys.js");
   const { SSH_BASE_OPTS } = await import("../shared/ssh.js");
 

packages/cli/src/commands/index.ts

@@ -34,6 +34,8 @@ export {
 } from "./list.js";
 // pick.ts — cmdPick
 export { cmdPick } from "./pick.js";
+// pull-history.ts — cmdPullHistory (recursive child history pull)
+export { cmdPullHistory } from "./pull-history.js";
 // run.ts — cmdRun, cmdRunHeadless, script failure guidance
 export {
   cmdRun,