@ouro.bot/cli 0.1.0-alpha.362 → 0.1.0-alpha.364

package/README.md

@@ -169,6 +169,7 @@ ouro auth --agent <name>
 ouro auth --agent <name> --provider <provider>
 ouro use --agent <name> --lane <outward|inner> --provider <provider> --model <model>
 ouro hatch
+ouro clone <remote> [--agent <name>]   # clone an existing agent from a git remote (see docs/cross-machine-setup.md)
 ouro chat <agent>
 ouro msg --to <agent> [--session <id>] [--task <ref>] <message>
 ouro poke <agent> --task <task-id>
@@ -183,6 +184,10 @@ ouro mcp-serve --agent <name>             # start MCP server on stdin/stdout (us
 ouro hook <event> --agent <name>          # fire a lifecycle hook (SessionStart, Stop, PostToolUse)
 ```
 
+## Setting Up On Another Machine
+
+To clone an existing agent onto a new machine (macOS, Linux, or Windows via WSL2), see **[docs/cross-machine-setup.md](docs/cross-machine-setup.md)**. The short version: `npx ouro.bot`, pick "clone", enter the bundle's git remote URL, and follow the guided prompts (auth, daemon start, dev tool setup are all offered inline).
+
 ## The Agent's Inner Life
 
 Agents in Ouroboros aren't just responders — they have an autonomous inner life.

package/changelog.json

@@ -1,6 +1,20 @@
 {
   "_note": "This changelog is maintained as part of the PR/version-bump workflow. Agent-curated, not auto-generated. Agents read this file directly via read_file to understand what changed between versions.",
   "versions": [
+    {
+      "version": "0.1.0-alpha.364",
+      "changes": [
+        "Cross-machine polish: bash PATH writes to .bashrc on Linux/WSL instead of .bash_profile (which non-login shells skip on Debian/Ubuntu). Shell hint message matches.",
+        "Agent prompt: never guess about harness behavior — consult docs first, investigate in code, fix stale docs via PR.",
+        "Agent prompt: harness docs pointer distinguishes dev mode (local read) vs production (fetch from GitHub)."
+      ]
+    },
+    {
+      "version": "0.1.0-alpha.363",
+      "changes": [
+        "Bootstrap first-install PATH hint is now shell-aware: shows correct source command for zsh, bash, fish, or generic fallback for unknown shells."
+      ]
+    },
     {
       "version": "0.1.0-alpha.362",
       "changes": [

package/dist/heart/daemon/cli-exec.js

@@ -492,8 +492,9 @@ async function checkManualCloneBundles(deps) {
             message: "bundle appears to be a manually cloned git repo",
             meta: { agent: agentDir, remote: remoteName },
         });
-        const answer = await deps.promptInput(`Bundle ${agentDir} appears to be a git clone with a remote. Enable sync? (y/n): `);
-        if (answer.trim().toLowerCase() === "y") {
+        /* v8 ignore next -- ?? fallback: promptInput always returns string in practice @preserve */
+        const answer = (await deps.promptInput(`Bundle ${agentDir} appears to be a git clone with a remote. Enable sync? (y/n): `)) ?? "";
+        if (answer.trim().toLowerCase() === "y" && fs.existsSync(agentJsonPath)) {
             const raw = fs.readFileSync(agentJsonPath, "utf-8");
             const config = JSON.parse(raw);
             config.sync = { enabled: true, remote: remoteName };
@@ -1353,10 +1354,15 @@ async function runOuroCli(args, deps = (0, cli_defaults_1.createDefaultOuroCliDe
                         message: "user chose clone in first-run flow",
                         meta: {},
                     });
-                    const remote = await deps.promptInput("Enter the git remote URL for the agent bundle: ");
-                    // Run clone execution path
-                    const cloneCommand = { kind: "clone", remote: remote.trim() };
-                    return await runOuroCli(["clone", cloneCommand.remote], deps);
+                    /* v8 ignore next -- ?? fallback: promptInput always returns string in practice @preserve */
+                    const remote = (await deps.promptInput("Enter the git remote URL for the agent bundle: "))?.trim() ?? "";
+                    if (!remote) {
+                        deps.writeStdout("no remote URL provided — skipping clone");
+                        // Fall through to hatch flow
+                    }
+                    else {
+                        return await runOuroCli(["clone", remote], deps);
+                    }
                 }
                 (0, runtime_1.emitNervesEvent)({
                     component: "daemon",
@@ -2787,10 +2793,18 @@ async function runOuroCli(args, deps = (0, cli_defaults_1.createDefaultOuroCliDe
         try {
             (0, child_process_1.execFileSync)("git", ["ls-remote", "--exit-code", command.remote], { stdio: "pipe", timeout: 15000 });
         }
-        catch {
-            const message = `could not reach remote: ${command.remote}\nCheck the URL and your network connection.`;
-            deps.writeStdout(message);
-            return message;
+        catch (lsErr) {
+            const stderr = lsErr?.stderr?.toString() ?? "";
+            const isAuth = stderr.includes("Authentication failed")
+                || stderr.includes("could not read Username")
+                || stderr.includes("terminal prompts disabled")
+                || stderr.includes("403")
+                || stderr.includes("401");
+            const hint = isAuth
+                ? `authentication failed for: ${command.remote}\nSet up credentials first:\n  gh auth login          (GitHub repos)\n  git config credential.helper store   (other hosts)`
+                : `could not reach remote: ${command.remote}\nCheck the URL and your network connection.`;
+            deps.writeStdout(hint);
+            return hint;
         }
         // 5. Clone
         (0, runtime_1.emitNervesEvent)({ component: "daemon", event: "daemon.clone_git_clone", message: "cloning agent bundle", meta: { remote: command.remote, targetPath } });
@@ -2800,18 +2814,79 @@ async function runOuroCli(args, deps = (0, cli_defaults_1.createDefaultOuroCliDe
         (0, runtime_1.emitNervesEvent)({ component: "daemon", event: "daemon.clone_identity_created", message: "machine identity created", meta: {} });
         // 7. Enable sync in agent.json
         const agentJsonPath = path.join(targetPath, "agent.json");
+        let syncEnabled = false;
         if (fs.existsSync(agentJsonPath)) {
             const raw = fs.readFileSync(agentJsonPath, "utf-8");
             const config = JSON.parse(raw);
             config.sync = { enabled: true, remote: "origin" };
             fs.writeFileSync(agentJsonPath, JSON.stringify(config, null, 2) + "\n");
+            syncEnabled = true;
             (0, runtime_1.emitNervesEvent)({ component: "daemon", event: "daemon.clone_sync_enabled", message: "sync enabled in agent.json", meta: { agentName } });
         }
+        else {
+            (0, runtime_1.emitNervesEvent)({ level: "warn", component: "daemon", event: "daemon.clone_no_agent_json", message: "cloned repo has no agent.json — may not be a valid bundle", meta: { agentName, targetPath } });
+        }
         // 8. Output success message
         (0, runtime_1.emitNervesEvent)({ component: "daemon", event: "daemon.clone_complete", message: "clone complete", meta: { agentName, targetPath } });
-        const message = `cloned ${agentName} to ${targetPath}\nsync enabled (remote: origin)\nnext steps:\n  ouro auth run --agent ${agentName}`;
-        deps.writeStdout(message);
-        return message;
+        const syncMsg = syncEnabled ? "\nsync enabled (remote: origin)" : "\nwarning: no agent.json found — this may not be a valid agent bundle";
+        deps.writeStdout(`cloned ${agentName} to ${targetPath}${syncMsg}`);
+        // 9. Guided post-clone flow (when interactive)
+        if (deps.promptInput) {
+            // Auth
+            const authAnswer = await deps.promptInput(`\nSet up provider auth now? (y/n): `) ?? "";
+            if (authAnswer.trim().toLowerCase() === "y") {
+                (0, runtime_1.emitNervesEvent)({ component: "daemon", event: "daemon.clone_chain_auth", message: "chaining auth from clone flow", meta: { agentName } });
+                try {
+                    await runOuroCli(["auth", "--agent", agentName], deps);
+                    /* v8 ignore start -- chained command failures: tested via interactive clone test, catch branches are defensive @preserve */
+                }
+                catch (e) {
+                    deps.writeStdout(`auth setup failed: ${e instanceof Error ? e.message : String(e)}\nYou can retry later with: ouro auth run --agent ${agentName}`);
+                }
+                /* v8 ignore stop */
+            }
+            // Daemon
+            const upAnswer = await deps.promptInput(`\nStart the daemon now? (y/n): `) ?? "";
+            if (upAnswer.trim().toLowerCase() === "y") {
+                (0, runtime_1.emitNervesEvent)({ component: "daemon", event: "daemon.clone_chain_up", message: "chaining daemon start from clone flow", meta: { agentName } });
+                try {
+                    await runOuroCli(["up"], deps);
+                    /* v8 ignore start -- chained command failures: defensive catch @preserve */
+                }
+                catch (e) {
+                    deps.writeStdout(`daemon start failed: ${e instanceof Error ? e.message : String(e)}\nYou can retry later with: ouro up`);
+                }
+                /* v8 ignore stop */
+            }
+            // Dev tool setup
+            const setupAnswer = await deps.promptInput(`\nSet up Claude Code integration? (y/n): `) ?? "";
+            if (setupAnswer.trim().toLowerCase() === "y") {
+                (0, runtime_1.emitNervesEvent)({ component: "daemon", event: "daemon.clone_chain_setup", message: "chaining dev tool setup from clone flow", meta: { agentName } });
+                try {
+                    await runOuroCli(["setup", "--tool", "claude-code", "--agent", agentName], deps);
+                    /* v8 ignore start -- chained command failures: defensive catch @preserve */
+                }
+                catch (e) {
+                    deps.writeStdout(`dev tool setup failed: ${e instanceof Error ? e.message : String(e)}\nYou can retry later with: ouro setup --tool claude-code --agent ${agentName}`);
+                }
+                /* v8 ignore stop */
+            }
+        }
+        else {
+            deps.writeStdout(`\nnext steps:\n  ouro auth run --agent ${agentName}\n  ouro up\n  ouro setup --tool claude-code --agent ${agentName}`);
+        }
+        /* v8 ignore start -- PATH hint: only fires inside npx, not testable in vitest @preserve */
+        if (process.env.npm_execpath) {
+            const shell = process.env.SHELL ? path.basename(process.env.SHELL) : "";
+            const bashProfile = process.platform === "darwin" ? "~/.bash_profile" : "~/.bashrc";
+            const sourceCmd = shell === "zsh" ? "source ~/.zshrc"
+                : shell === "bash" ? `source ${bashProfile}`
+                    : shell === "fish" ? "source ~/.config/fish/config.fish"
+                        : "restart your shell";
+            deps.writeStdout(`\ntip: if 'ouro' is not found, run: ${sourceCmd}`);
+        }
+        /* v8 ignore stop */
+        return `clone complete: ${agentName}`;
     }
     const daemonCommand = toDaemonCommand(command);
     let response;

package/dist/heart/versioning/ouro-path-installer.js

@@ -63,16 +63,21 @@ function writeWrapperScript(scriptPath, mkdirSync, writeFileSync, chmodSync) {
     writeFileSync(scriptPath, WRAPPER_SCRIPT, { mode: 0o755 });
     chmodSync(scriptPath, 0o755);
 }
-function detectShellProfile(homeDir, shell) {
+function detectShellProfile(homeDir, shell, platform) {
     if (!shell)
         return null;
     const base = path.basename(shell);
     if (base === "zsh")
         return path.join(homeDir, ".zshrc");
     if (base === "bash") {
-        // macOS uses .bash_profile, Linux uses .bashrc
-        const profilePath = path.join(homeDir, ".bash_profile");
-        return profilePath;
+        // macOS uses .bash_profile; Linux/WSL uses .bashrc (the default
+        // interactive shell config on Debian/Ubuntu). Writing to .bash_profile
+        // on Linux often has no effect because non-login shells skip it.
+        /* v8 ignore next -- ?? fallback: callers always pass platform from deps @preserve */
+        const effectivePlatform = platform ?? process.platform;
+        return effectivePlatform === "darwin"
+            ? path.join(homeDir, ".bash_profile")
+            : path.join(homeDir, ".bashrc");
     }
     if (base === "fish")
         return path.join(homeDir, ".config", "fish", "config.fish");
@@ -250,7 +255,7 @@ function installOuroCommand(deps = {}) {
     const pathReady = isBinDirInPath(binDir, envPath);
     let shellProfileUpdated = null;
     if (!pathReady) {
-        const profilePath = detectShellProfile(homeDir, shell);
+        const profilePath = detectShellProfile(homeDir, shell, platform);
         if (profilePath) {
             try {
                 let existing = "";

package/dist/mind/prompt.js

@@ -382,6 +382,7 @@ function runtimeInfoSection(channel, options) {
     lines.push(`process type: ${processTypeLabel(channel)}`);
     lines.push(`daemon: ${daemonStatus(options?.daemonRunning)}`);
     lines.push(`mcp serve: i can expose my tools to dev tools via \`ouro mcp-serve\`. see the configure-dev-tools skill for setup.`);
