arc402-cli 0.2.0

package/src/daemon/wallet-monitor.ts

@@ -0,0 +1,90 @@
+/**
+ * Wallet monitor — verifies wallet contract exists and is operational.
+ * Steps 4 and 5 of the daemon startup sequence (Spec 32 §3).
+ */
+import { ethers } from "ethers";
+import type { DaemonConfig } from "./config";
+import {
+  ARC402_WALLET_GUARDIAN_ABI,
+  ARC402_WALLET_MACHINE_KEY_ABI,
+} from "../abis";
+
+export interface WalletStatus {
+  contractAddress: string;
+  ownerAddress: string;
+  isFrozen: boolean;
+  machineKeyAuthorized: boolean;
+  ethBalance: string;
+}
+
+export async function verifyWallet(
+  config: DaemonConfig,
+  provider: ethers.Provider,
+  machineKeyAddress: string
+): Promise<WalletStatus> {
+  const { contract_address, owner_address } = config.wallet;
+
+  // Step 4: Verify wallet contract exists
+  const code = await provider.getCode(contract_address);
+  if (code === "0x") {
+    throw new Error(`No contract at wallet address ${contract_address}`);
+  }
+
+  const guardianContract = new ethers.Contract(
+    contract_address,
+    ARC402_WALLET_GUARDIAN_ABI,
+    provider
+  );
+
+  // Verify owner matches config (if owner_address is set)
+  if (owner_address) {
+    const onChainOwner: string = await guardianContract.owner();
+    if (onChainOwner.toLowerCase() !== owner_address.toLowerCase()) {
+      throw new Error(
+        `Wallet owner mismatch. Config: ${owner_address}, On-chain: ${onChainOwner}`
+      );
+    }
+  }
+
+  const onChainOwner: string = await guardianContract.owner();
+
+  // Step 5: Check wallet is not frozen
+  const frozen: boolean = await guardianContract.frozen();
+  if (frozen) {
+    throw new Error("Wallet is frozen. Daemon cannot operate.");
+  }
+
+  // Check machine key authorization (best effort — v1 wallets may not have registry)
+  let machineKeyAuthorized = false;
+  try {
+    const machineKeyContract = new ethers.Contract(
+      contract_address,
+      ARC402_WALLET_MACHINE_KEY_ABI,
+      provider
+    );
+    machineKeyAuthorized = await machineKeyContract.authorizedMachineKeys(machineKeyAddress);
+  } catch {
+    // v1 wallet may not have machine key registry — policy-based auth, continue
+    machineKeyAuthorized = true;
+  }
+
+  // Get ETH balance
+  const balanceBig = await provider.getBalance(contract_address);
+  const ethBalance = ethers.formatEther(balanceBig);
+
+  return {
+    contractAddress: contract_address,
+    ownerAddress: onChainOwner,
+    isFrozen: false,
+    machineKeyAuthorized,
+    ethBalance,
+  };
+}
+
+export async function getWalletBalance(
+  contractAddress: string,
+  provider: ethers.Provider
+): Promise<string> {
+  const balanceBig = await provider.getBalance(contractAddress);
+  return ethers.formatEther(balanceBig);
+}

package/src/drain-v4.ts

