svamp-cli 0.1.68 → 0.1.70

package/dist/cli.mjs

@@ -1,4 +1,4 @@
-import { b as stopDaemon, s as startDaemon, d as daemonStatus } from './run-DWFTrXVF.mjs';
+import { b as stopDaemon, s as startDaemon, d as daemonStatus } from './run-C7CEDmD4.mjs';
 import 'os';
 import 'fs/promises';
 import 'fs';
@@ -109,7 +109,7 @@ async function main() {
     const { handleServiceCommand } = await import('./commands-CF32XIau.mjs');
     await handleServiceCommand();
   } else if (subcommand === "process" || subcommand === "proc") {
-    const { processCommand } = await import('./commands-BwT-PFl4.mjs');
+    const { processCommand } = await import('./commands-CIgrbviM.mjs');
     let machineId;
     const processArgs = args.slice(1);
     const mIdx = processArgs.findIndex((a) => a === "--machine" || a === "-m");
@@ -127,7 +127,7 @@ async function main() {
   } else if (!subcommand || subcommand === "start") {
     await handleInteractiveCommand();
   } else if (subcommand === "--version" || subcommand === "-v") {
-    const pkg = await import('./package-CHfluhvW.mjs').catch(() => ({ default: { version: "unknown" } }));
+    const pkg = await import('./package-B0d2rUXI.mjs').catch(() => ({ default: { version: "unknown" } }));
     console.log(`svamp version: ${pkg.default.version}`);
   } else {
     console.error(`Unknown command: ${subcommand}`);
@@ -136,7 +136,7 @@ async function main() {
   }
 }
 async function handleInteractiveCommand() {
-  const { runInteractive } = await import('./run-BYtrsPjt.mjs');
+  const { runInteractive } = await import('./run-CgSj6KtU.mjs');
   const interactiveArgs = subcommand === "start" ? args.slice(1) : args;
   let directory = process.cwd();
   let resumeSessionId;
@@ -181,7 +181,7 @@ async function handleAgentCommand() {
     return;
   }
   if (agentArgs[0] === "list") {
-    const { KNOWN_ACP_AGENTS, KNOWN_MCP_AGENTS: KNOWN_MCP_AGENTS2 } = await import('./run-DWFTrXVF.mjs').then(function (n) { return n.i; });
+    const { KNOWN_ACP_AGENTS, KNOWN_MCP_AGENTS: KNOWN_MCP_AGENTS2 } = await import('./run-C7CEDmD4.mjs').then(function (n) { return n.i; });
     console.log("Known agents:");
     for (const [name, config2] of Object.entries(KNOWN_ACP_AGENTS)) {
       console.log(`  ${name.padEnd(12)} ${config2.command} ${config2.args.join(" ")}  (ACP)`);
@@ -193,7 +193,7 @@ async function handleAgentCommand() {
     console.log('Use "svamp agent -- <command> [args]" for a custom ACP agent.');
     return;
   }
-  const { resolveAcpAgentConfig, KNOWN_MCP_AGENTS } = await import('./run-DWFTrXVF.mjs').then(function (n) { return n.i; });
+  const { resolveAcpAgentConfig, KNOWN_MCP_AGENTS } = await import('./run-C7CEDmD4.mjs').then(function (n) { return n.i; });
   let cwd = process.cwd();
   const filteredArgs = [];
   for (let i = 0; i < agentArgs.length; i++) {
@@ -217,12 +217,12 @@ async function handleAgentCommand() {
   console.log(`Starting ${config.agentName} agent in ${cwd}...`);
   let backend;
   if (KNOWN_MCP_AGENTS[config.agentName]) {
-    const { CodexMcpBackend } = await import('./run-DWFTrXVF.mjs').then(function (n) { return n.j; });
+    const { CodexMcpBackend } = await import('./run-C7CEDmD4.mjs').then(function (n) { return n.j; });
     backend = new CodexMcpBackend({ cwd, log: logFn });
   } else {
-    const { AcpBackend } = await import('./run-DWFTrXVF.mjs').then(function (n) { return n.h; });
-    const { GeminiTransport } = await import('./run-DWFTrXVF.mjs').then(function (n) { return n.G; });
-    const { DefaultTransport } = await import('./run-DWFTrXVF.mjs').then(function (n) { return n.D; });
+    const { AcpBackend } = await import('./run-C7CEDmD4.mjs').then(function (n) { return n.h; });
+    const { GeminiTransport } = await import('./run-C7CEDmD4.mjs').then(function (n) { return n.G; });
+    const { DefaultTransport } = await import('./run-C7CEDmD4.mjs').then(function (n) { return n.D; });
     const transportHandler = config.agentName === "gemini" ? new GeminiTransport() : new DefaultTransport(config.agentName);
     backend = new AcpBackend({
       agentName: config.agentName,
@@ -340,7 +340,7 @@ async function handleSessionCommand() {
     printSessionHelp();
     return;
   }
-  const { sessionList, sessionSpawn, sessionStop, sessionInfo, sessionMessages, sessionAttach, sessionMachines, sessionSend, sessionWait, sessionShare, sessionRalphStart, sessionRalphCancel, sessionRalphStatus, sessionQueueAdd, sessionQueueList, sessionQueueClear } = await import('./commands-D4_QgXrS.mjs');
+  const { sessionList, sessionSpawn, sessionStop, sessionInfo, sessionMessages, sessionAttach, sessionMachines, sessionSend, sessionWait, sessionShare, sessionRalphStart, sessionRalphCancel, sessionRalphStatus, sessionQueueAdd, sessionQueueList, sessionQueueClear } = await import('./commands-BodoXVL9.mjs');
   const parseFlagStr = (flag, shortFlag) => {
     for (let i = 1; i < sessionArgs.length; i++) {
       if ((sessionArgs[i] === flag || shortFlag) && i + 1 < sessionArgs.length) {
@@ -400,7 +400,7 @@ async function handleSessionCommand() {
         allowDomain.push(sessionArgs[++i]);
       }
     }
-    const { parseShareArg } = await import('./commands-D4_QgXrS.mjs');
+    const { parseShareArg } = await import('./commands-BodoXVL9.mjs');
     const shareEntries = share.map((s) => parseShareArg(s));
     await sessionSpawn(agent, dir, targetMachineId, {
       message,
@@ -484,7 +484,7 @@ async function handleSessionCommand() {
       console.error("Usage: svamp session approve <session-id> [request-id] [--json]");
       process.exit(1);
     }
-    const { sessionApprove } = await import('./commands-D4_QgXrS.mjs');
+    const { sessionApprove } = await import('./commands-BodoXVL9.mjs');
     const approveReqId = sessionArgs[2] && !sessionArgs[2].startsWith("--") ? sessionArgs[2] : void 0;
     await sessionApprove(sessionArgs[1], approveReqId, targetMachineId, {
       json: hasFlag("--json")
@@ -494,7 +494,7 @@ async function handleSessionCommand() {
       console.error("Usage: svamp session deny <session-id> [request-id] [--json]");
       process.exit(1);
     }
-    const { sessionDeny } = await import('./commands-D4_QgXrS.mjs');
+    const { sessionDeny } = await import('./commands-BodoXVL9.mjs');
     const denyReqId = sessionArgs[2] && !sessionArgs[2].startsWith("--") ? sessionArgs[2] : void 0;
     await sessionDeny(sessionArgs[1], denyReqId, targetMachineId, {
       json: hasFlag("--json")
@@ -597,7 +597,7 @@ async function handleMachineCommand() {
     return;
   }
   if (machineSubcommand === "share") {
-    const { machineShare } = await import('./commands-D4_QgXrS.mjs');
+    const { machineShare } = await import('./commands-BodoXVL9.mjs');
     let machineId;
     const shareArgs = [];
     for (let i = 1; i < machineArgs.length; i++) {
@@ -627,7 +627,7 @@ async function handleMachineCommand() {
     }
     await machineShare(machineId, { add, remove, list, configPath, showConfig });
   } else if (machineSubcommand === "exec") {
-    const { machineExec } = await import('./commands-D4_QgXrS.mjs');
+    const { machineExec } = await import('./commands-BodoXVL9.mjs');
     let machineId;
     let cwd;
     const cmdParts = [];
@@ -647,7 +647,7 @@ async function handleMachineCommand() {
     }
     await machineExec(machineId, command, cwd);
   } else if (machineSubcommand === "info") {
-    const { machineInfo } = await import('./commands-D4_QgXrS.mjs');
+    const { machineInfo } = await import('./commands-BodoXVL9.mjs');
     let machineId;
     for (let i = 1; i < machineArgs.length; i++) {
       if ((machineArgs[i] === "--machine" || machineArgs[i] === "-m") && i + 1 < machineArgs.length) {
@@ -670,7 +670,7 @@ async function handleMachineCommand() {
     const { machineNotify } = await import('./agentCommands-C6iGblcL.mjs');
     await machineNotify(message, level);
   } else if (machineSubcommand === "ls") {
-    const { machineLs } = await import('./commands-D4_QgXrS.mjs');
+    const { machineLs } = await import('./commands-BodoXVL9.mjs');
     let machineId;
     let showHidden = false;
     let path;
@@ -1044,50 +1044,42 @@ function printHelp() {
   console.log(`
 svamp \u2014 AI workspace on Hypha Cloud
 
-Usage:
-  svamp                        Start interactive Claude session (synced to cloud)
-  svamp start [-d <path>]      Same as above, with explicit directory
-  svamp login [url]            Login to Hypha (opens browser, stores token)
-  svamp daemon start           Start the daemon (detached)
-  svamp daemon stop            Stop the daemon (sessions preserved for restart)
-  svamp daemon restart         Restart the daemon (sessions resume seamlessly)
-  svamp daemon status          Show daemon status
-  svamp daemon install         Install as system service (launchd/systemd/wrapper)
-  svamp session list           List active sessions
-  svamp session spawn          Spawn a new session on the daemon
-  svamp session send <id> <m>  Send message to a session
-  svamp session wait <id>      Wait for agent to become idle
-  svamp session info <id>      Show session status & pending permissions
-  svamp session messages <id>  Show message history
-  svamp session approve <id>   Approve pending permission request
-  svamp session deny <id>      Deny pending permission request
-  svamp session attach <id>    Attach to a session (interactive terminal)
-  svamp session share <id>     Manage session sharing
-  svamp session --help         Show all session commands
-  svamp machine share          Manage machine sharing & security contexts
-  svamp machine --help         Show all machine commands
-  svamp skills find <query>    Search the skills marketplace
-  svamp skills install <n>     Install a skill from the marketplace
-  svamp skills --help          Show all skill commands
-  svamp process apply <f.yaml>  Create/update a supervised process (idempotent)
-  svamp process list           List supervised processes
-  svamp process start <name>   Start or create a process
-  svamp process logs <name>    Show process log output
-  svamp process --help         Show all process commands
-  svamp service expose <name>  Expose a service from this sandbox
-  svamp service list           List service groups
-  svamp service --help         Show all service commands
-  svamp agent list             List known agents
-  svamp agent <name>           Start local agent session (gemini, codex)
-  svamp --version              Show version
-  svamp --help                 Show this help
+Quick start \u2014 spawn an agent to do a task (use -p bypassPermissions to run autonomously):
+  svamp session spawn claude -d ./project -p bypassPermissions --message "fix tests" --wait
+
+  Note: without -p bypassPermissions the agent PAUSES waiting for human approval of each
+  tool use. This will cause it to hang in automated/agent contexts. Use bypassPermissions
+  for autonomous work, or "default" only when a human is actively watching.
+
+Commands:
+  svamp                              Start interactive Claude session (synced to cloud)
+  svamp login [url]                  Login to Hypha (opens browser, stores token)
+  svamp daemon start                 Start the background daemon (required for sessions)
+  svamp daemon status                Show daemon status
+  svamp daemon --help                Show all daemon commands
+
+  Session management (requires daemon running):
+  svamp session spawn <agent> [opts] Spawn a new agent session (agents: claude, gemini, codex)
+  svamp session send <id> <message>  Send message to a session (--wait to block until done)
+  svamp session wait <id>            Wait for agent to become idle
+  svamp session messages <id>        Show message history (--last N, --json, --raw)
+  svamp session info <id>            Show session status & pending permissions
+  svamp session list                 List sessions
+  svamp session stop <id>            Stop a session
+  svamp session attach <id>          Attach interactive terminal (stdin/stdout)
+  svamp session approve/deny <id>    Approve or deny pending permission requests
+  svamp session --help               Show ALL session commands and detailed options
+
+  Other:
+  svamp machine --help               Machine sharing & security contexts
+  svamp skills --help                Skills marketplace (find, install, publish)
+  svamp service --help               Service exposure (HTTP services from sandboxes)
+  svamp agent <name>                 Start local agent session (no daemon needed)
+  svamp --version                    Show version
 
 Interactive mode:
-  When you run 'svamp' with no arguments, Claude starts in your terminal
-  with full interactive access. Your session is synced to Hypha Cloud so
-  it's visible in the web app. When a message arrives from the web app,
-  svamp switches to remote mode to process it, then you can press
-  Space-Space to return to local mode.
+  Run 'svamp' with no arguments to start Claude in your terminal with cloud sync.
+  Messages from the web app auto-switch to remote mode. Space-Space returns to local.
 
 Environment variables:
   HYPHA_SERVER_URL     Hypha server URL (required for cloud sync)
@@ -1113,149 +1105,170 @@ Usage:
 }
 function printSessionHelp() {
   console.log(`
-svamp session \u2014 Manage daemon sessions (Claude, Gemini, Codex)
+svamp session \u2014 Spawn and manage AI agent sessions
 
-Commands:
-  svamp session list [--active] [--json]                       List sessions (alias: ls)
-  svamp session machines                                        List discoverable machines
-  svamp session spawn <agent> [-d <path>] [options]            Spawn a new session
-  svamp session stop <id>                                       Stop a session
-  svamp session info <id> [--json]                             Show status, activity & pending permissions
-  svamp session send <id> <message> [--wait] [--timeout N] [--json]
-                                                                Send a message to a session
-  svamp session wait <id> [--timeout N] [--json]               Wait for agent to become idle
-  svamp session messages <id> [--last N] [--json] [--raw] [--after N] [--limit N]
-                                                                Show messages (alias: msgs)
-  svamp session attach <id>                                     Attach to session (interactive terminal)
-  svamp session approve <id> [request-id] [--json]             Approve pending permission(s)
-  svamp session deny <id> [request-id] [--json]                Deny pending permission(s)
+QUICK START \u2014 Spawn a session, give it a task, get results:
 
-Spawn options:
-  -d, --directory <path>          Working directory (default: cwd)
-  -p, --permission-mode <mode>    Agent permission mode (see "Permission modes" below)
-  --message <msg>                 Send initial message after spawn
-  --wait                          Wait for agent to become idle before returning
-  --worktree                      Create a git worktree branch (at .dev/worktree/<name>)
-  --isolate                       Force OS-level sandbox isolation
-  --security-context <path>       Apply security context config (JSON file)
-  --share <email>[:<role>]        Share with user (repeatable). Role: view, interact, admin
-  --deny-network                  Block all network access
-  --deny-read <path>              Deny reading path (repeatable)
-  --allow-write <path>            Allow writing path (repeatable)
-  --allow-domain <domain>         Allow network domain (repeatable)
+  # One-liner: spawn agent, send task, wait for completion
+  svamp session spawn claude -d ./my-project -p bypassPermissions \\
+    --message "fix the failing tests" --wait
 
-Permission modes (-p, --permission-mode):
-  default              Prompt for each tool use (default)
-  acceptEdits          Auto-approve file edits, prompt for bash/dangerous tools
-  bypassPermissions    Auto-approve all tools (no prompts)
+  # The command prints the session ID (e.g., "abc12345-..."). Use it to:
+  svamp session messages abc1 --last 10         # read output (prefix match on ID)
+  svamp session send abc1 "now run lint" --wait  # send follow-up, wait for done
+  svamp session stop abc1                        # stop when finished
 
-Permission workflow:
-  When an agent runs with 'default' or 'acceptEdits' permission mode, it pauses
-  when it needs to use a tool that requires approval. Use these commands to manage:
+  # Spawn on a remote/cloud machine:
+  svamp session spawn claude -d /workspace -m cloud-box --message "deploy" --wait
 
-  1. Check status:    svamp session info <id> --json
-                      \u2192 shows pendingPermissions array when agent is blocked
-  2. Wait & detect:   svamp session wait <id> --json
-                      \u2192 exits with code 2 if permission pending (see exit codes)
-  3. Approve:         svamp session approve <id>          (approve all pending)
-                      svamp session approve <id> <rid>    (approve specific request)
-  4. Deny:            svamp session deny <id>             (deny all pending)
-                      svamp session deny <id> <rid>       (deny specific request)
+AGENTS:
+  claude    Claude Code \u2014 full coding agent (default)
+  gemini    Google Gemini via ACP protocol
+  codex     OpenAI Codex via MCP protocol
 
-  Request IDs support prefix matching (e.g., "abc1" matches "abc12345-...").
+  Usage: svamp session spawn <agent> [options]
+  The <agent> argument is required. Use "claude" if unsure.
 
-Messages options:
-  --last N       Show only the last N messages
-  --after N      Start after sequence number N
-  --limit N      Max messages to fetch from server (default: 1000, cap: 500 per page)
-  --json         Output as JSON (FormattedMessage: id, seq, role, text, createdAt)
-  --raw          With --json: output full raw message objects (includes tool_use args,
-                 tool_result content, thinking blocks \u2014 use for programmatic parsing)
+COMMANDS:
 
-Exit codes (wait, send --wait, spawn --wait):
-  0   Agent is idle (task completed)
-  1   Error (timeout, connection failure, session not found)
-  2   Agent is waiting for permission approval \u2014 use approve/deny to continue
+  Lifecycle:
+    spawn <agent> [-d <path>] [options]   Spawn a new agent session
+    stop <id>                             Stop a running session
+    list [--active] [--json]              List sessions (alias: ls)
+    machines                              List discoverable machines
+    info <id> [--json]                    Show status & pending permissions
 
-Global options:
-  --machine <id>, -m <id>  Target a specific machine (prefix match supported)
+  Communicate:
+    send <id> <message> [--wait] [--timeout N] [--json]
+                                          Send a message to a running session
+    messages <id> [--last N] [--json]     Read message history (alias: msgs)
+    wait <id> [--timeout N] [--json]      Wait for agent to become idle
+    attach <id>                           Attach interactive terminal (stdin/stdout)
 
-Agents: claude (default), gemini, codex
-Session and machine IDs support prefix matching (e.g., "abc1" matches "abc12345-...").
+  Permissions (when agent pauses for approval):
+    approve <id> [request-id] [--json]    Approve pending tool permission(s)
+    deny <id> [request-id] [--json]       Deny pending tool permission(s)
 
-Sharing:
-  svamp session share <id> --list                            List shared users
-  svamp session share <id> --add <email>[:<role>]            Share with user
-  svamp session share <id> --remove <email>                  Remove shared user
-  svamp session share <id> --public <view|interact|off>     Set public link access
+  Sharing:
+    share <id> --list                     List shared users
+    share <id> --add <email>[:<role>]     Share with user (role: view|interact|admin)
+    share <id> --remove <email>           Remove shared user
+    share <id> --public <view|interact|off>  Set public link access
 
-Options:
-  --machine <id>, -m <id>  Target a specific machine (prefix match supported)
+  Ralph Loop (iterative automation):
+    ralph-start <id> "<task>" [options]   Start iterative loop
+    ralph-cancel <id>                     Cancel loop
+    ralph-status <id>                     Show loop status
+
+  Message Queue:
+    queue add <id> "<message>"            Queue a message for later
+    queue list <id>                       List queued messages
+    queue clear <id>                      Clear queue
+
+SPAWN OPTIONS:
+  -d, --directory <path>          Working directory (REQUIRED for meaningful work)
+  -p, --permission-mode <mode>    Permission mode (see below). Default: "default"
+  --message <msg>                 Send this message to the agent immediately after spawn
+  --wait                          Block until agent finishes (idle). Combine with --message
+                                  for fire-and-forget: spawn \u2192 task \u2192 wait \u2192 done.
+  --timeout <sec>                 Timeout for --wait (default: no timeout)
+  --worktree                      Create isolated git worktree branch (.dev/worktree/<name>)
+  --tags <tag1,tag2>              Comma-separated tags for session grouping
+  --parent <sessionId>            Set parent session (auto-set from SVAMP_SESSION_ID env)
 
-Spawn options:
-  -p, --permission-mode <mode>  Agent permission mode: default, acceptEdits, bypassPermissions
-  --worktree                    Create a git worktree branch as working directory
+PERMISSION MODES:
+  default              \u26A0 Agent PAUSES and waits for human approval before each tool use.
+                       The agent will be stuck (exit code 2) until you run approve/deny.
+                       DO NOT use default mode in automated pipelines \u2014 the agent will hang.
+  acceptEdits          Auto-approve file edits. Still pauses for bash & dangerous tools.
+  bypassPermissions    Auto-approve everything. No prompts, no pauses. Fully autonomous.
+                       Use this for automation, CI, or when spawning from another agent.
 
-Spawn isolation options:
-  --share <email>[:<role>]    Share session (repeatable). Role: view, interact, admin
-  --security-context <path>   Path to security context JSON config file
-  --isolate                   Force OS-level isolation even without sharing
-  --deny-read <path>          Deny read access to path (repeatable)
-  --allow-write <path>        Allow write access to path (repeatable)
-  --deny-network              Deny all network access
-  --allow-domain <domain>     Allow network access to domain (repeatable)
+  \u26A1 For agents/scripts: ALWAYS pass -p bypassPermissions unless you have a human
+     monitoring the session who can approve/deny tool requests in real time.
 
-Spawn grouping options:
-  --tags <tag1,tag2>          Comma-separated tags
-  --parent <sessionId>        Set parent session (auto-detected from SVAMP_SESSION_ID)
+PERMISSION WORKFLOW (only relevant for "default" and "acceptEdits" modes):
+  1. svamp session wait <id> --json    \u2192 exit code 2 means permission pending
+  2. svamp session info <id> --json    \u2192 shows pendingPermissions array
+  3. svamp session approve <id>        \u2192 approve all pending (or approve <id> <rid>)
+  4. svamp session deny <id>           \u2192 deny all pending (or deny <id> <rid>)
+
+ISOLATION & SHARING OPTIONS (for spawn):
+  --isolate                       Force OS-level sandbox (even without sharing)
+  --security-context <path>       Apply security context config (JSON file)
+  --share <email>[:<role>]        Share session (repeatable). Role: view|interact|admin
+  --deny-network                  Block all network access
+  --deny-read <path>              Deny reading path (repeatable)
+  --allow-write <path>            Allow writing path (repeatable)
+  --allow-domain <domain>         Allow network domain (repeatable)
 
-Agents: claude (default), gemini, codex
+MESSAGES OPTIONS:
+  --last N       Show last N messages only
+  --after N      Start after sequence number N (for pagination)
+  --limit N      Max messages to fetch (default: 1000)
+  --json         Output as JSON array of {id, seq, role, text, createdAt}
+  --raw          With --json: include full raw objects (tool_use, tool_result, thinking)
 
-Session and machine IDs can be abbreviated (prefix match, like Docker).
+RALPH LOOP OPTIONS (for ralph-start):
+  --context-mode <mode>           fresh (new process each iteration) or continue (same process)
+  --completion-promise <text>     Completion signal text (default: DONE)
+  --max-iterations <n>            Max iterations (default: 10)
+  --cooldown <sec>                Delay between iterations (default: 1)
 
-NOTE: By default, spawned agents run with 'default' permission mode, which means
-the agent may pause to request permission for tool use (file edits, bash, etc.).
-Use -p bypassPermissions to run without approval prompts.
+EXIT CODES (for wait, send --wait, spawn --wait):
+  0   Agent is idle (task completed successfully)
+  1   Error (timeout, connection failure, session not found)
+  2   Agent is waiting for permission approval \u2014 use approve/deny to unblock
 
-Attach commands:
+ATTACH COMMANDS (inside an attached session):
   /quit, /detach    Detach (session keeps running)
   /abort, /cancel   Cancel current agent turn
-  /kill             Stop the session
+  /kill             Stop the session entirely
   /info             Show session status
 
-Ralph Loop (iterative task automation):
-  svamp session ralph-start <id> "<task>" [--context-mode fresh|continue] [--completion-promise TEXT] [--max-iterations N] [--cooldown N]
-  svamp session ralph-cancel <id>
-  svamp session ralph-status <id>
-  (alias: svamp session ralph <id> "<task>" ...)
+GLOBAL OPTIONS:
+  --machine <id>, -m <id>   Target a specific machine (prefix match supported)
 
-Message Queue:
-  svamp session queue add <id> "<message>"
-  svamp session queue list <id>
-  svamp session queue clear <id>
+ID MATCHING:
+  Session and machine IDs support prefix matching.
+  "abc1" matches "abc12345-6789-..." \u2014 you only need enough characters to be unique.
 
-Examples:
-  # Spawn with bypassed permissions (no prompts)
-  svamp session spawn claude -d ./proj -p bypassPermissions --message "fix tests" --wait
+EXAMPLES:
+
+  # === Common: Spawn agent to do a task and wait ===
+  svamp session spawn claude -d ./my-project -p bypassPermissions \\
+    --message "fix all TypeScript errors, run tsc to verify" --wait
+
+  # === Multi-step: Spawn, then send messages interactively ===
+  ID=$(svamp session spawn claude -d ./proj -p bypassPermissions)
+  svamp session send $ID "first, read the README" --wait
+  svamp session send $ID "now implement the feature described there" --wait
+  svamp session messages $ID --last 20
 
-  # Spawn with default permissions, handle approval via CLI
-  svamp session spawn claude -d ./proj --message "refactor auth"
-  svamp session wait abc1 --json           # exits with code 2 if permission pending
-  svamp session approve abc1               # approve all pending permissions
-  svamp session wait abc1                  # wait for completion
+  # === Spawn child session from another agent (e.g., in a bash tool) ===
+  # Use -p bypassPermissions so the child doesn't get stuck on approvals.
+  # Use --wait so your script blocks until the child finishes.
+  svamp session spawn claude -d /tmp/test-project -p bypassPermissions \\
+    --message "run the test suite and report results" --wait
+  # Then read the child's output:
+  svamp session messages <child-id> --last 5
 
-  # Monitor session messages (raw for full tool details)
-  svamp session messages abc1 --last 10 --json --raw
+  # === Monitor with permissions (default mode) ===
+  svamp session spawn claude -d ./proj --message "refactor auth module"
+  svamp session wait abc1 --json       # exit code 2 = permission pending
+  svamp session approve abc1           # approve all pending
+  svamp session wait abc1              # wait for completion
 
-  # Send message and wait for completion
-  svamp session send abc1 "run the tests" --wait --json
+  # === Spawn on a remote machine ===
+  svamp session spawn claude -d /workspace -m my-cloud-box \\
+    -p bypassPermissions --message "deploy to staging" --wait
 
-  # Isolation & sharing
+  # === Isolated session with network restrictions ===
   svamp session spawn claude -d /tmp/sandbox --isolate --deny-network
-  svamp session spawn claude -d /tmp/proj --share alice@example.com:admin
 
-  # Ralph Loop
-  svamp session ralph-start abc1 "Fix all linting errors" --context-mode fresh --max-iterations 10
+  # === Ralph Loop: iterative task automation ===
+  svamp session ralph-start abc1 "Fix all linting errors" \\
+    --context-mode fresh --max-iterations 10
 `);
 }
 function printMachineHelp() {

package/dist/{commands-D4_QgXrS.mjs → commands-BodoXVL9.mjs}

@@ -2,7 +2,7 @@ import { existsSync, readFileSync } from 'node:fs';
 import { execSync } from 'node:child_process';
 import { resolve, join } from 'node:path';
 import os from 'node:os';
-import { l as loadSecurityContextConfig, e as resolveSecurityContext, f as buildSecurityContextFromFlags, m as mergeSecurityContexts, c as connectToHypha } from './run-DWFTrXVF.mjs';
+import { l as loadSecurityContextConfig, e as resolveSecurityContext, f as buildSecurityContextFromFlags, m as mergeSecurityContexts, c as connectToHypha } from './run-C7CEDmD4.mjs';
 import 'os';
 import 'fs/promises';
 import 'fs';

package/dist/{commands-BwT-PFl4.mjs → commands-CIgrbviM.mjs}

@@ -1,11 +1,11 @@
 import { writeFileSync, readFileSync } from 'fs';
 import { resolve } from 'path';
-import { connectAndGetMachine } from './commands-D4_QgXrS.mjs';
+import { connectAndGetMachine } from './commands-BodoXVL9.mjs';
 import 'node:fs';
 import 'node:child_process';
 import 'node:path';
 import 'node:os';
-import './run-DWFTrXVF.mjs';
+import './run-C7CEDmD4.mjs';
 import 'os';
 import 'fs/promises';
 import 'url';

package/dist/index.mjs

@@ -1,4 +1,4 @@
-export { c as connectToHypha, d as daemonStatus, g as getHyphaServerUrl, r as registerMachineService, a as registerSessionService, s as startDaemon, b as stopDaemon } from './run-DWFTrXVF.mjs';
+export { c as connectToHypha, d as daemonStatus, g as getHyphaServerUrl, r as registerMachineService, a as registerSessionService, s as startDaemon, b as stopDaemon } from './run-C7CEDmD4.mjs';
 import 'os';
 import 'fs/promises';
 import 'fs';

package/dist/{package-CHfluhvW.mjs → package-B0d2rUXI.mjs}

@@ -1,5 +1,5 @@
 var name = "svamp-cli";
-var version = "0.1.68";
+var version = "0.1.70";
 var description = "Svamp CLI — AI workspace daemon on Hypha Cloud";
 var author = "Amun AI AB";
 var license = "SEE LICENSE IN LICENSE";