@tpsdev-ai/cli 0.1.0 → 0.2.0

package/dist/src/commands/office.js

@@ -1,17 +1,19 @@
-import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync, openSync, closeSync, copyFileSync } from "node:fs";
-import { join, dirname } from "node:path";
+import { spawnSync } from "node:child_process";
+import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, unlinkSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
-import { spawn, spawnSync } from "node:child_process";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
 import { sanitizeIdentifier } from "../schema/sanitizer.js";
-import { connectAndKeepAlive, startRelay, syncRemoteBranch } from "../utils/relay.js";
 import { connectionAlive, listHostStates } from "../utils/connection-state.js";
-import { sandboxSocketPath, isSandboxReady, waitForSandbox, sandboxExec, loadImageIntoSandbox } from "../utils/sandbox.js";
-import { provisionTeam } from "../utils/provision.js";
-import { fileURLToPath } from "node:url";
-import { fingerprint, loadHostIdentity, lookupBranch, registerBranch, revokeBranch } from "../utils/identity.js";
+import { fingerprint, loadHostIdentity, registerBranch, revokeBranch } from "../utils/identity.js";
 import { NoiseIkTransport } from "../utils/noise-ik-transport.js";
+import { provisionTeam } from "../utils/provision.js";
+import { connectAndKeepAlive, startRelay } from "../utils/relay.js";
+import { isSandboxReady, loadImageIntoSandbox, sandboxExec, sandboxSocketPath, waitForSandbox } from "../utils/sandbox.js";
+import { MSG_JOIN_COMPLETE, MSG_MAIL_DELIVER } from "../utils/wire-mail.js";
 import { WsNoiseTransport } from "../utils/ws-noise-transport.js";
-import { MSG_JOIN_COMPLETE } from "../utils/wire-mail.js";
+import { branchRoot as sharedBranchRoot, resolveTeamId, workspacePath as sharedWorkspacePath } from "../utils/workspace.js";
+import { runOfficeManager, loadWorkspaceManifest } from "./office-manager.js";
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const BOOTSTRAP_TEMPLATE = `#!/bin/bash
 set -e
@@ -51,88 +53,75 @@ nohup openclaw gateway run --config "$CONFIG" > __WORKSPACE__/gateway.log 2>&1 &
 echo "Branch office agent ready (gateway pid $!)"
 `;
 function branchRoot() {
-    return join(process.env.HOME || homedir(), ".tps", "branch-office");
+    return sharedBranchRoot();
+}
+function workspacePath(agentId) {
+    return sharedWorkspacePath(agentId);
+}
+function sandboxName(agentId) {
+    const teamId = resolveTeamId(agentId);
+    return `tps-${teamId}`;
+}
+function relayPidFile(agentId) {
+    return join(workspacePath(agentId), "relay.pid");
+}
+function outboxCounts(agentId) {
+    const ws = workspacePath(agentId);
+    const root = join(ws, "mail", "outbox");
+    const countDir = (dir) => existsSync(dir) ? readdirSync(dir).filter(f => f.endsWith(".json")).length : 0;
+    return {
+        newCount: countDir(join(root, "new")),
+        curCount: countDir(join(root, "cur")),
+        failedCount: countDir(join(root, "failed")),
+    };
 }
 function validateAgent(agent) {
     if (!agent) {
-        console.error("Agent is required.");
+        console.error("Agent name is required.");
         process.exit(1);
     }
     const safe = sanitizeIdentifier(agent);
     if (safe !== agent) {
-        console.error(`Invalid agent id: ${agent}`);
+        console.error(`Invalid agent identifier: ${agent}`);
         process.exit(1);
     }
     return agent;
 }