@@ -0,0 +1,159 @@
+/**
+ * drain-v4.ts
+ * Drains ETH from v4 wallet (0xb4aF8760) to owner (0x7745772d) via WalletConnect.
+ * Steps: openContext → attest → executeSpend → closeContext
+ */
+import { ethers } from "ethers";
+import { SignClient } from "@walletconnect/sign-client";
+import { KeyValueStorage } from "@walletconnect/keyvaluestorage";
+import qrcode from "qrcode-terminal";
+import path from "path";
+import os from "os";
+import * as fs from "fs";
+
+const V4_WALLET    = "0xb4aF8760d349a6A4C8495Ae4da9089bC84994eE6";
+const OWNER        = "0x7745772d67Cd52c1F38706bF5550AdcD925c7c00";
+const INTENT_ATTEST = "0x7ad8db6C5f394542E8e9658F86C85cC99Cf6D460";
+const CHAIN_ID     = 8453;
+const RPC          = "https://base-mainnet.g.alchemy.com/v2/YIA2uRCsFI-j5pqH-aRzflrACSlV1Qrs";
+
+// Leave 0.00005 ETH for gas
+const DRAIN_AMOUNT = ethers.parseEther("0.00045");
+
+const WALLET_ABI = [
+  "function openContext(bytes32 contextId, string calldata taskType) external",
+  "function attest(bytes32 attestationId, string calldata action, string calldata reason, address recipient, uint256 amount, address token, uint256 expiresAt) external",
+  "function executeSpend(address payable recipient, uint256 amount, string calldata category, bytes32 attestationId) external",
+  "function closeContext() external",
+  "function contextOpen() external view returns (bool)",
+];
+
+const ATTEST_ABI = [
+  "function attest(bytes32 attestationId, string calldata action, string calldata reason, address recipient, uint256 amount, address token, uint256 expiresAt) external",
+];
+
+async function main() {
+  const provider = new ethers.JsonRpcProvider(RPC);
+  const balance = await provider.getBalance(V4_WALLET);
+  console.log(`v4 balance: ${ethers.formatEther(balance)} ETH`);
+
+  if (balance < DRAIN_AMOUNT) {
+    console.error("Insufficient balance");
+    process.exit(1);
+  }
+
+  // Load config for machine key
+  const config = JSON.parse(fs.readFileSync(path.join(os.homedir(), ".arc402/config.json"), "utf8"));
+  const machineKey = new ethers.Wallet(config.privateKey, provider);
+  console.log(`Machine key: ${machineKey.address}`);
+
+  // WalletConnect setup
+  const projectId = config.walletConnectProjectId;
+  const storagePath = path.join(os.homedir(), ".arc402/wc-storage.json");
+  const client = await SignClient.init({
+    projectId,
+    metadata: { name: "ARC-402 Drain v4", description: "Drain v4 wallet ETH to owner", url: "https://app.arc402.xyz", icons: [] },
+    storage: new KeyValueStorage({ database: storagePath }),
+  });
+
+  const { uri, approval } = await client.connect({
+    requiredNamespaces: {
+      eip155: {
+        methods: ["eth_sendTransaction"],
+        chains: [`eip155:${CHAIN_ID}`],
+        events: ["chainChanged", "accountsChanged"],
+      },
+    },
+  });
+
+  console.log("\nScan this QR in MetaMask (make sure you're on Base):\n");
+  qrcode.generate(uri!, { small: true });
+  console.log(`\nMetaMask deep link:\nmetamask://wc?uri=${encodeURIComponent(uri!)}\n`);
+  console.log("Waiting for MetaMask approval...");
+
+  const session = await approval();
+  console.log("✓ MetaMask connected");
+
+  // Build transactions
+  const walletIface = new ethers.Interface(WALLET_ABI);
+  const attestIface = new ethers.Interface(ATTEST_ABI);
+
+  const contextId = ethers.keccak256(ethers.toUtf8Bytes(`drain-${Date.now()}`));
+  const attestationId = ethers.keccak256(ethers.toUtf8Bytes(`attest-${Date.now()}`));
+  const expiry = Math.floor(Date.now() / 1000) + 600; // 10 min
+
+  const account = session.namespaces.eip155.accounts[0].split(":")[2];
+  console.log(`Owner address: ${account}`);
+
+  async function sendTx(to: string, data: string, description: string) {
+    console.log(`\nSending tx: ${description}`);
+    const result = await client.request({
+      topic: session.topic,
+      chainId: `eip155:${CHAIN_ID}`,
+      request: {
+        method: "eth_sendTransaction",
+        params: [{ from: account, to, data, gas: "0x30D40" }],
+      },
+    });
+    console.log(`✓ ${description}: ${result}`);
+    // Wait for confirmation
+    const receipt = await provider.waitForTransaction(result as string, 1, 60000);
+    console.log(`  Confirmed in block ${receipt?.blockNumber}`);
+    return result;
+  }
+
+  // Step 1: close stale context via machine key if needed
+  console.log("\nStep 1: Checking context state...");
+  const walletContract = new ethers.Contract(V4_WALLET, WALLET_ABI, machineKey);
+  const isOpen = await walletContract.contextOpen();
+  if (isOpen) {
+    console.log("  Stale context found — closing it...");
+    const closeTx = await walletContract.closeContext();
+    await closeTx.wait(2);
+    await new Promise(r => setTimeout(r, 3000));
+    console.log(`  ✓ Closed: ${closeTx.hash}`);
+  }
+
+  // Step 2: owner opens context (MetaMask signs — so simulation sees it)
+  console.log("\nStep 2: Owner opens context via MetaMask...");
+  await sendTx(
+    V4_WALLET,
+    new ethers.Interface(WALLET_ABI).encodeFunctionData("openContext", [contextId, "drain"]),
+    "Open context"
+  );
+
+  // Step 3: call attest() directly on wallet (onlyOwnerOrMachineKey — no executeContractCall needed)
+  const walletIface2 = new ethers.Interface(WALLET_ABI);
+  await sendTx(
+    V4_WALLET,
+    walletIface2.encodeFunctionData("attest", [
+      attestationId,
+      "spend",
+      "drain v4 to owner",
+      OWNER,
+      DRAIN_AMOUNT,
+      ethers.ZeroAddress,
+      expiry,
+    ]),
+    "Create spend attestation"
+  );
+
+  // Step 4: machine key executes spend
+  console.log("\nStep 4: Executing spend (machine key)...");
+  const spendTx = await walletContract.executeSpend(OWNER, DRAIN_AMOUNT, "general", attestationId);
+  await spendTx.wait();
+  console.log(`✓ ETH sent to owner: ${spendTx.hash}`);
+
+  // Step 4: close context
+  const closeTx = await walletContract.closeContext();
+  await closeTx.wait();
+  console.log(`✓ Context closed: ${closeTx.hash}`);
+
+  const newBalance = await provider.getBalance(V4_WALLET);
+  console.log(`\nv4 remaining balance: ${ethers.formatEther(newBalance)} ETH`);
+  console.log(`Done. ${ethers.formatEther(DRAIN_AMOUNT)} ETH sent to ${OWNER}`);
+
+  process.exit(0);
+}
+
+main().catch(e => { console.error(e); process.exit(1); });