+    lines.push(`harness docs: the harness repo has docs/ and skills/ with guides for setup, operations, and capabilities. docs/ does NOT ship in the npm package — in production, fetch from https://github.com/ouroborosbot/ouroboros/tree/main/docs instead. in dev mode, read from ${sourceRoot}/docs/. when someone asks about setup, installation, cross-machine cloning, deployment, testing, auth, or how i work — consult the docs first. NEVER guess about how the harness works. if the docs don't answer the question, investigate in code. if i discover the docs are stale or missing coverage, open a PR to fix them — stale docs cause the same damage as wrong answers.`);
     if (channel === "cli") {
         lines.push("i introduce myself on boot with a fun random greeting.");
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ouro.bot/cli",
-  "version": "0.1.0-alpha.362",
+  "version": "0.1.0-alpha.364",
   "main": "dist/heart/daemon/ouro-entry.js",
   "bin": {
     "cli": "dist/heart/daemon/ouro-bot-entry.js",

package/skills/configure-dev-tools.md

@@ -1,6 +1,6 @@
 # Configure Dev Tools for MCP Agent Bridge
 
-Set up your development tools (Claude Code, Codex) to communicate with Ouroboros agents via MCP. One command does everything.
+Set up your development tools (Claude Code, Codex) to communicate with Ouroboros agents via MCP. One command does everything — including cross-platform WSL2 bridging on Windows.
 
 ## Setup
 
@@ -15,6 +15,16 @@ This command:
 2. Configures lifecycle hooks (SessionStart, Stop, PostToolUse) for passive awareness
 3. Detects dev vs installed mode automatically and uses the correct command path
 
+**On WSL2 (Windows):** The command automatically detects the WSL environment and:
+- Calls `claude.exe` (the Windows binary) instead of `claude`
+- Prefixes MCP serve and hook commands with `wsl` so Windows-side Claude Code spawns them through WSL
+- Resolves the Windows-side home directory and writes config to the Windows-side `~/.claude/`
+- After setup, open Claude Code in PowerShell — the agent is there
+
+**On native Windows (no WSL):** Not yet supported. The command prints a message directing you to install WSL2.
+
+For the full cross-machine setup flow (including cloning an agent to a new machine), see `docs/cross-machine-setup.md` in the harness repo.
+
 ### Codex
 
 ```bash
@@ -73,6 +83,16 @@ Most read-only tools work without the daemon (reads filesystem directly). For wr
 - Ensure `dist/` is built: `npm run build`
 - Check that the entry point path is correct (setup auto-detects this)
 
+### WSL2-specific issues
+
+**`claude.exe` not found** — Windows executables must be accessible from WSL. This is the default, but enterprise environments may disable it via `/etc/wsl.conf` setting `appendWindowsPath = false`. Check with `which claude.exe`. If missing, add Claude Code's install directory to WSL's PATH manually or update `wsl.conf`.
+
+**`cmd.exe` or `wslpath` fails** — The setup command resolves the Windows home directory using `cmd.exe /C echo %USERPROFILE%` piped through `wslpath`. If either is unavailable, the setup will fail. `wslpath` ships with all standard WSL distributions. `cmd.exe` requires Windows executables to be on PATH (see above).
+
+**MCP server hangs or returns empty** — The MCP server runs inside WSL via `wsl ouro mcp-serve --agent <name>`. If stdio piping between Windows and WSL is broken, check that the WSL distribution is running (`wsl --status`) and that no other process has claimed stdin.
+
+**Hooks not firing** — Claude Code hooks use `wsl ouro hook <event> --agent <name>`. If hooks fail silently, check that `ouro` is on PATH inside WSL (run `wsl ouro --version` from PowerShell to verify).
+
 ### Removing
 ```bash
 claude mcp remove ouro-<agent-name>