-export function parseJoinToken(token) {
-    let u;
-    try {
-        u = new URL(token);
-    }
-    catch {
-        throw new Error("Invalid join token URL");
-    }
-    if (u.protocol !== "tps:")
-        throw new Error("Join token must use tps:// scheme");
-    const host = u.searchParams.get("host") || "";
-    const portRaw = u.searchParams.get("port") || "";
-    const transportRaw = u.searchParams.get("transport") || "ws";
-    const pubkeyRaw = u.searchParams.get("pubkey") || "";
-    const sigRaw = u.searchParams.get("sigpubkey") || "";
-    const fp = u.searchParams.get("fp") || "";
-    if (!host)
-        throw new Error("Join token missing host");
-    const transport = transportRaw === "tcp" ? "tcp" : "ws";
-    const port = Number(portRaw);
-    if (!Number.isFinite(port) || port <= 0 || port > 65535) {
-        throw new Error("Join token has invalid port");
-    }
-    if (!pubkeyRaw)
-        throw new Error("Join token missing pubkey");
-    if (!sigRaw)
-        throw new Error("Join token missing sigpubkey");
-    if (!fp)
-        throw new Error("Join token missing fingerprint");
-    let encryptionPubkey;
-    let signingPubkey;
+function resolveSandboxId(agentId) {
+    const result = spawnSync("nono", ["list", "--json"], { encoding: "utf8" });
+    if (result.status !== 0)
+        return null;
     try {
-        encryptionPubkey = new Uint8Array(Buffer.from(pubkeyRaw, "base64url"));
-        signingPubkey = new Uint8Array(Buffer.from(sigRaw, "base64url"));
+        const states = JSON.parse(result.stdout);
+        const target = sandboxName(agentId);
+        const found = states.find((s) => s.name === target);
+        return found ? found.id : null;
     }
     catch {
-        throw new Error("Join token contains invalid key encoding");
-    }
-    if (encryptionPubkey.length !== 32)
-        throw new Error("Join token encryption pubkey must be 32 bytes");
-    if (signingPubkey.length !== 32)
-        throw new Error("Join token signing pubkey must be 32 bytes");
-    const normalizedFp = fp.startsWith("sha256:") ? fp : `sha256:${fp}`;
-    const expected = `sha256:${fingerprint(signingPubkey)}`;
-    if (expected !== normalizedFp) {
-        throw new Error("Join token fingerprint does not match signing key");
+        return null;
     }
-    return { host, port, transport, encryptionPubkey, signingPubkey, fingerprint: normalizedFp };
-}
-function workspacePath(agent) {
-    return join(branchRoot(), agent);
 }
-function sandboxName(agent) {
-    return `tps-${agent}`;
-}
-function sandboxAgent() {
-    const raw = process.env.TPS_SANDBOX_AGENT || "claude";
-    const safe = sanitizeIdentifier(raw);
-    if (safe !== raw) {
-        throw new Error(`Invalid sandbox agent: ${raw}`);
+export function parseJoinToken(tokenUrl) {
+    const url = new URL(tokenUrl);
+    if (url.protocol !== "tps:" || url.host !== "join") {
+        throw new Error("Invalid join token protocol. Must be tps://join?...");
     }
-    return raw;
-}
-function idFile(agent) {
-    return join(workspacePath(agent), "sandbox.id");
-}
-function relayPidFile(agent) {
-    return join(workspacePath(agent), "relay.pid");
+    const host = url.searchParams.get("host");
+    const port = Number(url.searchParams.get("port"));
+    const pubkey = url.searchParams.get("pubkey");
+    const sigpubkey = url.searchParams.get("sigpubkey");
+    const fp = url.searchParams.get("fp");
+    if (!host || isNaN(port) || !pubkey || !sigpubkey || !fp) {
+        throw new Error("Invalid join token: missing required parameters");
+    }
+    return {
+        host,
+        port,
+        transport: url.searchParams.get("transport") || "ws",
+        encryptionPubkey: new Uint8Array(Buffer.from(pubkey, "base64url")),
+        signingPubkey: new Uint8Array(Buffer.from(sigpubkey, "base64url")),
+        fingerprint: fp,
+    };
 }
 function setupWorkspace(agent) {
     const ws = workspacePath(agent);
@@ -143,11 +132,11 @@ function setupWorkspace(agent) {
     mkdirSync(join(ws, "mail", "outbox", "failed"), { recursive: true });
     mkdirSync(join(ws, "mail", "outbox", "paused"), { recursive: true });
     const bootstrap = join(ws, "bootstrap.sh");
-    // Security: never source bootstrap from process.cwd().
-    // Use the trusted in-code template to avoid cwd injection.
-    // ops-15.5: Don't overwrite existing bootstrap.sh if user customized it.
     if (!existsSync(bootstrap)) {
-        const template = BOOTSTRAP_TEMPLATE.replaceAll("__WORKSPACE__", ws);
+        const teamRoot = join(branchRoot(), agent);
+        const template = BOOTSTRAP_TEMPLATE
+            .replaceAll("__WORKSPACE__", ws)
+            .replaceAll("__TEAM_ROOT__", teamRoot);
         writeFileSync(bootstrap, template, { mode: 0o755 });
     }
     else {
@@ -155,336 +144,108 @@ function setupWorkspace(agent) {
     }
     return ws;
 }
-function resolveSandboxId(agent) {
-    const sid = idFile(agent);
-    if (existsSync(sid)) {
-        return readFileSync(sid, "utf-8").trim();
-    }
-    const listed = spawnSync("docker", ["sandbox", "ls", "--json"], { encoding: "utf-8" });
-    if (listed.status !== 0)
-        return null;
-    try {
-        const parsed = JSON.parse(listed.stdout || "{}");
-        const rows = parsed.vms || [];
-        const expected = sandboxName(agent).toLowerCase();
-        const match = rows.find((r) => (r.name || "").toLowerCase() === expected);
-        if (!match)
-            return null;
-        return (match.name || match.id || match.sandboxId || null);
-    }
-    catch {
-        return null;
-    }
-}
-function relayLogFile(agent) {
-    return join(workspacePath(agent), "relay.log");
-}
-function startRelayProcess(agent) {
-    const pidFile = relayPidFile(agent);
-    if (existsSync(pidFile)) {
-        const pid = Number(readFileSync(pidFile, "utf-8").trim());
-        try {
-            // Check if process exists (signal 0)
-            process.kill(pid, 0);
-            console.log(`Relay already running (pid ${pid})`);
-            return;
-        }
-        catch {
-            // Process dead, proceed to spawn new one
-        }
-    }
-    const logPath = relayLogFile(agent);
-    const logFd = openSync(logPath, "a");
-    const child = spawn(process.execPath, [process.argv[1], "office", "relay", agent], {
-        detached: true,
-        stdio: ["ignore", logFd, logFd],
-        env: { ...process.env },
-    });
-    child.unref();
-    // Close the fd in the parent so we don't hold it open (child has it now)
-    // Wait, spawn with detached doesn't automatically close fds in parent?
-    // Actually, passing fd to stdio options duplicates it to child. Parent can close.
-    // But we need to be careful not to close it before spawn uses it? Spawn is synchronous in setup.
-    // Node docs say: "The file descriptor is duplicated in the child process."
-    // Safe to close in parent after spawn returns.
-    try {
-        closeSync(logFd);
-    }
-    catch { }
-    writeFileSync(relayPidFile(agent), `${child.pid}\n`, "utf-8");
-}
-function stopRelayProcess(agent) {
-    const pf = relayPidFile(agent);
-    if (!existsSync(pf))
-        return;
-    const pid = Number(readFileSync(pf, "utf-8").trim());
-    if (pid > 0) {
-        try {
-            process.kill(pid, "SIGTERM");
-        }
-        catch {
-            // already stopped
-        }
-    }
-}
-function outboxCounts(agent) {
-    const ws = workspacePath(agent);
-    const outNew = join(ws, "mail", "outbox", "new");
-    const outCur = join(ws, "mail", "outbox", "cur");
-    const outFailed = join(ws, "mail", "outbox", "failed");
-    const newCount = existsSync(outNew) ? readdirSync(outNew).filter((f) => f.endsWith(".json")).length : 0;
-    const curCount = existsSync(outCur) ? readdirSync(outCur).filter((f) => f.endsWith(".json")).length : 0;
-    const failedCount = existsSync(outFailed) ? readdirSync(outFailed).filter((f) => f.endsWith(".json")).length : 0;
-    return { newCount, curCount, failedCount };
-}
 export async function runOffice(args) {
     switch (args.action) {
-        case "join": {
-            const agent = validateAgent(args.agent);
-            if (!args.joinToken) {
-                console.error("Usage: tps office join <name> <join-token-url>");
-                process.exit(1);
-            }
-            const token = parseJoinToken(args.joinToken);
-            const existing = lookupBranch(agent);
-            if (existing) {
-                console.error(`Branch '${agent}' is already registered. Revoke first or use a different name.`);
-                process.exit(1);
-            }
-            registerBranch(agent, token.signingPubkey, {
-                fingerprint: `sha256:${fingerprint(token.signingPubkey)}`,
-                trust: "standard",
-            }, token.encryptionPubkey);
-            console.log(`Connecting to ${token.host}:${token.port}...`);
-            const hostKp = loadHostIdentity();
-            const wire = token.transport === "ws" ? new WsNoiseTransport(hostKp) : new NoiseIkTransport(hostKp);
-            const channel = await wire.connect({
-                host: token.host,
-                port: token.port,
-                branchId: agent,
-                hostPublicKey: token.encryptionPubkey,
-            });
-            console.log(`Noise_IK handshake OK — branch fingerprint verified: ${token.fingerprint}`);
-            await channel.send({
-                type: MSG_JOIN_COMPLETE,
-                seq: 0,
-                ts: new Date().toISOString(),
-                body: {
-                    hostPubkey: Buffer.from(hostKp.encryption.publicKey).toString("base64url"),
-                    hostFingerprint: fingerprint(hostKp.encryption.publicKey),
-                    hostId: process.env.TPS_HOST_ID || "host",
-                },
-            });
-            const ws = workspacePath(agent);
-            mkdirSync(ws, { recursive: true });
-            const remoteRecord = {
-                host: token.host,
-                port: token.port,
-                branchId: agent,
-                fingerprint: token.fingerprint,
-                pubkey: Buffer.from(token.encryptionPubkey).toString("base64url"),
-                joinedAt: new Date().toISOString(),
-                transport: token.transport,
-            };
-            writeFileSync(join(ws, "remote.json"), JSON.stringify(remoteRecord, null, 2), "utf-8");
-            await channel.close();
-            console.log(`Branch '${agent}' registered.`);
-            console.log("Host pubkey sent to branch.");
-            console.log("Remote branch office ready.");
-            return;
-        }
         case "start": {
-            const agent = validateAgent(args.agent);
-            // ops-17: Check for manifest mode (team provisioning)
             if (args.manifest) {
                 try {
                     provisionTeam(args.manifest, branchRoot());
-                    console.log(`Team '${agent}' provisioned from manifest.`);
+                    if (args.soundstage && args.agent) {
+                        const team = validateAgent(args.agent);
+                        const teamRoot = join(branchRoot(), team);
+                        const ws = join(teamRoot, "workspace");
+                        const marker = join(teamRoot, "soundstage.json");
+                        mkdirSync(teamRoot, { recursive: true });
+                        writeFileSync(marker, JSON.stringify({ enabled: true, startedAt: new Date().toISOString() }));
+                        const teamBootstrap = join(teamRoot, "bootstrap.sh");
+                        let bs = BOOTSTRAP_TEMPLATE
+                            .replaceAll("__WORKSPACE__", ws)
+                            .replaceAll("__TEAM_ROOT__", teamRoot);
+                        const workspaceBootstrap = join(ws, "bootstrap.sh");
+                        if (existsSync(workspaceBootstrap)) {
+                            bs = readFileSync(workspaceBootstrap, "utf-8").replaceAll("__TEAM_ROOT__", teamRoot);
+                        }
+                        writeFileSync(teamBootstrap, bs, { mode: 0o755 });
+                    }
+                    console.log(`Team provisioned from manifest.`);
                 }
                 catch (e) {
                     console.error(`Failed to provision team: ${e.message}`);
                     process.exit(1);
                 }
+                return;
             }
+            const agent = validateAgent(args.agent);
+            const sName = sandboxName(agent);
             const ws = setupWorkspace(agent);
             if (args.soundstage) {
-                // Write soundstage marker OUTSIDE workspace mount (agents can't detect it)
+                console.log("🎬 Soundstage mode enabled (Mock LLM, local isolation)");
                 const teamRoot = join(branchRoot(), agent);
-                const marker = {
-                    mode: "soundstage",
-                    createdAt: new Date().toISOString(),
-                    agent,
-                    manifest: args.manifest || null,
-                    mockLlmPort: 11434,
-                };
-                // Use teamRoot instead of ws to place outside workspace
-                writeFileSync(join(teamRoot, "soundstage.json"), JSON.stringify(marker, null, 2), "utf-8");
-                // Rewrite openclaw.json to point at mock LLM
-                const configPath = join(ws, ".openclaw", "openclaw.json");
-                if (existsSync(configPath)) {
-                    const config = JSON.parse(readFileSync(configPath, "utf-8"));
-                    if (config.agents?.defaults?.model) {
-                        config.agents.defaults.model.primary = "openai-compatible/mock-soundstage";
-                        config.agents.defaults.model.fallbacks = [];
-                    }
-                    // Add base URL for the mock
-                    config.agents = config.agents || {};
-                    config.agents.defaults = config.agents.defaults || {};
-                    config.agents.defaults.baseUrl = "http://127.0.0.1:11434/v1";
-                    writeFileSync(configPath, JSON.stringify(config, null, 2), "utf-8");
-                }
-                // Copy mock LLM server into team root (NOT workspace — agents can't modify it)
-                const mockSrc = join(__dirname, "..", "soundstage", "mock-llm.js");
-                const mockDst = join(teamRoot, "mock-llm.js");
-                if (!existsSync(mockSrc)) {
-                    throw new Error("Soundstage mock LLM not found. Run `bun run build` first.");
-                }
-                copyFileSync(mockSrc, mockDst);
-                // Substitute __TEAM_ROOT__ in bootstrap (setupWorkspace only handles __WORKSPACE__)
-                const bootstrapPath = join(ws, "bootstrap.sh");
-                if (existsSync(bootstrapPath)) {
-                    const bs = readFileSync(bootstrapPath, "utf-8").replaceAll("__TEAM_ROOT__", teamRoot);
-                    writeFileSync(bootstrapPath, bs, { mode: 0o755 });
+                const marker = join(teamRoot, "soundstage.json");
+                mkdirSync(teamRoot, { recursive: true });
+                writeFileSync(marker, JSON.stringify({ enabled: true, startedAt: new Date().toISOString() }));
+                const soundstageImage = join(__dirname, "..", "..", "images", "tps-soundstage.tar");
+                if (existsSync(soundstageImage)) {
+                    console.log(`Loading soundstage image: ${soundstageImage}`);
+                    loadImageIntoSandbox(sName, soundstageImage);
                 }
-            }
-            const sName = sandboxName(agent);
-            const skipVm = process.env.TPS_OFFICE_SKIP_VM === "1";
-            if (!skipVm) {
-                // Idempotency: check if sandbox already exists
-                const existingId = resolveSandboxId(agent);
-                if (!existingId) {
-                    const sAgent = sandboxAgent();
-                    console.log(`Creating sandbox ${sName}...`);
-                    // docker sandbox create hangs indefinitely (v0.11.0 bug) even after
-                    // the VM is ready. Spawn it in the background and wait for the socket.
-                    const createLog = join(ws, "create.log");
-                    const createLogFd = openSync(createLog, "a");
-                    const createArgs = ["sandbox", "create", "--name", sName];
-                    // Soundstage uses a pre-built image with openclaw already installed
-                    if (args.soundstage) {
-                        createArgs.push("--template", "tps-soundstage:latest");
-                    }
-                    createArgs.push(sAgent, ws);
-                    const createChild = spawn("docker", createArgs, {
-                        detached: true,
-                        stdio: ["ignore", createLogFd, createLogFd],
-                    });
-                    createChild.unref();
-                    try {
-                        closeSync(createLogFd);
-                    }
-                    catch { }
-                    // Wait for VM socket to appear (the create command keeps running but VM is ready)
-                    console.log("Waiting for sandbox VM to boot...");
-                    if (!waitForSandbox(sName, 90000)) {
-                        // Check if sandbox appeared in ls even if socket isn't ready
-                        const check = spawnSync("docker", ["sandbox", "ls", "--json"], { encoding: "utf-8" });
-                        const vms = JSON.parse(check.stdout || "{}").vms || [];
-                        const found = vms.find((v) => v.name === sName);
-                        if (!found) {
-                            console.error(`Sandbox creation failed. Check ${createLog}`);
-                            process.exit(1);
-                        }
-                        // VM exists but socket not ready — wait longer
-                        console.log("VM created, waiting for daemon...");
-                        if (!waitForSandbox(sName, 30000)) {
-                            console.error("Sandbox VM daemon did not become ready.");
-                            process.exit(1);
-                        }
-                    }
-                    console.log("Sandbox VM ready.");
+                const bootstrap = join(ws, "bootstrap.sh");
+                if (existsSync(bootstrap)) {
+                    const bs = readFileSync(bootstrap, "utf-8").replaceAll("__TEAM_ROOT__", teamRoot);
+                    writeFileSync(bootstrap, bs, { mode: 0o755 });
                 }
             }
-            const id = sName;
-            writeFileSync(idFile(agent), `${id}\n`, "utf-8");
-            const sock = sandboxSocketPath(id);
-            if (!skipVm) {
-                // Ensure VM is ready (may already be if we just created it above)
-                if (!isSandboxReady(id)) {
-                    console.log("Waiting for sandbox VM...");
-                    if (!waitForSandbox(id, 60000)) {
-                        console.error("Sandbox VM did not become ready in 60s.");
-                        process.exit(1);
-                    }
-                }
-                // Load base image for bootstrap execution
-                console.log("Loading base image into sandbox...");
-                if (!loadImageIntoSandbox(id, "node:22-alpine")) {
-                    if (!loadImageIntoSandbox(id, "alpine:latest")) {
-                        console.error("Failed to load base image into sandbox VM.");
-                        process.exit(1);
-                    }
-                }
-                // Execute bootstrap via direct socket (workaround for docker sandbox exec bug)
-                console.log("Running bootstrap...");
-                const exec = sandboxExec(id, ["sh", join(ws, "bootstrap.sh")], {
-                    workspace: ws,
-                    image: "node:22-alpine",
-                });
-                if (exec.status !== 0) {
-                    const fallback = sandboxExec(id, ["sh", join(ws, "bootstrap.sh")], {
-                        workspace: ws,
-                        image: "alpine:latest",
-                    });
-                    if (fallback.status !== 0) {
-                        console.error(fallback.stderr || fallback.stdout || "Bootstrap failed.");
-                        process.exit(1);
-                    }
-                }
+            const teamId = resolveTeamId(agent);
+            const isTeam = teamId !== agent;
+            if (isTeam) {
+                console.log(`(Shared team sandbox: ${teamId})`);
             }
-            if (process.env.TPS_OFFICE_SKIP_RELAY !== "1") {
-                startRelayProcess(agent);
+            if (process.env.TPS_OFFICE_SKIP_VM === "1") {
+                console.log(`✓ Sandbox ready for ${agent} (SKIPPED).`);
+                return;
             }
-            console.log(`Sandbox started for ${agent}`);
-            console.log(`ID: ${id}`);
-            console.log(`Socket: ${sock}`);
-            console.log(`Workspace: ${ws}`);
-            return;
-        }
-        case "stop": {
-            const agent = validateAgent(args.agent);
-            stopRelayProcess(agent);
-            const id = resolveSandboxId(agent);
-            if (!id) {
-                console.error(`No sandbox found for agent: ${agent}`);
+            console.log(`Starting sandbox VM for ${agent}...`);
+            spawnSync("nono", ["start", sName, "--mount", `${ws}:/workspace`, "--image", "node:22-alpine"], { stdio: "inherit" });
+            if (!waitForSandbox(sName)) {
+                console.error("Timed out waiting for sandbox to be ready.");
                 process.exit(1);
             }
-            const stop = spawnSync("docker", ["sandbox", "stop", id], { encoding: "utf-8" });
-            if (stop.status !== 0) {
-                console.error(stop.stderr || stop.stdout || `Failed to stop sandbox ${id}.`);
-                process.exit(1);
+            console.log(`✓ Sandbox ready for ${agent}.`);
+            // Auto-run Office Manager if a workspace manifest exists
+            if (loadWorkspaceManifest(ws)) {
+                console.log("Workspace manifest found — running Office Manager...");
+                await runOfficeManager(ws, { dryRun: false });
             }
-            console.log(`Stopped sandbox ${id} (${agent})`);
             return;
         }
-        case "revoke": {
+        case "setup": {
             const agent = validateAgent(args.agent);
-            const existing = lookupBranch(agent);
-            if (!existing) {
-                console.error(`Branch '${agent}' not found in registry.`);
+            const ws = workspacePath(agent);
+            const ok = await runOfficeManager(ws, { dryRun: args.dryRun ?? false });
+            if (!ok)
                 process.exit(1);
-            }
-            revokeBranch(agent, "manual revocation");
-            console.log(`Branch '${agent}' revoked. Run 'tps branch init' on the remote to re-join.`);
-            return;
-        }
-        case "sync": {
-            const agent = validateAgent(args.agent);
-            const result = await syncRemoteBranch(agent);
-            console.log(`Sync complete. Received ${result.received} message(s) from ${agent}.`);
             return;
         }
-        case "connect": {
+        case "stop": {
             const agent = validateAgent(args.agent);
-            console.log(`Connecting to ${agent}... (Ctrl-C to stop)`);
-            const cleanup = await connectAndKeepAlive(agent);
-            const shutdown = async () => {
-                await cleanup();
-                process.exit(0);
-            };
-            process.on("SIGTERM", shutdown);
-            process.on("SIGINT", shutdown);
-            await new Promise(() => { });
+            const sName = sandboxName(agent);
+            const soundstageMarker = join(branchRoot(), agent, "soundstage.json");
+            if (existsSync(soundstageMarker)) {
+                try {
+                    unlinkSync(soundstageMarker);
+                }
+                catch { }
+            }
+            const sid = resolveSandboxId(agent);
+            if (!sid) {
+                process.stderr.write("No sandbox found for agent\n");
+                process.exit(1);
+            }
+            console.log(`Stopping sandbox VM for ${agent}...`);
+            const stopResult = spawnSync("nono", ["stop", sName], { stdio: "inherit" });
+            if (stopResult.status !== 0) {
+                process.exit(stopResult.status ?? 1);
+            }
             return;
         }
         case "list": {
@@ -535,16 +296,12 @@ export async function runOffice(args) {
             console.log(`Workspace: ${ws}`);
             if (isSoundstage) {
                 console.log(`Mode: 🎬 soundstage (mock LLM, real sandbox)`);
-                console.log(`Sandbox: ${sid || "not running"}${vmReady ? " (VM ready)" : ""}`);
-            }
-            else {
-                console.log(`Sandbox: ${sid || "not running"}${vmReady ? " (VM ready)" : ""}`);
             }
+            console.log(`Sandbox: ${sid || "not running"}${vmReady ? " (VM ready)" : ""}`);
             if (sid)
                 console.log(`Socket: ${sandboxSocketPath(sName2)}`);
             console.log(`Relay: ${relayRunning ? "running" : "stopped"}`);
             console.log(`Outbox pending: ${counts.newCount} (cur=${counts.curCount}, failed=${counts.failedCount})`);
-            // Check for paused messages (loop detection)
             const pausedDir = join(ws, "mail", "outbox", "paused");
             if (existsSync(pausedDir)) {
                 const pausedCount = readdirSync(pausedDir).filter((f) => f.endsWith(".json")).length;
@@ -566,7 +323,6 @@ export async function runOffice(args) {
                 stop();
                 process.exit(0);
             });
-            // keep process alive
             setInterval(() => { }, 60_000);
             return;
         }
@@ -592,6 +348,132 @@ export async function runOffice(args) {
             if (result.stderr)
                 process.stderr.write(result.stderr);
             process.exit(result.status ?? 1);
+            return;
+        }
+        case "join": {
+            if (!args.agent || !args.joinToken) {
+                console.error("Usage: tps office join <name> <join-token>");
+                process.exit(1);
+            }
+            const agent = validateAgent(args.agent);
+            const token = parseJoinToken(args.joinToken);
+            registerBranch(agent, token.signingPubkey, {
+                fingerprint: `sha256:${fingerprint(token.signingPubkey)}`,
+                trust: "standard",
+            }, token.encryptionPubkey);
+            console.log(`Connecting to ${token.host}:${token.port}...`);
+            const hostKp = await loadHostIdentity();
+            const wire = token.transport === "ws" ? new WsNoiseTransport(hostKp) : new NoiseIkTransport(hostKp);
+            const channel = await wire.connect({
+                host: token.host,
+                port: token.port,
+                branchId: agent,
+                hostPublicKey: token.encryptionPubkey,
+            });
+            console.log(`Noise_IK handshake OK — branch fingerprint verified: ${token.fingerprint}`);
+            await channel.send({
+                type: MSG_JOIN_COMPLETE,
+                seq: 0,
+                ts: new Date().toISOString(),
+                body: {
+                    hostPubkey: Buffer.from(hostKp.encryption.publicKey).toString("base64url"),
+                    hostFingerprint: fingerprint(hostKp.encryption.publicKey),
+                    hostId: process.env.TPS_HOST_ID || "host",
+                },
+            });
+            const ws = workspacePath(agent);
+            mkdirSync(ws, { recursive: true });
+            const remoteRecord = {
+                host: token.host,
+                port: token.port,
+                branchId: agent,
+                fingerprint: token.fingerprint,
+                pubkey: Buffer.from(token.encryptionPubkey).toString("base64url"),
+                joinedAt: new Date().toISOString(),
+                transport: token.transport,
+            };
+            writeFileSync(join(ws, "remote.json"), JSON.stringify(remoteRecord, null, 2), "utf-8");
+            await channel.close();
+            console.log(`Branch '${agent}' registered.`);
+            console.log("Host pubkey sent to branch.");
+            return;
+        }
+        case "revoke": {
+            const agent = validateAgent(args.agent);
+            revokeBranch(agent, "manual revocation");
+            const ws = workspacePath(agent);
+            const rPath = join(ws, "remote.json");
+            if (existsSync(rPath)) {
+                try {
+                    unlinkSync(rPath);
+                }
+                catch { }
+            }
+            console.log(`Branch '${agent}' revoked.`);
+            return;
+        }
+        case "sync": {
+            if (!args.agent) {
+                console.error("Usage: tps office sync <name>");
+                process.exit(1);
+            }
+            const { syncRemoteBranch: syncRemote } = await import("../utils/relay.js");
+            const { received } = await syncRemote(args.agent);
+            console.log(`Sync complete. Received ${received} message(s).`);
+            return;
+        }
+        case "connect": {
+            if (!args.agent) {
+                console.error("Usage: tps office connect <name>");
+                process.exit(1);
+            }
+            const hostKp = await loadHostIdentity();
+            const stop = await connectAndKeepAlive(args.agent, {
+                onMessage: (msg) => {
+                    if (msg.type === MSG_MAIL_DELIVER) {
+                        console.log(`\n[${new Date().toLocaleTimeString()}] ✉️ Mail received`);
+                    }
+                }
+            });
+            console.log(`Persistent connection active for '${args.agent}'. Press Ctrl+C to disconnect.`);
+            process.on("SIGINT", async () => {
+                await stop();
+                process.exit(0);
+            });
+            setInterval(() => { }, 60_000);
+            return;
+        }
+        case "kill": {
+            let killed = 0;
+            const { listHostStates, clearHostState } = await import("../utils/connection-state.js");
+            const states = listHostStates();
+            for (const s of states) {
+                try {
+                    process.kill(s.pid, "SIGTERM");
+                    clearHostState(s.branch);
+                    killed++;
+                }
+                catch {
+                    clearHostState(s.branch);
+                }
+            }
+            const pidPath = join(process.env.HOME || homedir(), ".tps", "branch", "branch.pid");
+            if (existsSync(pidPath)) {
+                try {
+                    const pid = Number(readFileSync(pidPath, "utf-8").trim());
+                    if (pid) {
+                        process.kill(pid, "SIGTERM");
+                        killed++;
+                    }
+                }
+                catch { }
+                try {
+                    rmSync(pidPath, { force: true });
+                }
+                catch { }
+            }
+            console.log(`Kill switch engaged. Terminated ${killed} TPS process(es).`);
+            break;
         }
     }
 }