package/src/endpoint-config.ts

@@ -0,0 +1,83 @@
+import * as fs from "fs";
+import * as os from "os";
+import * as path from "path";
+
+export const ARC402_DIR = path.join(os.homedir(), ".arc402");
+export const ENDPOINT_CONFIG_PATH = path.join(ARC402_DIR, "endpoint.json");
+export const DEFAULT_LOCAL_INGRESS_TARGET = "http://127.0.0.1:4402";
+export const DEFAULT_TUNNEL_MODE = "host-cloudflared" as const;
+
+export interface EndpointConfig {
+  version: 1;
+  agentName: string;
+  hostname: string;
+  publicUrl: string;
+  localIngressTarget: string;
+  tunnelMode: "host-cloudflared";
+  tunnelTarget?: string;
+  walletAddress?: string;
+  subdomainApi?: string;
+  notes?: string;
+  claimedAt?: string;
+  updatedAt: string;
+}
+
+export function endpointConfigExists(): boolean {
+  return fs.existsSync(ENDPOINT_CONFIG_PATH);
+}
+
+export function loadEndpointConfig(): EndpointConfig | null {
+  if (!endpointConfigExists()) return null;
+  try {
+    return JSON.parse(fs.readFileSync(ENDPOINT_CONFIG_PATH, "utf-8")) as EndpointConfig;
+  } catch {
+    return null;
+  }
+}
+
+export function saveEndpointConfig(config: EndpointConfig): void {
+  fs.mkdirSync(ARC402_DIR, { recursive: true, mode: 0o700 });
+  fs.writeFileSync(ENDPOINT_CONFIG_PATH, JSON.stringify(config, null, 2) + "\n", { mode: 0o600 });
+}
+
+export function normalizeAgentName(value: string): string {
+  return value.trim().toLowerCase().replace(/[^a-z0-9-]/g, "-").replace(/-+/g, "-").replace(/^-|-$/g, "");
+}
+
+export function buildHostname(agentName: string): string {
+  return `${normalizeAgentName(agentName)}.arc402.xyz`;
+}
+
+export function buildPublicUrl(hostname: string): string {
+  return `https://${hostname}`;
+}
+
+export function buildEndpointConfig(input: {
+  agentName: string;
+  localIngressTarget?: string;
+  tunnelMode?: "host-cloudflared";
+  tunnelTarget?: string;
+  walletAddress?: string;
+  subdomainApi?: string;
+  notes?: string;
+  claimedAt?: string;
+  existing?: EndpointConfig | null;
+}): EndpointConfig {
+  const normalizedName = normalizeAgentName(input.agentName);
+  const hostname = buildHostname(normalizedName);
+  const now = new Date().toISOString();
+  return {
+    version: 1,
+    agentName: normalizedName,
+    hostname,
+    publicUrl: buildPublicUrl(hostname),
+    localIngressTarget: input.localIngressTarget ?? input.existing?.localIngressTarget ?? DEFAULT_LOCAL_INGRESS_TARGET,
+    tunnelMode: input.tunnelMode ?? input.existing?.tunnelMode ?? DEFAULT_TUNNEL_MODE,
+    tunnelTarget: input.tunnelTarget ?? input.existing?.tunnelTarget,
+    walletAddress: input.walletAddress ?? input.existing?.walletAddress,
+    subdomainApi: input.subdomainApi ?? input.existing?.subdomainApi,
+    notes: input.notes ?? input.existing?.notes,
+    claimedAt: input.claimedAt ?? input.existing?.claimedAt,
+    updatedAt: now,
+  };
+}

