@launchchair/agent 0.4.10 → 0.4.12

package/AGENTS.md

@@ -6,7 +6,7 @@ This file is for fresh agent chats that need to use the LaunchChair Agent API or
 
 Use LaunchChair first for product, research, validation, positioning, pricing, MVP blueprint, and phase-loop work. Do not inspect the local repo first unless the user is in Stack Setup, Build MVP, Design and Landing Page implementation, or another code-changing phase.
 
-Fresh LaunchChair projects often do not have a local repo yet. Before Stack Setup, the configured runner folder may be empty on purpose.
+Fresh LaunchChair projects often do not have a local repo yet. Before Stack Setup, each project uses its own isolated workspace under `~/.launchchair/projects`.
 
 ## Public Docs To Read
 
@@ -35,6 +35,7 @@ mkdir -p "$HOME/launchchair-agent"
 curl -fsSL "https://www.launchchair.io/api/agent/v1/bridge/local-bridge.mjs" -o "$HOME/launchchair-agent/local-bridge.mjs"
 curl -fsSL "https://www.launchchair.io/api/agent/v1/bridge/launchchair-cli.mjs" -o "$HOME/launchchair-agent/launchchair-cli.mjs"
 curl -fsSL "https://www.launchchair.io/api/agent/v1/bridge/mcp-bridge-server.mjs" -o "$HOME/launchchair-agent/mcp-bridge-server.mjs"
+curl -fsSL "https://www.launchchair.io/api/agent/v1/bridge/project-workspace.mjs" -o "$HOME/launchchair-agent/project-workspace.mjs"
 curl -fsSL "https://www.launchchair.io/api/agent/v1/bridge/runner-command.mjs" -o "$HOME/launchchair-agent/runner-command.mjs"
 curl -fsSL "https://www.launchchair.io/api/agent/v1/bridge/codex-runner.mjs" -o "$HOME/launchchair-agent/codex-runner.mjs"
 curl -fsSL "https://www.launchchair.io/api/agent/v1/bridge/claude-code-runner.mjs" -o "$HOME/launchchair-agent/claude-code-runner.mjs"