package/src/index.ts

@@ -0,0 +1,75 @@
+#!/usr/bin/env node
+import { Command } from "commander";
+import { registerAcceptCommand } from "./commands/accept";
+import { registerAgentCommands } from "./commands/agent";
+import { registerAgreementsCommands } from "./commands/agreements";
+import { registerArbitratorCommand } from "./commands/arbitrator";
+import { registerCancelCommand } from "./commands/cancel";
+import { registerChannelCommands } from "./commands/channel";
+import { registerConfigCommands } from "./commands/config";
+import { registerDeliverCommand } from "./commands/deliver";
+import { registerDiscoverCommand } from "./commands/discover";
+import { registerEndpointCommands } from "./commands/endpoint";
+import { registerDisputeCommand } from "./commands/dispute";
+import { registerHireCommand } from "./commands/hire";
+import { registerHandshakeCommand } from "./commands/agent-handshake";
+import { registerNegotiateCommands } from "./commands/negotiate";
+import { registerRelayCommands } from "./commands/relay";
+import { registerRemediateCommands } from "./commands/remediate";
+import { registerDaemonCommands } from "./commands/daemon";
+import { registerOpenShellCommands } from "./commands/openshell";
+import { registerWorkroomCommands } from "./commands/workroom";
+import { registerArenaHandshakeCommands } from "./commands/arena-handshake";
+import { registerTrustCommand } from "./commands/trust";
+import { registerWalletCommands } from "./commands/wallet";
+import { renderBanner } from "./ui/banner";
+import { registerOwnerCommands } from "./commands/owner";
+import { registerSetupCommands } from "./commands/setup";
+import { registerVerifyCommand } from "./commands/verify";
+import { registerContractInteractionCommands } from "./commands/contract-interaction";
+import { registerWatchtowerCommands } from "./commands/watchtower";
+import { registerColdStartCommands } from "./commands/coldstart";
+import { registerMigrateCommands } from "./commands/migrate";
+import reputation from "./commands/reputation.js";
+import policy from "./commands/policy.js";
+
+// Show banner when invoked with no arguments
+if (process.argv.length <= 2) {
+  renderBanner();
+  process.exit(0);
+}
+
+const program = new Command();
+program.name("arc402").description("ARC-402 CLI aligned to canonical-capability discovery → negotiate → hire → remediate → dispute workflow").version("0.2.0");
+registerConfigCommands(program);
+registerHandshakeCommand(program);
+registerAgentCommands(program);
+registerDiscoverCommand(program);
+registerEndpointCommands(program);
+registerNegotiateCommands(program);
+registerHireCommand(program);
+registerAgreementsCommands(program);
+registerAcceptCommand(program);
+registerDeliverCommand(program);
+registerRemediateCommands(program);
+registerDisputeCommand(program);
+registerArbitratorCommand(program);
+registerCancelCommand(program);
+registerChannelCommands(program);
+registerRelayCommands(program);
+registerDaemonCommands(program);
+registerOpenShellCommands(program);
+registerWorkroomCommands(program);
+registerArenaHandshakeCommands(program);
+registerTrustCommand(program);
+registerWalletCommands(program);
+registerOwnerCommands(program);
+registerSetupCommands(program);
+registerVerifyCommand(program);
+registerContractInteractionCommands(program);
+registerWatchtowerCommands(program);
+registerColdStartCommands(program);
+registerMigrateCommands(program);
+program.addCommand(reputation);
+program.addCommand(policy);
+program.parse(process.argv);

package/src/openshell-runtime.ts

@@ -0,0 +1,277 @@
+import * as fs from "fs";
+import * as os from "os";
+import * as path from "path";
+import { spawnSync } from "child_process";
+import { parse as parseToml } from "smol-toml";
+import { loadConfig } from "./config";
+
+export const ARC402_DIR = path.join(os.homedir(), ".arc402");
+export const OPENSHELL_TOML = path.join(ARC402_DIR, "openshell.toml");
+export const OPENSHELL_RUNTIME_DIR = path.join(ARC402_DIR, "openshell-runtime");
+export const OPENSHELL_RUNTIME_TARBALL = path.join(OPENSHELL_RUNTIME_DIR, "arc402-cli-runtime.tgz");
+export const DEFAULT_RUNTIME_REMOTE_ROOT = "/sandbox/.arc402/runtime/arc402-cli";
+
+export interface OpenShellConfig {
+  sandbox: { name: string; policy?: string; providers?: string[] };
+  runtime?: {
+    local_tarball?: string;
+    remote_root?: string;
+    synced_at?: string;
+  };
+}
+
+export function runCmd(
+  cmd: string,
+  args: string[],
+  opts: { env?: NodeJS.ProcessEnv; input?: string; timeout?: number } = {}
+): { stdout: string; stderr: string; ok: boolean; status: number | null } {
+  const result = spawnSync(cmd, args, {
+    encoding: "utf-8",
+    env: { ...process.env, ...(opts.env ?? {}) },
+    input: opts.input,
+    timeout: opts.timeout ?? 60000,
+  });
+  return {
+    stdout: (result.stdout ?? "").trim(),
+    stderr: (result.stderr ?? "").trim(),
+    ok: result.status === 0 && !result.error,
+    status: result.status,
+  };
+}
+
+export interface DockerAccessStatus {
+  ok: boolean;
+  detail: string;
+}
+
+export function detectDockerAccess(): DockerAccessStatus {
+  const result = runCmd("docker", ["info", "--format", "{{.ServerVersion}}"], { timeout: 20000 });
+  if (result.ok) {
+    return { ok: true, detail: `running (${result.stdout || "version unknown"})` };
+  }
+
+  const detail = result.stderr || result.stdout || "Docker is unavailable";
+  if (/permission denied/i.test(detail)) {
+    return { ok: false, detail: "installed but this shell cannot access the Docker daemon" };
+  }
+  if (/Cannot connect to the Docker daemon/i.test(detail) || /Is the docker daemon running/i.test(detail)) {
+    return { ok: false, detail: "installed but the Docker daemon is not running" };
+  }
+  if (/command not found/i.test(detail) || result.status === 127) {
+    return { ok: false, detail: "not installed" };
+  }
+  return { ok: false, detail };
+}
+
+export function resolveOpenShellSecrets(): {
+  machineKey?: string;
+  telegramBotToken?: string;
+  telegramChatId?: string;
+} {
+  let machineKey = process.env["ARC402_MACHINE_KEY"];
+  let telegramBotToken = process.env["TELEGRAM_BOT_TOKEN"];
+  let telegramChatId = process.env["TELEGRAM_CHAT_ID"];
+
+  try {
+    const config = loadConfig();
+    if (!machineKey && config.privateKey) machineKey = config.privateKey;
+    if (!telegramBotToken && config.telegramBotToken) telegramBotToken = config.telegramBotToken;
+    if (!telegramChatId && config.telegramChatId) telegramChatId = config.telegramChatId;
+  } catch {
+    // CLI config is optional here; env vars still win when present.
+  }
+
+  return { machineKey, telegramBotToken, telegramChatId };
+}
+
+export function buildOpenShellSecretExports(requireMachineKey = false): string {
+  const secrets = resolveOpenShellSecrets();
+  const exports: string[] = [];
+
+  if (secrets.machineKey) {
+    exports.push(`export ARC402_MACHINE_KEY=${shellEscape(secrets.machineKey)}`);
+  } else if (requireMachineKey) {
+    throw new Error("ARC402 machine key not found in env or arc402 config");
+  }
+
+  if (secrets.telegramBotToken) {
+    exports.push(`export TELEGRAM_BOT_TOKEN=${shellEscape(secrets.telegramBotToken)}`);
+  }
+  if (secrets.telegramChatId) {
+    exports.push(`export TELEGRAM_CHAT_ID=${shellEscape(secrets.telegramChatId)}`);
+  }
+
+  return exports.join(" && ");
+}
+
+export function readOpenShellConfig(): OpenShellConfig | null {
+  if (!fs.existsSync(OPENSHELL_TOML)) return null;
+  try {
+    const raw = fs.readFileSync(OPENSHELL_TOML, "utf-8");
+    const parsed = parseToml(raw) as Record<string, unknown>;
+    const sb = parsed.sandbox as Record<string, unknown> | undefined;
+    if (!sb || typeof sb.name !== "string") return null;
+    const runtime = parsed.runtime as Record<string, unknown> | undefined;
+    return {
+      sandbox: {
+        name: sb.name,
+        policy: typeof sb.policy === "string" ? sb.policy : undefined,
+        providers: Array.isArray(sb.providers) ? (sb.providers as string[]) : undefined,
+      },
+      runtime: runtime ? {
+        local_tarball: typeof runtime.local_tarball === "string" ? runtime.local_tarball : undefined,
+        remote_root: typeof runtime.remote_root === "string" ? runtime.remote_root : undefined,
+        synced_at: typeof runtime.synced_at === "string" ? runtime.synced_at : undefined,
+      } : undefined,
+    };
+  } catch {
+    return null;
+  }
+}
+
+export function writeOpenShellConfig(config: OpenShellConfig): void {
+  fs.mkdirSync(ARC402_DIR, { recursive: true, mode: 0o700 });
+  const providers = (config.sandbox.providers ?? []).map((p) => `"${p}"`).join(", ");
+  const lines = [
+    "# ARC-402 OpenShell configuration",
+    "# Written by: arc402 openshell init / sync-runtime",
+    "",
+    "[sandbox]",
+    `name = "${config.sandbox.name}"`,
+    config.sandbox.policy ? `policy = "${config.sandbox.policy}"` : "",
+    `providers = [${providers}]`,
+    "",
+    "[runtime]",
+    `local_tarball = "${config.runtime?.local_tarball ?? OPENSHELL_RUNTIME_TARBALL}"`,
+    `remote_root = "${config.runtime?.remote_root ?? DEFAULT_RUNTIME_REMOTE_ROOT}"`,
+    `synced_at = "${config.runtime?.synced_at ?? new Date().toISOString()}"`,
+    "",
+  ].filter(Boolean);
+  fs.writeFileSync(OPENSHELL_TOML, lines.join("\n"), { mode: 0o600 });
+}
+
+function findCliRoot(startDir: string): string {
+  let current = startDir;
+  while (true) {
+    const pkg = path.join(current, "package.json");
+    const dist = path.join(current, "dist", "index.js");
+    if (fs.existsSync(pkg) && fs.existsSync(dist)) return current;
+    const parent = path.dirname(current);
+    if (parent === current) throw new Error("Could not locate ARC-402 CLI root from current install path");
+    current = parent;
+  }
+}
+
+export function buildRuntimeTarball(): { cliRoot: string; tarballPath: string } {
+  const cliRoot = findCliRoot(__dirname);
+  fs.mkdirSync(OPENSHELL_RUNTIME_DIR, { recursive: true, mode: 0o700 });
+
+  const tar = runCmd(
+    "tar",
+    [
+      "-czf",
+      OPENSHELL_RUNTIME_TARBALL,
+      "package.json",
+      "package-lock.json",
+      "dist",
+      "node_modules",
+    ],
+    { timeout: 300000, env: process.env }
+  );
+
+  if (!tar.ok) {
+    // Retry from the cli root via shell so relative paths resolve correctly.
+    const shellTar = runCmd(
+      "bash",
+      [
+        "-lc",
+        `cd ${shellEscape(cliRoot)} && tar -czf ${shellEscape(OPENSHELL_RUNTIME_TARBALL)} package.json package-lock.json dist node_modules`,
+      ],
+      { timeout: 300000 }
+    );
+    if (!shellTar.ok) {
+      throw new Error(shellTar.stderr || shellTar.stdout || "Failed to build ARC-402 runtime tarball");
+    }
+  }
+
+  return { cliRoot, tarballPath: OPENSHELL_RUNTIME_TARBALL };
+}
+
+export function buildOpenShellSshConfig(sandboxName: string): { configPath: string; host: string } {
+  const sshConfig = runCmd("openshell", ["sandbox", "ssh-config", sandboxName], { timeout: 120000 });
+  if (!sshConfig.ok || !sshConfig.stdout.trim()) {
+    throw new Error(`Failed to get OpenShell SSH config for sandbox ${sandboxName}: ${sshConfig.stderr || sshConfig.stdout || "unknown error"}`);
+  }
+  const hostMatch = sshConfig.stdout.match(/^Host\s+(\S+)/m);
+  if (!hostMatch) {
+    throw new Error(`Could not parse OpenShell SSH host alias for sandbox ${sandboxName}`);
+  }
+  const configPath = path.join(os.tmpdir(), `arc402-openshell-${sandboxName}.ssh`);
+  fs.writeFileSync(configPath, sshConfig.stdout, { mode: 0o600 });
+  return { configPath, host: hostMatch[1] };
+}
+
+export function provisionFileToSandbox(sandboxName: string, localPath: string, remotePath: string): void {
+  if (!fs.existsSync(localPath)) {
+    throw new Error(`Local file not found: ${localPath}`);
+  }
+
+  const remoteDir = path.posix.dirname(remotePath);
+  const uploadDir = `/tmp/arc402-upload-${Date.now()}`;
+  const { configPath, host } = buildOpenShellSshConfig(sandboxName);
+
+  const prep = runCmd("ssh", ["-F", configPath, host, `rm -rf ${shellEscape(uploadDir)} && mkdir -p ${shellEscape(uploadDir)} && mkdir -p ${shellEscape(remoteDir)}`], { timeout: 120000 });
+  if (!prep.ok) {
+    throw new Error(`Failed to prepare remote upload directory: ${prep.stderr || prep.stdout}`);
+  }
+
+  const upload = runCmd("openshell", ["sandbox", "upload", sandboxName, localPath, uploadDir], { timeout: 300000 });
+  if (!upload.ok) {
+    throw new Error(`Failed to upload ${path.basename(localPath)}: ${upload.stderr || upload.stdout}`);
+  }
+
+  const remoteUploaded = path.posix.join(uploadDir, path.basename(localPath));
+  const move = runCmd("ssh", ["-F", configPath, host, `cp ${shellEscape(remoteUploaded)} ${shellEscape(remotePath)}`], { timeout: 120000 });
+  if (!move.ok) {
+    throw new Error(`Failed to place ${path.basename(localPath)} at ${remotePath}: ${move.stderr || move.stdout}`);
+  }
+}
+
+export function provisionRuntimeToSandbox(
+  sandboxName: string,
+  remoteRoot = DEFAULT_RUNTIME_REMOTE_ROOT,
+): { tarballPath: string; remoteRoot: string } {
+  const { tarballPath } = buildRuntimeTarball();
+  const remoteUploadDir = `/tmp/arc402-runtime-upload-${Date.now()}`;
+  const remoteTarball = `${remoteUploadDir}/arc402-cli-runtime.tgz`;
+  const { configPath, host } = buildOpenShellSshConfig(sandboxName);
+
+  const prep = runCmd("ssh", ["-F", configPath, host, `rm -rf ${shellEscape(remoteUploadDir)} && mkdir -p ${shellEscape(remoteUploadDir)}`], { timeout: 120000 });
+  if (!prep.ok) {
+    throw new Error(`Failed to prepare remote upload directory: ${prep.stderr || prep.stdout}`);
+  }
+
+  const upload = runCmd("openshell", ["sandbox", "upload", sandboxName, tarballPath, remoteUploadDir], { timeout: 300000 });
+  if (!upload.ok) {
+    throw new Error(`Failed to upload ARC-402 runtime bundle: ${upload.stderr || upload.stdout}`);
+  }
+
+  const extract = runCmd(
+    "ssh",
+    [
+      "-F", configPath,
+      host,
+      `mkdir -p ${shellEscape(remoteRoot)} && tar -xzf ${shellEscape(remoteTarball)} -C ${shellEscape(remoteRoot)} && test -f ${shellEscape(path.posix.join(remoteRoot, "dist/daemon/index.js"))}`,
+    ],
+    { timeout: 300000 }
+  );
+  if (!extract.ok) {
+    throw new Error(`Failed to provision ARC-402 runtime inside sandbox: ${extract.stderr || extract.stdout}`);
+  }
+
+  return { tarballPath, remoteRoot };
+}
+
+export function shellEscape(value: string): string {
+  return `'${value.replace(/'/g, `'"'"'`)}'`;
+}