@@ -42,21 +43,8 @@ curl -fsSL "https://www.launchchair.io/api/agent/v1/bridge/chatgpt-runner.mjs" -
 curl -fsSL "https://www.launchchair.io/api/agent/v1/bridge/claude-runner.mjs" -o "$HOME/launchchair-agent/claude-runner.mjs"
 curl -fsSL "https://www.launchchair.io/agent-artifacts/AGENTS.md" -o "$HOME/launchchair-agent/AGENTS.md"
 chmod +x "$HOME/launchchair-agent"/*.mjs
-LAUNCHCHAIR_AGENT_WORKDIR="${LC_AGENT_CODEX_CWD:-${LC_AGENT_CLAUDE_CODE_CWD:-$PWD}}"
-if [ -d "$LAUNCHCHAIR_AGENT_WORKDIR" ] && [ ! -f "$LAUNCHCHAIR_AGENT_WORKDIR/AGENTS.md" ]; then
-  printf '%s\n' \
-    '# LaunchChair Agent Bootstrap Pointer' \
-    '' \
-    'Before searching this repo, read ~/launchchair-agent/AGENTS.md.' \
-    'Use LaunchChair MCP/API first for product phases, project discovery, project creation, and phase loops.' \
-    'Do not ask for extra confirmation before using LaunchChair MCP/API when the user already requested the action and the token permits it.' \
-    'Only inspect this repo for Stack Setup, Build MVP, Design/Landing Page, SEO implementation, smoke testing, security review, or code remediation.' \
-    > "$LAUNCHCHAIR_AGENT_WORKDIR/AGENTS.md"
-fi
 ```
 
-The final block creates a tiny project-local `AGENTS.md` pointer only when the target folder does not already have one. It helps fresh Codex chats auto-load the LaunchChair instructions without overwriting a real project instruction file.
-
 ## CLI
 
 The npm CLI is the recommended setup path for Codex Desktop and Claude Desktop. It can log in through LaunchChair, save the token locally, print paste-ready MCP config, write Claude Desktop config, and start the local bridge.
@@ -64,8 +52,9 @@ The npm CLI is the recommended setup path for Codex Desktop and Claude Desktop.
 ```bash
 npm install -g @launchchair/agent
 launchchair login
-launchchair setup codex --cwd /absolute/path/to/repo-or-empty-folder
-launchchair setup claude --cwd /absolute/path/to/repo-or-empty-folder
+launchchair setup codex
+launchchair setup claude
+launchchair bind --project-id PROJECT_UUID --cwd /absolute/path/to/verified-clone
 launchchair projects --query LeafLore
 launchchair create --name SignalLift --one-liner "Distribution workspace for technical founders" --project-type b2b --idempotency-key signallift-v1
 launchchair run-once
@@ -76,7 +65,7 @@ launchchair mcp-config codex --ui-fields
 If Codex Desktop is being configured through the custom MCP form instead of `~/.codex/config.toml`, run:
 
 ```bash
-launchchair setup codex --cwd /absolute/path/to/repo-or-empty-folder --copy-config
+launchchair setup codex --copy-config
 ```
 
 ## Environment Variables
@@ -89,12 +78,12 @@ LAUNCHCHAIR_PROJECT_ID="optional project UUID; omit or leave blank if creating o
 `launchchair login` is the recommended token path. It saves the token to `~/.launchchair/config.json`, and `launchchair mcp-server` reads that saved token. Use `LAUNCHCHAIR_AGENT_TOKEN` only as a manual fallback when browser login is skipped or a per-client token override is needed.
 The packaged MCP and local bridges also read the same saved CLI config as a fallback, so a desktop MCP launch should not require pasting a token into Codex or Claude config after browser login. Guided setup verifies standards-compliant MCP initialize and tool discovery before it reports success.
 
-For Codex Desktop local runs:
+For Codex Desktop local runs, choose the runner globally and bind each project clone independently:
 
 ```bash
 LC_AGENT_ROUTER_GPT_TARGET="codex"
 LC_AGENT_ROUTER_CODEX_TARGET="codex"
-LC_AGENT_CODEX_CWD="/absolute/path/to/the-folder-codex-should-build-into"
+launchchair bind --project-id PROJECT_UUID --cwd /absolute/path/to/verified-clone
 ```
 
 For Claude Desktop plus Claude Code local runs:
@@ -102,10 +91,10 @@ For Claude Desktop plus Claude Code local runs:
 ```bash
 LC_AGENT_ROUTER_GPT_TARGET="claude_code"
 LC_AGENT_ROUTER_CODEX_TARGET="claude_code"
-LC_AGENT_CLAUDE_CODE_CWD="/absolute/path/to/the-folder-claude-code-should-build-into"
+launchchair bind --project-id PROJECT_UUID --cwd /absolute/path/to/verified-clone
 ```
 
-The build folder can be an empty scratch folder until Stack Setup creates or records the GitHub repository. After Stack Setup, the user should clone the generated repo locally or update the runner CWD to the cloned repo path.
+Pre-code work uses an isolated per-project scratch folder. After Stack Setup records the GitHub repository, the bridge auto-detects matching clones in standard repo folders and verifies the Git `origin`. If needed, clone the repo and run `launchchair bind`; code-changing runs fail closed until that verification succeeds.
 
 ## MCP Server Config Example
 
@@ -124,13 +113,12 @@ LAUNCHCHAIR_CONFIG_DIR = "/absolute/path/to/.launchchair"
 LAUNCHCHAIR_PROJECT_ID = ""
 LC_AGENT_ROUTER_GPT_TARGET = "codex"
 LC_AGENT_ROUTER_CODEX_TARGET = "codex"
-LC_AGENT_CODEX_CWD = "/absolute/path/to/the-folder-codex-should-build-into"
 
 # Optional fallback if launchchair login was skipped:
 # LAUNCHCHAIR_AGENT_TOKEN = "<full lc_at token from Settings API Access>"
 ```
 
-Prefer `launchchair setup codex --cwd /absolute/path/to/build-folder` so the CLI writes native config and verifies MCP tool discovery. Use `launchchair mcp-config codex --ui-fields` only for manual custom-form setup.
+Prefer `launchchair setup codex` so the CLI writes native config and verifies MCP tool discovery. Use `launchchair bind --project-id PROJECT_UUID --cwd /absolute/path/to/verified-clone` after cloning when automatic discovery cannot locate the repo. Use `launchchair mcp-config codex --ui-fields` only for manual custom-form setup.
 
 ## What To Do First In A Fresh Chat
 

package/README.md

@@ -49,59 +49,60 @@ Tokens are masked in CLI output. Do not paste real tokens into public docs, scre
 
 ## Guided Setup
 
-Use `setup` as the easiest path. It saves the build folder, writes a small `AGENTS.md` pointer into that folder, starts browser login when no token is saved yet, writes the MCP config for your agent, and then proves the server can complete MCP `initialize` and `tools/list` before reporting success.
+Use `setup` as the easiest path. It starts browser login when no token is saved yet, writes the global MCP config for your agent, creates isolated per-project workspaces, and then proves the server can complete MCP `initialize` and `tools/list` before reporting success.
 
 Codex Desktop:
 
 ```bash
-launchchair setup codex --cwd /absolute/path/to/repo-or-empty-folder
+launchchair setup codex
 ```
 
 If you prefer Codex Desktop's custom MCP form, copy paste-ready fields instead:
 
 ```bash
-launchchair setup codex --cwd /absolute/path/to/repo-or-empty-folder --copy-config
+launchchair setup codex --copy-config
 ```
 
 Claude Desktop + Claude Code (Claude Code is registered at user scope when its CLI is installed):
 
 ```bash
-launchchair setup claude --cwd /absolute/path/to/repo-or-empty-folder
+launchchair setup claude
 ```
 
 Configure only one Claude client when needed:
 
 ```bash
-launchchair setup claude-desktop --cwd /absolute/path/to/repo-or-empty-folder
-launchchair setup claude-code --cwd /absolute/path/to/repo-or-empty-folder
+launchchair setup claude-desktop
+launchchair setup claude-code
 ```
 
 Terminal / CLI agents:
 
 ```bash
-launchchair setup terminal --cwd /absolute/path/to/repo-or-empty-folder
+launchchair setup terminal
 ```
 
 If you do not want browser login during setup, add `--skip-login`. You can also save an existing token during setup:
 
 ```bash
-launchchair setup codex --cwd . --skip-login
-launchchair setup codex --cwd . --token "<full lc_at token from LaunchChair Settings API Access>"
+launchchair setup codex --skip-login
+launchchair setup codex --token "<full lc_at token from LaunchChair Settings API Access>"
 ```
 
 Setup writes client configuration by default. Use `--copy-config`, `--ui-fields`, or `--print-config` only when you intentionally want manual configuration. Authenticated setup exits nonzero if the MCP handshake or required tool discovery fails; `--skip-mcp-check` is an explicit diagnostic escape hatch, not the recommended first-run path.
 
-For a fresh project before a repo exists, point `--cwd` at an empty folder. LaunchChair can run ideation, validation, positioning, pricing, and MVP blueprint before code exists; Stack Setup and Build MVP can later use that folder as the build target.
+Fresh projects automatically use an isolated folder under `~/.launchchair/projects/<project-id>/workspace` before a repo exists. After Stack Setup, LaunchChair looks for the repo by its recorded Git URL in standard local repo folders and verifies the `origin` before switching. If it cannot find the clone, code work stops with an exact clone and `launchchair bind` instruction instead of using another project.
 
-Use `setup terminal` when the agent runs inside a normal shell instead of Codex Desktop or Claude Desktop MCP. It writes the same project-local `AGENTS.md` pointer, saves the build folder, and prints the CLI commands the agent should use: `launchchair projects`, `launchchair create`, `launchchair continue`, `launchchair run-once`, and `launchchair bridge`.
+Use `setup terminal` when the agent runs inside a normal shell instead of Codex Desktop or Claude Desktop MCP. It installs the user-scoped bootstrap and prints the CLI commands the agent should use: `launchchair projects`, `launchchair create`, `launchchair continue`, `launchchair run-once`, and `launchchair bridge`.
 
 ## Common Commands
 
 ```bash
-launchchair setup codex --cwd /absolute/path/to/repo-or-empty-folder
-launchchair setup claude --cwd /absolute/path/to/repo-or-empty-folder
-launchchair setup claude-code --cwd /absolute/path/to/repo-or-empty-folder
-launchchair setup terminal --cwd /absolute/path/to/repo-or-empty-folder
+launchchair setup codex
+launchchair setup claude
+launchchair setup claude-code
+launchchair setup terminal
+launchchair bind --project-id <project-id> --cwd /absolute/path/to/verified-clone
 launchchair projects
 launchchair projects --query LeafLore
 launchchair scorecards --project-id <project-id>
@@ -114,7 +115,7 @@ launchchair bridge
 launchchair mcp-config codex
 launchchair mcp-config codex --ui-fields --copy-config
 launchchair mcp-config claude
-launchchair install-agent-md --cwd /absolute/path/to/repo-or-empty-folder
+launchchair install-agent-md --cwd /absolute/path/to/repo
 ```
 
 Feature projects can be created and planned from the CLI for every authenticated LaunchChair workspace:
@@ -175,17 +176,17 @@ launchchair run-once
 
 ## Runner Targets
 
-Codex:
+Codex routes are selected globally, while repository paths are bound per LaunchChair project:
 
 ```bash
-launchchair config set codex-cwd /absolute/path/to/repo-or-empty-folder
+launchchair bind --project-id <project-id> --cwd /absolute/path/to/verified-clone
 launchchair bridge
 ```
 
 Claude Code:
 
 ```bash
-launchchair config set claude-code-cwd /absolute/path/to/repo-or-empty-folder
+launchchair bind --project-id <project-id> --cwd /absolute/path/to/verified-clone
 LC_AGENT_ROUTER_GPT_TARGET=claude_code LC_AGENT_ROUTER_CODEX_TARGET=claude_code launchchair bridge
 ```
 

package/launchchair-cli.mjs

@@ -14,8 +14,13 @@ import os from "node:os";
 import path from "node:path";
 import process from "node:process";
 import { fileURLToPath } from "node:url";
+import {
+  bindProjectWorkspace,
+  listProjectWorkspaceBindings,
+  unbindProjectWorkspace,
+} from "./project-workspace.mjs";
 
-const VERSION = "0.4.10";
+const VERSION = "0.4.12";
 const SCRIPT_DIR = path.dirname(fileURLToPath(import.meta.url));
 const DEFAULT_BASE_URL = "https://www.launchchair.io";
 const CONFIG_DIR = process.env.LAUNCHCHAIR_CONFIG_DIR?.trim()
@@ -179,9 +184,11 @@ Commands:
   bridge                          Start the long-running local bridge for Run with Agent
   mcp-server                      Run the stdio MCP server using saved CLI config
   setup codex|claude|claude-desktop|claude-code|terminal [options]
-                                  Guided setup for CLI, CWD, AGENTS.md, MCP config, and bridge
+                                  Guided global CLI/MCP setup with isolated project workspaces
+  bind --project-id ID --cwd PATH Bind one LaunchChair project to a verified local Git clone
+  unbind --project-id ID           Remove one project's saved local repository binding
   config                          Show local CLI config without printing the token
-  config set KEY VALUE             Save base-url, project-id, codex-cwd, or claude-code-cwd
+  config set KEY VALUE             Save base-url or project-id
   mcp-config codex|claude [options]
                                   Print MCP config or Codex custom MCP form fields
   install-agent-md [--cwd PATH]   Create a small AGENTS.md pointer in a fresh repo
@@ -215,7 +222,7 @@ Continue options:
   --completion-target TEXT        Natural-language target for the loop run
 
 Setup options:
-  --cwd PATH                      Repo folder or empty folder the agent should build into
+  --cwd PATH                      Bind this repo only when --project-id is also supplied
   --token TOKEN                   Optional manual lc_at token fallback to save during setup
   --project-id ID                 Optional default LaunchChair project id
   --base-url URL                  Optional LaunchChair base URL
@@ -241,8 +248,8 @@ Env:
   LAUNCHCHAIR_AGENT_TOKEN         Optional full lc_at token override
   LAUNCHCHAIR_BASE_URL            Default: https://www.launchchair.io
   LAUNCHCHAIR_PROJECT_ID          Optional default project id
-  LC_AGENT_CODEX_CWD              Folder Codex should build into
-  LC_AGENT_CLAUDE_CODE_CWD        Folder Claude Code should build into
+  LC_AGENT_CODEX_CWD              Legacy candidate only; verified per project before use
+  LC_AGENT_CLAUDE_CODE_CWD        Legacy candidate only; verified per project before use
 
 MCP config options:
   --ui-fields                     Print fields for Codex Desktop's custom MCP form
@@ -767,9 +774,9 @@ function buildBridgeEnv(projectId = defaultProjectId()) {
     LAUNCHCHAIR_CONFIG_DIR: CONFIG_DIR,
     LAUNCHCHAIR_AGENT_TOKEN: token(),
     LAUNCHCHAIR_PROJECT_ID: projectId,
-    LC_AGENT_CODEX_CWD: configValue("codexCwd", ["LC_AGENT_CODEX_CWD"], ""),
-    LC_AGENT_CLAUDE_CODE_CWD: configValue("claudeCodeCwd", ["LC_AGENT_CLAUDE_CODE_CWD"], ""),
   };
+  delete childEnv.LC_AGENT_CODEX_CWD;
+  delete childEnv.LC_AGENT_CLAUDE_CODE_CWD;
   Object.keys(childEnv).forEach((key) => {
     if (childEnv[key] === undefined || childEnv[key] === null || childEnv[key] === "") {
       delete childEnv[key];
@@ -881,7 +888,6 @@ function mcpEnvForTarget(target, options = {}) {
   const includeTokenPlaceholder = options.includeTokenPlaceholder !== false;
   const details = targetDetails(target || "codex");
   const projectId = defaultProjectId();
-  const cwd = configValue(details.cwdConfigKey, [details.cwdEnvName], "/absolute/path/to/repo-or-empty-folder");
   const envBlock = {
     LAUNCHCHAIR_BASE_URL: baseUrl(),
     LAUNCHCHAIR_CONFIG_DIR: CONFIG_DIR,
@@ -889,7 +895,6 @@ function mcpEnvForTarget(target, options = {}) {
     ...(projectId ? { LAUNCHCHAIR_PROJECT_ID: projectId } : {}),
     LC_AGENT_ROUTER_GPT_TARGET: details.routerTarget,
     LC_AGENT_ROUTER_CODEX_TARGET: details.routerTarget,
-    [details.cwdEnvName]: cwd,
   };
   return Object.fromEntries(Object.entries(envBlock).filter(([, value]) => String(value ?? "").trim()));
 }
@@ -1025,13 +1030,12 @@ ${envLines}`;
 
 function renderMcpUiFields(target) {
   const normalized = normalizedMcpTarget(target);
-  const details = targetDetails(normalized);
   const server = mcpServerConfig(normalized);
   const envLines =
     Object.entries(server.env)
       .map(([key, value]) => `  ${key} = ${value}`)
       .join("\n") || "  (none)";
-  const workingDir = server.env[details.cwdEnvName] || process.cwd();
+  const workingDir = path.join(CONFIG_DIR, "projects");
   return `Name
   launchchair
 
@@ -1173,14 +1177,20 @@ function printMcpConfig(target, args = {}) {
 
 function showConfig() {
   const config = loadConfig();
+  const bindings = listProjectWorkspaceBindings(CONFIG_PATH);
   title("CLI config");
   row("Path", CONFIG_PATH, existsSync(CONFIG_PATH) ? "dim" : "yellow");
   row("Base URL", baseUrl(), "cyan");
   row("Token", maskToken(token()), token() ? "green" : "yellow");
   row("Token source", tokenSource(), token() ? "green" : "yellow");
   row("Project ID", defaultProjectId() || "not set", defaultProjectId() ? "cyan" : "dim");
-  row("Codex CWD", configValue("codexCwd", ["LC_AGENT_CODEX_CWD"], "not set"), config.codexCwd || env("LC_AGENT_CODEX_CWD") ? "cyan" : "dim");
-  row("Claude Code CWD", configValue("claudeCodeCwd", ["LC_AGENT_CLAUDE_CODE_CWD"], "not set"), config.claudeCodeCwd || env("LC_AGENT_CLAUDE_CODE_CWD") ? "cyan" : "dim");
+  row("Project bindings", Object.keys(bindings).length, Object.keys(bindings).length > 0 ? "cyan" : "dim");
+  for (const [projectId, binding] of Object.entries(bindings)) {
+    row(`  ${projectId.slice(0, 12)}`, typeof binding === "string" ? binding : binding?.path ?? "invalid", "cyan");
+  }
+  if (config.codexCwd || config.claudeCodeCwd || env("LC_AGENT_CODEX_CWD") || env("LC_AGENT_CLAUDE_CODE_CWD")) {
+    row("Legacy CWD", "ignored unless its Git origin matches the current project", "yellow");
+  }
 }
 
 function setConfig(args) {
@@ -1189,16 +1199,50 @@ function setConfig(args) {
   const allowed = {
     "base-url": "baseUrl",
     "project-id": "projectId",
-    "codex-cwd": "codexCwd",
-    "claude-code-cwd": "claudeCodeCwd",
   };
   if (!key || !value || !allowed[key]) {
-    throw new Error("Usage: launchchair config set base-url|project-id|codex-cwd|claude-code-cwd VALUE");
+    throw new Error("Usage: launchchair config set base-url|project-id VALUE. Use launchchair bind for local repositories.");
   }
   saveConfig({ [allowed[key]]: key === "base-url" ? value.replace(/\/+$/, "") : value });
   ok(`Saved ${key} to ${CONFIG_PATH}`);
 }
 
+async function getRunnerWorkspaceContext(projectId) {
+  const payload = await api(`/api/agent/v1/projects/${encodeURIComponent(projectId)}/runner-workspace`);
+  return payload?.workspace && typeof payload.workspace === "object" ? payload.workspace : { projectId };
+}
+
+async function bindProject(args) {
+  const projectId = String(args["project-id"] || defaultProjectId() || "").trim();
+  const cwd = String(args.cwd || "").trim();
+  if (!projectId || !cwd) {
+    throw new Error("Usage: launchchair bind --project-id ID --cwd /absolute/path/to/repo");
+  }
+  const context = await getRunnerWorkspaceContext(projectId);
+  const repository = context?.repository && typeof context.repository === "object" ? context.repository : {};
+  const binding = bindProjectWorkspace({
+    configPath: CONFIG_PATH,
+    projectId,
+    cwd,
+    repositoryUrl: String(repository.repoUrl || repository.cloneUrl || "").trim(),
+  });
+  installAgentMd({ cwd: binding.path });
+  title("project repository bound");
+  row("Project ID", projectId, "cyan");
+  row("Local repository", binding.path, "cyan");
+  if (binding.repositoryUrl) row("Verified origin", binding.repositoryUrl, "green");
+  ok("Future runs for this LaunchChair project will use this repository.");
+  ok("Already-running bridges will pick up this binding on the next run.");
+}
+
+function unbindProject(args) {
+  const projectId = String(args["project-id"] || defaultProjectId() || "").trim();
+  if (!projectId) throw new Error("Usage: launchchair unbind --project-id ID");
+  const existed = unbindProjectWorkspace({ configPath: CONFIG_PATH, projectId });
+  if (existed) ok(`Removed local repository binding for ${projectId}.`);
+  else warn(`No local repository binding existed for ${projectId}.`);
+}
+
 function installAgentMd(args) {
   const cwd = path.resolve(String(args.cwd || process.cwd()));
   const target = path.join(cwd, "AGENTS.md");
@@ -1258,17 +1302,23 @@ function installLaunchChairSkill(args) {
 
 async function setup(args) {
   const details = targetDetails(args._[0] || "codex");
-  const cwd = path.resolve(String(args.cwd || process.cwd()));
+  const requestedCwd = typeof args.cwd === "string" && args.cwd.trim() ? path.resolve(args.cwd.trim()) : "";
   const writeConfig =
     args["write-config"] === true ||
     (args["copy-config"] !== true && args["ui-fields"] !== true && args["print-config"] !== true);
   const incomingToken = typeof args.token === "string" ? args.token.trim() : "";
   const incomingBaseUrl = typeof args["base-url"] === "string" ? args["base-url"].trim().replace(/\/+$/, "") : undefined;
   const incomingProjectId = typeof args["project-id"] === "string" ? args["project-id"].trim() : "";
+  const bindingProjectId = incomingProjectId || defaultProjectId();
+
+  if (requestedCwd && !bindingProjectId) {
+    throw new Error("--cwd must be paired with --project-id. Global runner directories are no longer supported.");
+  }
 
   title(`guided setup for ${details.label}`);
-  mkdirSync(cwd, { recursive: true });
-  ok(`Build folder ready: ${cwd}`);
+  const projectWorkspaceRoot = path.join(CONFIG_DIR, "projects");
+  mkdirSync(projectWorkspaceRoot, { recursive: true, mode: 0o700 });
+  ok(`Isolated project workspace root ready: ${projectWorkspaceRoot}`);
 
   if (incomingToken) {
     if (!incomingToken.startsWith("lc_at_")) {
@@ -1287,10 +1337,6 @@ async function setup(args) {
     });
   }
 
-  saveConfig({ [details.cwdConfigKey]: cwd });
-  ok(`Saved ${details.cwdEnvName}: ${cwd}`);
-  installAgentMd({ cwd });
-
   if (!token() && args["skip-login"] !== true) {
     print("");
     warn("No saved LaunchChair token found. Starting browser approval now.");
@@ -1306,8 +1352,12 @@ async function setup(args) {
     });
   }
 
+  if (requestedCwd) {
+    await bindProject({ "project-id": bindingProjectId, cwd: requestedCwd });
+  }
+
   if (details.mcpTarget === "codex") {
-    installLaunchChairSkill({ cwd });
+    installLaunchChairSkill({ cwd: path.dirname(CONFIG_DIR) });
   }
 
   print("");
@@ -1410,7 +1460,7 @@ async function setup(args) {
     print("Start a fresh agent chat. The agent should discover the LaunchChair MCP tools automatically.");
   }
   print("");
-  row("Build folder", cwd, "cyan");
+  row("Workspace mode", requestedCwd ? `project-bound: ${requestedCwd}` : "isolated per LaunchChair project", "cyan");
   row("Runner target", details.routerTarget, "cyan");
   row("Config file", CONFIG_PATH, "dim");
 
@@ -1441,6 +1491,8 @@ async function main() {
   if (command === "bridge") return spawnBridge(["--verbose"]);
   if (command === "mcp-server") return spawnMcpServer();
   if (command === "setup") return setup(args);
+  if (command === "bind") return bindProject(args);
+  if (command === "unbind") return unbindProject(args);
   if (command === "config" && args._[0] === "set") return setConfig({ ...args, _: args._.slice(1) });
   if (command === "config") return showConfig();
   if (command === "mcp-config") return printMcpConfig(args._[0] || "codex", args);

package/local-bridge.mjs

@@ -15,9 +15,10 @@ import os from "node:os";
 import path from "node:path";
 import process from "node:process";
 import { fileURLToPath } from "node:url";
+import { resolveProjectWorkspace } from "./project-workspace.mjs";
 import { buildRunnerCommand, parseRunnerCommand } from "./runner-command.mjs";
 
-const VERSION = "0.4.10";
+const VERSION = "0.4.12";
 const CLIENT_TYPES = ["codex", "chatgpt", "claude", "claude_code", "other"];
 const AGENT_SCRIPT_DIR = path.dirname(fileURLToPath(import.meta.url));
 const CONFIG_DIR = process.env.LAUNCHCHAIR_CONFIG_DIR?.trim()
@@ -130,10 +131,10 @@ Optional env:
   AGENT_MOCK_RESPONSE            If set, skips runner command and returns this payload
   OPENAI_API_KEY                 Enables built-in ChatGPT runner fallback
   ANTHROPIC_API_KEY              Enables built-in Claude runner fallback
-  LC_AGENT_CODEX_CWD             Folder codex-runner should build in (default: bridge cwd)
+  LC_AGENT_CODEX_CWD             Legacy search candidate; Git origin must match the project
   LC_AGENT_CODEX_SANDBOX         read-only|workspace-write|danger-full-access (default: workspace-write)
   LC_AGENT_CODEX_MODEL           Optional Codex model override
-  LC_AGENT_CLAUDE_CODE_CWD       Folder claude-code-runner should build in (default: bridge cwd)
+  LC_AGENT_CLAUDE_CODE_CWD       Legacy search candidate; Git origin must match the project
   LC_AGENT_CLAUDE_CODE_MODEL     Optional Claude Code model override
   LC_AGENT_CLAUDE_CODE_ALLOWED_TOOLS
                                  Optional Claude Code allowedTools list
@@ -193,6 +194,10 @@ const config = {
     gpt: normalizeTarget(env("LC_AGENT_ROUTER_GPT_TARGET", "codex"), "codex"),
     codex: normalizeTarget(env("LC_AGENT_ROUTER_CODEX_TARGET", "codex"), "codex"),
   },
+  legacyRepoPaths: {
+    codex: env("LC_AGENT_CODEX_CWD", savedConfigValue("codexCwd", process.cwd())),
+    claudeCode: env("LC_AGENT_CLAUDE_CODE_CWD", savedConfigValue("claudeCodeCwd", process.cwd())),
+  },
   runnerCommands: {
     generic: env("LC_AGENT_RUNNER_CMD"),
     gpt: env("LC_AGENT_RUNNER_CMD_GPT"),
@@ -347,6 +352,25 @@ async function claimNextRun() {
   return payload?.run ?? null;
 }
 
+function resolveWorkspaceForRun(run) {
+  const target = getTargetForRun(run) === "claude_code" ? "claude_code" : "codex";
+  const legacyPath = target === "claude_code" ? config.legacyRepoPaths.claudeCode : config.legacyRepoPaths.codex;
+  const context = run?.runnerWorkspace && typeof run.runnerWorkspace === "object" && !Array.isArray(run.runnerWorkspace)
+    ? run.runnerWorkspace
+    : {};
+  return {
+    target,
+    workspace: resolveProjectWorkspace({
+      configDir: CONFIG_DIR,
+      configPath: CONFIG_PATH,
+      projectId: String(run?.projectId ?? context.projectId ?? "").trim(),
+      repository: context.repository,
+      requireRepository: context.requiresRepository === true,
+      legacyPaths: [legacyPath],
+    }),
+  };
+}
+
 async function executeRunner(run) {
   if (config.mockResponse) {
     return {
@@ -367,6 +391,9 @@ async function executeRunner(run) {
   }
   const command = buildRunnerCommand(commandTemplate, run);
   const parsedCommand = parseRunnerCommand(command);
+  const resolved = resolveWorkspaceForRun(run);
+  const workspaceEnvName = resolved.target === "claude_code" ? "LC_AGENT_CLAUDE_CODE_CWD" : "LC_AGENT_CODEX_CWD";
+  log(`Workspace ${resolved.workspace.path} (${resolved.workspace.source})`);
 
   const startedAt = Date.now();
   return new Promise((resolve, reject) => {
@@ -382,6 +409,7 @@ async function executeRunner(run) {
         LC_AGENT_CARD_ID: String(run.cardId ?? ""),
         LC_AGENT_PROMPT_MODE: String(run.promptMode ?? ""),
         LC_AGENT_RUN_TYPE: String(run.runType ?? ""),
+        [workspaceEnvName]: resolved.workspace.path,
       },
     });
 
@@ -415,6 +443,7 @@ async function executeRunner(run) {
         durationMs,
         usedMock: false,
         target: getTargetForRun(run),
+        workspace: resolved.workspace,
       });
     });
 
@@ -480,6 +509,7 @@ async function runOnce() {
         runIntent: run.runIntent ?? "initial",
         attemptNumber: run.attemptNumber ?? 1,
         maxAttempts: run.maxAttempts ?? 1,
+        localWorkspaceSource: execution.workspace?.source ?? null,
       },
       error: null,
     });

package/mcp-bridge-server.mjs

@@ -17,9 +17,10 @@ import os from "node:os";
 import path from "node:path";
 import process from "node:process";
 import { fileURLToPath } from "node:url";
+import { resolveProjectWorkspace } from "./project-workspace.mjs";
 import { buildRunnerCommand, parseRunnerCommand } from "./runner-command.mjs";
 
-const VERSION = "0.4.10";
+const VERSION = "0.4.12";
 const SERVER_NAME = "launchchair-agent-mcp";
 const AGENT_SCRIPT_DIR = path.dirname(fileURLToPath(import.meta.url));
 const CONFIG_DIR = process.env.LAUNCHCHAIR_CONFIG_DIR?.trim()
@@ -27,7 +28,7 @@ const CONFIG_DIR = process.env.LAUNCHCHAIR_CONFIG_DIR?.trim()
   : path.join(os.homedir() || process.cwd(), ".launchchair");
 const CONFIG_PATH = path.join(CONFIG_DIR, "config.json");
 const BASE_SERVER_INSTRUCTIONS =
-  "Use LaunchChair MCP tools—not web browsing—for LaunchChair project discovery, creation, planning, validation scoring, and loops. Call the most specific available tool. When asked for validation scores, call launchchair_get_scorecards and report those scorecards; do not substitute generated direction-option scores. If a requested workflow is unavailable, explain the access or setup issue instead of silently substituting another project type or workflow.";
+  "Use LaunchChair MCP tools—not web browsing—for LaunchChair project discovery, creation, planning, validation scoring, and loops. Call the most specific available tool. When asked for validation scores, call launchchair_get_scorecards and report those scorecards; do not substitute generated direction-option scores. Always present completedPhaseLinks, selected choice URLs, and any upgradeUrl returned by a tool to the user as clickable links. If a requested workflow is unavailable, explain the access or setup issue instead of silently substituting another project type or workflow.";
 
 function nodeScriptCommand(scriptName) {
   return `${JSON.stringify(process.execPath)} ${JSON.stringify(path.join(AGENT_SCRIPT_DIR, scriptName))}`;
@@ -128,7 +129,7 @@ const config = {
     codexTarget: env("LC_AGENT_RUNNER_CMD_CODEX", builtInRunnerCommand("codex")),
     claudeCode: env("LC_AGENT_RUNNER_CMD_CLAUDE_CODE", builtInRunnerCommand("claude_code")),
   },
-  localRepoPaths: {
+  legacyRepoPaths: {
     codex: env("LC_AGENT_CODEX_CWD", savedConfigValue("codexCwd", process.cwd())),
     claudeCode: env("LC_AGENT_CLAUDE_CODE_CWD", savedConfigValue("claudeCodeCwd", process.cwd())),
   },
@@ -227,6 +228,32 @@ function commandForRun(run) {
   return config.runnerCommands.generic;
 }
 
+function runnerTargetForRun(run) {
+  return targetForRun(run) === "claude_code" ? "claude_code" : "codex";
+}
+
+function resolveWorkspaceForRun(run, workspaceContext = run?.runnerWorkspace, options = {}) {
+  const target = runnerTargetForRun(run);
+  const context = workspaceContext && typeof workspaceContext === "object" && !Array.isArray(workspaceContext)
+    ? workspaceContext
+    : {};
+  const legacyPath = target === "claude_code" ? config.legacyRepoPaths.claudeCode : config.legacyRepoPaths.codex;
+  return resolveProjectWorkspace({
+    configDir: CONFIG_DIR,
+    configPath: CONFIG_PATH,
+    projectId: String(run?.projectId ?? context.projectId ?? "").trim(),
+    repository: context.repository,
+    requireRepository: context.requiresRepository === true,
+    preferRepository: options.preferRepository === true,
+    legacyPaths: [legacyPath],
+  });
+}
+
+async function getRunnerWorkspaceContext(projectId) {
+  const payload = await api(`/api/agent/v1/projects/${encodeURIComponent(projectId)}/runner-workspace`);
+  return payload?.workspace && typeof payload.workspace === "object" ? payload.workspace : { projectId };
+}
+
 async function executeRunner(run) {
   if (config.mockResponse) {
     return {
@@ -245,6 +272,10 @@ async function executeRunner(run) {
   }
   const command = buildRunnerCommand(template, run);
   const parsedCommand = parseRunnerCommand(command);
+  const workspace = resolveWorkspaceForRun(run);
+  const workspaceEnvName = runnerTargetForRun(run) === "claude_code"
+    ? "LC_AGENT_CLAUDE_CODE_CWD"
+    : "LC_AGENT_CODEX_CWD";
   const startedAt = Date.now();
   return new Promise((resolve, reject) => {
     const child = spawn(parsedCommand.file, parsedCommand.args, {
@@ -259,6 +290,7 @@ async function executeRunner(run) {
         LC_AGENT_CARD_ID: String(run.cardId ?? ""),
         LC_AGENT_PROMPT_MODE: String(run.promptMode ?? ""),
         LC_AGENT_RUN_TYPE: String(run.runType ?? ""),
+        [workspaceEnvName]: workspace.path,
       },
     });
     let stdout = "";
@@ -286,6 +318,7 @@ async function executeRunner(run) {
         stderr,
         exitCode: code ?? 0,
         durationMs,
+        workspace,
       });
     });
     child.stdin.write(String(run.prompt ?? ""));
@@ -366,6 +399,7 @@ async function runOnce(args = {}) {
           runIntent: run.runIntent ?? "initial",
           attemptNumber: run.attemptNumber ?? 1,
           maxAttempts: run.maxAttempts ?? 1,
+          localWorkspaceSource: execution.workspace?.source ?? null,
         },
         error: null,
         clientName: String(args.clientName ?? "").trim() || config.clientName,
@@ -520,22 +554,35 @@ async function continueProjectLoop(args = {}) {
     typeof args.ideaSnapshot === "object" && args.ideaSnapshot !== null && !Array.isArray(args.ideaSnapshot)
       ? args.ideaSnapshot
       : null;
-  const runnerTarget = config.modeTargets.codex === "claude_code" ? "claude_code" : config.modeTargets.codex;
-  const localRepoPath =
-    runnerTarget === "claude_code" ? config.localRepoPaths.claudeCode : config.localRepoPaths.codex;
-  const agentSetup = {
-    localRepoPath,
-    runnerTarget,
-    clientType: config.clientType,
-    ...(typeof args.agentSetup === "object" && args.agentSetup !== null && !Array.isArray(args.agentSetup)
-      ? args.agentSetup
-      : {}),
+  const runnerTarget = config.modeTargets.codex === "claude_code" ? "claude_code" : "codex";
+  let runnerWorkspaceContext = await getRunnerWorkspaceContext(projectId);
+  let agentSetup = null;
+  const refreshAgentSetup = async () => {
+    runnerWorkspaceContext = await getRunnerWorkspaceContext(projectId);
+    const resolvedAgentWorkspace = resolveWorkspaceForRun(
+      { projectId, promptMode: "codex", runnerWorkspace: runnerWorkspaceContext },
+      runnerWorkspaceContext,
+      { preferRepository: true },
+    );
+    agentSetup = {
+      ...(typeof args.agentSetup === "object" && args.agentSetup !== null && !Array.isArray(args.agentSetup)
+        ? args.agentSetup
+        : {}),
+      localRepoPath: resolvedAgentWorkspace.path,
+      runnerTarget,
+      clientType: config.clientType,
+      repositoryVerified: resolvedAgentWorkspace.repositoryVerified,
+      repositoryUrl: resolvedAgentWorkspace.repositoryUrl,
+      workspaceSource: resolvedAgentWorkspace.source,
+    };
   };
+  await refreshAgentSetup();
   let pendingChoiceSelections = normalizeChoiceSelections(args);
   const steps = [];
   let final = null;
 
   for (let index = 0; index < maxSteps; index += 1) {
+    if (index > 0) await refreshAgentSetup();
     const loop = await api(`/api/agent/v1/projects/${encodeURIComponent(projectId)}/loop/continue`, {
       method: "POST",
       body: {
@@ -553,7 +600,9 @@ async function continueProjectLoop(args = {}) {
       break;
     }
 
-    const run = loop.run;
+    const run = loop.run
+      ? { ...loop.run, runnerWorkspace: loop.runnerWorkspace ?? runnerWorkspaceContext }
+      : null;
     if (!run?.id || !run?.prompt) {
       final = loop;
       break;
@@ -578,6 +627,7 @@ async function continueProjectLoop(args = {}) {
           attemptNumber: run.attemptNumber ?? 1,
           maxAttempts: run.maxAttempts ?? 1,
           projectLoopStep: index + 1,
+          localWorkspaceSource: execution.workspace?.source ?? null,
         },
         error: null,
         clientName: String(args.clientName ?? "").trim() || config.clientName,
@@ -1096,6 +1146,9 @@ async function handleRpc(request) {
       }
       writeError(id, -32601, `Unknown tool: ${toolName}`);
     } catch (error) {
+      const errorPayload = error?.payload && typeof error.payload === "object" && !Array.isArray(error.payload)
+        ? error.payload
+        : {};
       writeResult(id, {
         content: [
           {
@@ -1103,6 +1156,11 @@ async function handleRpc(request) {
             text: JSON.stringify(
               {
                 error: error instanceof Error ? error.message : String(error ?? "Tool failed"),
+                ...errorPayload,
+                ...(Number.isFinite(error?.status) ? { httpStatus: error.status } : {}),
+                ...(Number.isFinite(error?.retryAfterSeconds)
+                  ? { retryAfterSeconds: error.retryAfterSeconds }
+                  : {}),
               },
               null,
               2,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@launchchair/agent",
-  "version": "0.4.10",
+  "version": "0.4.12",
   "mcpName": "io.launchchair/agent",
   "description": "LaunchChair Agent CLI, MCP bridge, local bridge, and runners for Codex, Claude Code, ChatGPT, Claude, and Hermes workflows.",
   "type": "module",
@@ -15,6 +15,7 @@
     "launchchair-cli.mjs",
     "local-bridge.mjs",
     "mcp-bridge-server.mjs",
+    "project-workspace.mjs",
     "runner-command.mjs",
     "codex-runner.mjs",
     "claude-code-runner.mjs",

package/project-workspace.mjs

@@ -0,0 +1,306 @@
+import {
+  chmodSync,
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  renameSync,
+  statSync,
+  unlinkSync,
+  writeFileSync,
+} from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+function asRecord(value) {
+  return value && typeof value === "object" && !Array.isArray(value) ? value : {};
+}
+
+function text(value) {
+  return typeof value === "string" ? value.trim() : "";
+}
+
+function readConfig(configPath) {
+  try {
+    const parsed = JSON.parse(readFileSync(configPath, "utf8"));
+    return asRecord(parsed);
+  } catch {
+    return {};
+  }
+}
+
+function writeConfig(configPath, next) {
+  const directory = path.dirname(configPath);
+  mkdirSync(directory, { recursive: true, mode: 0o700 });
+  const temporary = path.join(directory, `.${path.basename(configPath)}.${process.pid}.${Date.now()}.tmp`);
+  try {
+    writeFileSync(temporary, `${JSON.stringify(next, null, 2)}\n`, { mode: 0o600 });
+    renameSync(temporary, configPath);
+    try {
+      chmodSync(configPath, 0o600);
+    } catch {
+      // Best effort for filesystems without POSIX permissions.
+    }
+  } finally {
+    if (existsSync(temporary)) unlinkSync(temporary);
+  }
+}
+
+function safeProjectKey(projectId) {
+  const value = text(projectId);
+  if (!value) throw new Error("LaunchChair projectId is required to resolve a local workspace.");
+  return value.replace(/[^a-zA-Z0-9._-]/g, "_").slice(0, 160);
+}
+
+export function normalizeGitRemote(value) {
+  let remote = text(value);
+  if (!remote) return "";
+  if (remote.startsWith("git@")) {
+    const match = remote.match(/^git@([^:]+):(.+)$/);
+    if (match) remote = `https://${match[1]}/${match[2]}`;
+  } else if (remote.startsWith("ssh://git@")) {
+    remote = remote.replace(/^ssh:\/\/git@/, "https://");
+  }
+  try {
+    const parsed = new URL(remote);
+    const pathname = parsed.pathname.replace(/^\/+/, "").replace(/\/+$/, "").replace(/\.git$/i, "");
+    return `${parsed.hostname.toLowerCase()}/${pathname.toLowerCase()}`;
+  } catch {
+    return remote.replace(/\.git$/i, "").replace(/\/+$/, "").toLowerCase();
+  }
+}
+
+export function repositoryNameFromUrl(value) {
+  const normalized = normalizeGitRemote(value);
+  return normalized.split("/").filter(Boolean).at(-1) ?? "";
+}
+
+function gitDirectory(repoPath) {
+  const dotGit = path.join(repoPath, ".git");
+  if (!existsSync(dotGit)) return "";
+  try {
+    if (statSync(dotGit).isDirectory()) return dotGit;
+    const pointer = readFileSync(dotGit, "utf8").match(/^gitdir:\s*(.+)$/im)?.[1]?.trim();
+    if (!pointer) return "";
+    return path.resolve(repoPath, pointer);
+  } catch {
+    return "";
+  }
+}
+
+export function readGitOrigin(repoPath) {
+  const gitDir = gitDirectory(repoPath);
+  if (!gitDir) return "";
+  try {
+    const raw = readFileSync(path.join(gitDir, "config"), "utf8");
+    const remoteBlock = raw.match(/\[remote\s+"origin"\]([\s\S]*?)(?=\n\[|$)/i)?.[1] ?? "";
+    return remoteBlock.match(/^\s*url\s*=\s*(.+)$/im)?.[1]?.trim() ?? "";
+  } catch {
+    return "";
+  }
+}
+
+function projectBindings(config) {
+  return asRecord(config.projectWorkspaces);
+}
+
+function bindingPath(config, projectId) {
+  const value = projectBindings(config)[projectId];
+  if (typeof value === "string") return text(value);
+  return text(asRecord(value).path);
+}
+
+function repositoryMatches(repoPath, expectedRepositoryUrl) {
+  const origin = readGitOrigin(repoPath);
+  if (!origin) return false;
+  const expected = normalizeGitRemote(expectedRepositoryUrl);
+  return !expected || normalizeGitRemote(origin) === expected;
+}
+
+function standardSearchRoots(config, legacyPaths = [], extraRoots = []) {
+  const home = os.homedir();
+  const configuredRoots = Array.isArray(config.repoSearchRoots) ? config.repoSearchRoots.map(text) : [];
+  const bindingParents = Object.values(projectBindings(config))
+    .map((value) => (typeof value === "string" ? value : asRecord(value).path))
+    .map(text)
+    .filter(Boolean)
+    .map((value) => path.dirname(path.resolve(value)));
+  const legacyParents = legacyPaths.map(text).filter(Boolean).map((value) => path.dirname(path.resolve(value)));
+  const legacyRoots = legacyPaths.map(text).filter(Boolean).map((value) => path.resolve(value));
+  return Array.from(
+    new Set(
+      [
+        ...extraRoots,
+        ...configuredRoots,
+        ...bindingParents,
+        ...legacyRoots,
+        ...legacyParents,
+        home ? path.join(home, "Documents", "GitHub") : "",
+        home ? path.join(home, "Developer") : "",
+        home ? path.join(home, "Projects") : "",
+        home ? path.join(home, "repos") : "",
+      ]
+        .map(text)
+        .filter(Boolean)
+        .map((value) => path.resolve(value)),
+    ),
+  );
+}
+
+function saveBinding(configPath, projectId, repoPath, repositoryUrl, source) {
+  const config = readConfig(configPath);
+  const bindings = projectBindings(config);
+  const next = {
+    ...config,
+    projectWorkspaces: {
+      ...bindings,
+      [projectId]: {
+        path: path.resolve(repoPath),
+        repositoryUrl: text(repositoryUrl) || text(asRecord(bindings[projectId]).repositoryUrl) || undefined,
+        source,
+        updatedAt: new Date().toISOString(),
+      },
+    },
+  };
+  writeConfig(configPath, next);
+  return next.projectWorkspaces[projectId];
+}
+
+export function bindProjectWorkspace({ configPath, projectId, cwd, repositoryUrl = "", source = "explicit" }) {
+  const id = text(projectId);
+  safeProjectKey(id);
+  const resolved = path.resolve(text(cwd));
+  if (!existsSync(resolved) || !statSync(resolved).isDirectory()) {
+    throw new Error(`Local project directory does not exist: ${resolved}`);
+  }
+  const expected = text(repositoryUrl);
+  const origin = readGitOrigin(resolved);
+  if (expected && !origin) {
+    throw new Error(`The selected directory is not a Git clone. Expected ${expected}.`);
+  }
+  if (expected && normalizeGitRemote(origin) !== normalizeGitRemote(expected)) {
+    throw new Error(`Git origin mismatch. Expected ${expected}, found ${origin || "no origin"}.`);
+  }
+  return saveBinding(configPath, id, resolved, expected || origin, source);
+}
+
+export function unbindProjectWorkspace({ configPath, projectId }) {
+  const id = text(projectId);
+  safeProjectKey(id);
+  const config = readConfig(configPath);
+  const bindings = { ...projectBindings(config) };
+  const existed = Object.prototype.hasOwnProperty.call(bindings, id);
+  delete bindings[id];
+  writeConfig(configPath, { ...config, projectWorkspaces: bindings });
+  return existed;
+}
+
+export function listProjectWorkspaceBindings(configPath) {
+  return projectBindings(readConfig(configPath));
+}
+
+export function isolatedProjectWorkspace(configDir, projectId) {
+  const key = safeProjectKey(projectId);
+  const target = path.join(configDir, "projects", key, "workspace");
+  mkdirSync(target, { recursive: true, mode: 0o700 });
+  const instructionsPath = path.join(target, "AGENTS.md");
+  if (!existsSync(instructionsPath)) {
+    writeFileSync(
+      instructionsPath,
+      [
+        "# LaunchChair isolated project workspace",
+        "",
+        `This folder belongs only to LaunchChair project ${projectId}.`,
+        "Use the LaunchChair prompt and MCP/API context for pre-code work.",
+        "Do not inspect, edit, or execute against unrelated repositories.",
+        "Before code-changing work, bind a verified local Git clone with `launchchair bind --project-id <id> --cwd <path>`.",
+        "",
+      ].join("\n"),
+      { mode: 0o600 },
+    );
+  }
+  return target;
+}
+
+export function resolveProjectWorkspace({
+  configDir,
+  configPath,
+  projectId,
+  repository = {},
+  requireRepository = false,
+  preferRepository = false,
+  legacyPaths = [],
+  searchRoots = [],
+}) {
+  const id = text(projectId);
+  safeProjectKey(id);
+  const config = readConfig(configPath);
+  const repo = asRecord(repository);
+  const repositoryUrl = text(repo.repoUrl) || text(repo.cloneUrl);
+  const cloneUrl = text(repo.cloneUrl) || repositoryUrl;
+  const repoName = text(repo.repoName) || repositoryNameFromUrl(repositoryUrl);
+  const boundPath = bindingPath(config, id);
+  const scratchPath = isolatedProjectWorkspace(configDir, id);
+
+  if (!requireRepository && !preferRepository) {
+    return {
+      path: scratchPath,
+      source: "isolated",
+      repositoryVerified: false,
+      repositoryUrl,
+      cloneUrl,
+    };
+  }
+
+  if (!repositoryUrl) {
+    if (requireRepository) {
+      throw new Error(
+        `LaunchChair project ${id} does not have repository metadata yet. Finish Stack Setup before running code-changing work.`,
+      );
+    }
+    return {
+      path: scratchPath,
+      source: "isolated",
+      repositoryVerified: false,
+      repositoryUrl: "",
+      cloneUrl: "",
+    };
+  }
+
+  const candidates = [boundPath, scratchPath, ...legacyPaths.map(text).filter(Boolean)];
+
+  if (repoName) {
+    for (const root of standardSearchRoots(config, legacyPaths, searchRoots)) {
+      candidates.push(path.join(root, repoName));
+    }
+  }
+
+  for (const candidate of Array.from(new Set(candidates.filter(Boolean).map((value) => path.resolve(value))))) {
+    if (!existsSync(candidate)) continue;
+    if (!repositoryMatches(candidate, repositoryUrl)) continue;
+    const source = candidate === boundPath ? "binding" : "auto_detected";
+    if (candidate !== boundPath) saveBinding(configPath, id, candidate, repositoryUrl || readGitOrigin(candidate), source);
+    return {
+      path: candidate,
+      source,
+      repositoryVerified: true,
+      repositoryUrl: repositoryUrl || readGitOrigin(candidate),
+      cloneUrl,
+    };
+  }
+
+  if (requireRepository) {
+    const expected = repositoryUrl ? ` for ${repositoryUrl}` : "";
+    const cloneStep = cloneUrl && repoName ? ` Clone it with: git clone ${cloneUrl} \"${repoName}\".` : "";
+    throw new Error(
+      `No verified local Git clone is bound to LaunchChair project ${id}${expected}.${cloneStep} Then run: launchchair bind --project-id ${id} --cwd \"/absolute/path/to/${repoName || "repo"}\"`,
+    );
+  }
+
+  return {
+    path: scratchPath,
+    source: "isolated",
+    repositoryVerified: false,
+    repositoryUrl,
+    cloneUrl,
+  };
+}

package/server.json

@@ -3,13 +3,13 @@
   "name": "io.launchchair/agent",
   "title": "LaunchChair",
   "description": "Plan, validate, and build products and features with LaunchChair.",
-  "version": "0.4.10",
+  "version": "0.4.12",
   "websiteUrl": "https://www.launchchair.io/docs/mcp",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "@launchchair/agent",
-      "version": "0.4.10",
+      "version": "0.4.12",
       "runtimeHint": "npx",
       "runtimeArguments": [
         {