codex-webstrapper 0.1.1 → 0.2.0

package/README.md

@@ -75,6 +75,8 @@ This project provides near-parity by emulation/bridging, not by removing those d
 
 ```bash
 codex-webstrap [--port <n>] [--bind <ip>] [--open] [--token-file <path>] [--codex-app <path>]
+codex-webstrapper [--port <n>] [--bind <ip>] [--open] [--token-file <path>] [--codex-app <path>]
+codex-webstrapper open [--port <n>] [--bind <ip>] [--token-file <path>] [--copy]
 ```
 
 ### Environment Overrides
@@ -112,7 +114,12 @@ codex-webstrap [--port <n>] [--bind <ip>] [--open] [--token-file <path>] [--code
 - macOS
 - Node.js 20+
 - Installed Codex app bundle at `/Applications/Codex.app` (or pass `--codex-app`)
-- `codex` CLI available in `PATH` (or set `CODEX_CLI_PATH`)
+
+By default, webstrapper runs the app-server via the bundled desktop CLI at:
+- `/Applications/Codex.app/Contents/Resources/codex`
+
+Optional override:
+- `CODEX_CLI_PATH=/custom/codex`
 
 ### Install
 
@@ -131,7 +138,7 @@ npm install -g codex-webstrapper
 With global install:
 
 ```bash
-codex-webstrap --port 8080 --bind 127.0.0.1
+codex-webstrapper --port 8080 --bind 127.0.0.1
 ```
 
 From local checkout:
@@ -143,7 +150,19 @@ From local checkout:
 Optional auto-open:
 
 ```bash
-codex-webstrap --open
+codex-webstrapper --open
+```
+
+Generate/open the full auth URL from your persisted token:
+
+```bash
+codex-webstrapper open
+```
+
+Copy the full auth URL (including token) to macOS clipboard:
+
+```bash
+codex-webstrapper open --copy
 ```
 
 ## Authentication Model
@@ -155,6 +174,12 @@ codex-webstrap --open
 open "http://127.0.0.1:8080/__webstrapper/auth?token=$(cat ~/.codex-webstrap/token)"
 ```
 
+Or use the helper command:
+
+```bash
+codex-webstrapper open
+```
+
 3. Server sets `cw_session` cookie (`HttpOnly`, `SameSite=Lax`, scoped to `/`).
 4. UI and bridge endpoints require a valid session cookie.
 
@@ -232,7 +257,7 @@ Codex setup-script compatible command:
 - Codex app not found
   - Pass `--codex-app /path/to/Codex.app`.
 - `codex` CLI spawn failures
-  - Ensure `codex` is on `PATH` or set `CODEX_CLI_PATH`.
+  - Ensure the bundled CLI exists in your Codex app install, or set `CODEX_CLI_PATH`.
 
 ## License
 

package/bin/codex-webstrap.sh

@@ -17,40 +17,106 @@ OPEN_FLAG="0"
 TOKEN_FILE="${CODEX_WEBSTRAP_TOKEN_FILE:-}"
 CODEX_APP="${CODEX_WEBSTRAP_CODEX_APP:-}"
 INTERNAL_WS_PORT="${CODEX_WEBSTRAP_INTERNAL_WS_PORT:-38080}"
+PORT_SET="0"
+BIND_SET="0"
+COPY_FLAG="0"
+COMMAND="serve"
+
+# Treat non-empty env overrides as explicit selections so open-mode runtime
+# autodetection cannot replace them.
+if [[ -n "${CODEX_WEBSTRAP_PORT:-}" ]]; then
+  PORT_SET="1"
+fi
+if [[ -n "${CODEX_WEBSTRAP_BIND:-}" ]]; then
+  BIND_SET="1"
+fi
+
+DEFAULT_TOKEN_FILE="${HOME}/.codex-webstrap/token"
+if [[ -z "$TOKEN_FILE" ]]; then
+  TOKEN_FILE="$DEFAULT_TOKEN_FILE"
+fi
+
+print_usage() {
+  cat <<USAGE
+Usage:
+  $(basename "$0") [--port <n>] [--bind <ip>] [--open] [--token-file <path>] [--codex-app <path>]
+  $(basename "$0") open [--port <n>] [--bind <ip>] [--token-file <path>] [--copy]
+
+Commands:
+  open              Build the full auth URL and open it in the browser.
+
+Options for open:
+  --copy            Copy full auth URL to clipboard with pbcopy instead of launching browser.
+
+Env overrides:
+  CODEX_WEBSTRAP_PORT
+  CODEX_WEBSTRAP_BIND
+  CODEX_WEBSTRAP_TOKEN_FILE
+  CODEX_WEBSTRAP_CODEX_APP
+  CODEX_WEBSTRAP_INTERNAL_WS_PORT
+USAGE
+}
+
+require_value() {
+  local flag="$1"
+  local value="${2:-}"
+  if [[ -z "$value" ]]; then
+    echo "Missing value for ${flag}" >&2
+    exit 1
+  fi
+}
+
+if [[ $# -gt 0 ]]; then
+  case "$1" in
+    open)
+      COMMAND="open"
+      shift
+      ;;
+    --help|-h|help)
+      print_usage
+      exit 0
+      ;;
+  esac
+fi
 
 while [[ $# -gt 0 ]]; do
   case "$1" in
+    open)
+      COMMAND="open"
+      shift
+      ;;
     --port)
+      require_value "$1" "${2:-}"
       PORT="$2"
+      PORT_SET="1"
       shift 2
       ;;
     --bind)
+      require_value "$1" "${2:-}"
       BIND="$2"
+      BIND_SET="1"
       shift 2
       ;;
-    --open)
-      OPEN_FLAG="1"
-      shift
-      ;;
     --token-file)
+      require_value "$1" "${2:-}"
       TOKEN_FILE="$2"
       shift 2
       ;;
+    --copy)
+      COPY_FLAG="1"
+      shift
+      ;;
+    --open)
+      OPEN_FLAG="1"
+      shift
+      ;;
     --codex-app)
+      require_value "$1" "${2:-}"
       CODEX_APP="$2"
       shift 2
       ;;
-    --help|-h)
-      cat <<USAGE
-Usage: $(basename "$0") [--port <n>] [--bind <ip>] [--open] [--token-file <path>] [--codex-app <path>]
-
-Env overrides:
-  CODEX_WEBSTRAP_PORT
-  CODEX_WEBSTRAP_BIND
-  CODEX_WEBSTRAP_TOKEN_FILE
-  CODEX_WEBSTRAP_CODEX_APP
-  CODEX_WEBSTRAP_INTERNAL_WS_PORT
-USAGE
+    --help|-h|help)
+      print_usage
       exit 0
       ;;
     *)
@@ -60,6 +126,71 @@ USAGE
   esac
 done
 
+if [[ "$COMMAND" != "open" && "$COPY_FLAG" == "1" ]]; then
+  echo "--copy can only be used with the 'open' command" >&2
+  exit 1
+fi
+
+if [[ "$COMMAND" == "open" ]]; then
+  if [[ ! -f "$TOKEN_FILE" ]]; then
+    echo "Token file not found: $TOKEN_FILE" >&2
+    exit 1
+  fi
+
+  TOKEN="$(tr -d '\r\n' < "$TOKEN_FILE")"
+  if [[ -z "$TOKEN" ]]; then
+    echo "Token file is empty: $TOKEN_FILE" >&2
+    exit 1
+  fi
+
+  if [[ "$PORT_SET" == "0" || "$BIND_SET" == "0" ]]; then
+    RUNTIME_FILE="${TOKEN_FILE}.runtime"
+    if [[ -f "$RUNTIME_FILE" ]]; then
+      RUNTIME_VALUES="$(node -e 'const fs = require("node:fs"); const filePath = process.argv[2]; try { const data = JSON.parse(fs.readFileSync(filePath, "utf8")); const bind = data.bind || ""; const port = data.port || ""; if (!bind || !port) { process.exit(1); } process.stdout.write(`${bind}\n${port}\n`); } catch { process.exit(1); }' "$TOKEN_FILE" "$RUNTIME_FILE" 2>/dev/null || true)"
+      if [[ -n "$RUNTIME_VALUES" ]]; then
+        RUNTIME_BIND="$(printf '%s' "$RUNTIME_VALUES" | sed -n '1p')"
+        RUNTIME_PORT="$(printf '%s' "$RUNTIME_VALUES" | sed -n '2p')"
+        if [[ -n "$RUNTIME_BIND" && -n "$RUNTIME_PORT" ]]; then
+          if command -v curl >/dev/null 2>&1; then
+            if curl -fsS --max-time 1 --connect-timeout 1 "http://${RUNTIME_BIND}:${RUNTIME_PORT}/__webstrapper/healthz" >/dev/null 2>&1; then
+              if [[ "$BIND_SET" == "0" ]]; then
+                BIND="$RUNTIME_BIND"
+              fi
+              if [[ "$PORT_SET" == "0" ]]; then
+                PORT="$RUNTIME_PORT"
+              fi
+            fi
+          else
+            if [[ "$BIND_SET" == "0" ]]; then
+              BIND="$RUNTIME_BIND"
+            fi
+            if [[ "$PORT_SET" == "0" ]]; then
+              PORT="$RUNTIME_PORT"
+            fi
+          fi
+        fi
+      fi
+    fi
+  fi
+
+  ENCODED_TOKEN="$(node -e 'process.stdout.write(encodeURIComponent(process.argv[1] || ""))' "$TOKEN")"
+  AUTH_URL="http://${BIND}:${PORT}/__webstrapper/auth?token=${ENCODED_TOKEN}"
+
+  if [[ "$COPY_FLAG" == "1" ]]; then
+    if ! command -v pbcopy >/dev/null 2>&1; then
+      echo "pbcopy not found in PATH" >&2
+      exit 1
+    fi
+    printf '%s' "$AUTH_URL" | pbcopy >/dev/null 2>&1
+    printf 'Copied auth URL to clipboard.\n'
+  else
+    open "$AUTH_URL"
+    printf 'Opened auth URL in browser.\n'
+    printf '%s\n' "$AUTH_URL"
+  fi
+  exit 0
+fi
+
 export CODEX_WEBSTRAP_PORT="$PORT"
 export CODEX_WEBSTRAP_BIND="$BIND"
 export CODEX_WEBSTRAP_TOKEN_FILE="$TOKEN_FILE"

package/package.json

@@ -1,11 +1,12 @@
 {
   "name": "codex-webstrapper",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "type": "module",
   "description": "Web wrapper for Codex desktop assets with bridge + token auth",
   "license": "MIT",
   "bin": {
-    "codex-webstrap": "./bin/codex-webstrap.sh"
+    "codex-webstrap": "./bin/codex-webstrap.sh",
+    "codex-webstrapper": "./bin/codex-webstrap.sh"
   },
   "files": [
     "bin/",

package/src/assets.mjs

@@ -37,7 +37,8 @@ export function resolveCodexAppPaths(explicitCodexAppPath) {
   const resourcesPath = path.join(appPath, "Contents", "Resources");
   const asarPath = path.join(resourcesPath, "app.asar");
   const infoPlistPath = path.join(appPath, "Contents", "Info.plist");
-  return { appPath, resourcesPath, asarPath, infoPlistPath };
+  const codexCliPath = path.join(resourcesPath, "codex");
+  return { appPath, resourcesPath, asarPath, infoPlistPath, codexCliPath };
 }
 
 export async function ensureCodexAppExists(paths) {

package/src/bridge-shim.js

@@ -599,6 +599,18 @@
   }
 
   function sendMessageFromView(payload) {
+    if (payload?.type === "open-in-browser") {
+      const target = payload?.url || payload?.href || null;
+      if (target) {
+        const opened = window.open(target, "_blank", "noopener,noreferrer");
+        if (!opened) {
+          // Fallback when popup is blocked.
+          window.location.href = target;
+        }
+      }
+      return Promise.resolve();
+    }
+
     sendEnvelope({
       type: "view-message",
       payload

package/src/message-router.mjs

@@ -880,6 +880,7 @@ export class MessageRouter {
       }
 
       let payload = {};
+      let status = 200;
       switch (endpoint) {
         case "get-global-state": {
           const key = params?.key;
@@ -1018,7 +1019,7 @@ export class MessageRouter {
           };
           break;
         case "local-environments":
-          payload = [];
+          payload = await this._resolveLocalEnvironments(params);
           break;
         case "has-custom-cli-executable":
           payload = { hasCustomCliExecutable: false };
@@ -1050,6 +1051,21 @@ export class MessageRouter {
           };
           break;
         }
+        case "git-create-branch": {
+          payload = await this._handleGitCreateBranch(params);
+          status = payload.ok ? 200 : 500;
+          break;
+        }
+        case "git-checkout-branch": {
+          payload = await this._handleGitCheckoutBranch(params);
+          status = payload.ok ? 200 : 500;
+          break;
+        }
+        case "git-push": {
+          payload = await this._handleGitPush(params);
+          status = payload.ok ? 200 : 500;
+          break;
+        }
         case "git-merge-base": {
           const gitRoot = typeof params?.gitRoot === "string" && params.gitRoot.length > 0
             ? params.gitRoot
@@ -1102,20 +1118,35 @@ export class MessageRouter {
           payload = await this._resolveGhPrStatus({ cwd, headBranch });
           break;
         }
+        case "generate-pull-request-message":
+          payload = await this._handleGeneratePullRequestMessage(params);
+          break;
+        case "gh-pr-create":
+          payload = await this._handleGhPrCreate(params);
+          break;
         case "paths-exist": {
           const paths = Array.isArray(params?.paths) ? params.paths.filter((p) => typeof p === "string") : [];
           payload = { existingPaths: paths };
           break;
         }
         default:
-          this.logger.warn("Unhandled vscode fetch endpoint", { endpoint });
-          payload = {};
+          if (endpoint.startsWith("git-")) {
+            this.logger.warn("Unhandled git vscode fetch endpoint", { endpoint });
+            payload = {
+              ok: false,
+              error: `unhandled git endpoint: ${endpoint}`
+            };
+            status = 500;
+          } else {
+            this.logger.warn("Unhandled vscode fetch endpoint", { endpoint });
+            payload = {};
+          }
       }
 
       this._sendFetchJson(ws, {
         requestId,
         url: message.url,
-        status: 200,
+        status,
         payload
       });
       return true;
@@ -1312,6 +1343,350 @@ export class MessageRouter {
     };
   }
 
+  async _handleGeneratePullRequestMessage(params) {
+    const cwd = typeof params?.cwd === "string" && params.cwd.length > 0
+      ? params.cwd
+      : process.cwd();
+    const prompt = typeof params?.prompt === "string" ? params.prompt : "";
+    const generated = await this._generatePullRequestMessageWithCodex({ cwd, prompt });
+    const fallback = generated || await this._generateFallbackPullRequestMessage({ cwd, prompt });
+    const title = this._normalizePullRequestTitle(fallback.title);
+    const body = this._normalizePullRequestBody(fallback.body);
+
+    return {
+      status: "success",
+      title,
+      body,
+      // Older clients read `bodyInstructions`; keep it in sync with the generated body.
+      bodyInstructions: body
+    };
+  }
+
+  _normalizePullRequestTitle(title) {
+    if (typeof title !== "string") {
+      return "Update project files";
+    }
+
+    const normalized = title.replace(/\s+/g, " ").trim();
+    if (normalized.length === 0) {
+      return "Update project files";
+    }
+    if (normalized.length <= 120) {
+      return normalized;
+    }
+    return `${normalized.slice(0, 117).trimEnd()}...`;
+  }
+
+  _normalizePullRequestBody(body) {
+    if (typeof body !== "string") {
+      return "## Summary\n- Update project files.\n\n## Testing\n- Not run (context not provided).";
+    }
+
+    const normalized = body.trim();
+    if (normalized.length > 0) {
+      return normalized;
+    }
+    return "## Summary\n- Update project files.\n\n## Testing\n- Not run (context not provided).";
+  }
+
+  _buildPullRequestCodexPrompt(prompt) {
+    const context = typeof prompt === "string" && prompt.trim().length > 0
+      ? prompt.trim().slice(0, 20_000)
+      : "No additional context was provided.";
+
+    return [
+      "Generate a GitHub pull request title and body.",
+      "Return JSON that matches the provided schema.",
+      "Requirements:",
+      "- title: concise imperative sentence, maximum 72 characters.",
+      "- body: markdown with sections exactly '## Summary' and '## Testing'.",
+      "- Summary should include 2 to 6 concrete bullet points.",
+      "- Testing should include bullet points. If unknown, say '- Not run (context not provided).'.",
+      "- Do not wrap output in code fences.",
+      "- Use only the provided context.",
+      "",
+      "Context:",
+      context
+    ].join("\n");
+  }
+
+  async _generatePullRequestMessageWithCodex({ cwd, prompt }) {
+    let tempDir = null;
+    try {
+      tempDir = await fs.mkdtemp(path.join(os.tmpdir(), "codex-webstrap-prmsg-"));
+      const schemaPath = path.join(tempDir, "schema.json");
+      const outputPath = path.join(tempDir, "output.json");
+      const schema = {
+        $schema: "http://json-schema.org/draft-07/schema#",
+        type: "object",
+        required: ["title", "body"],
+        additionalProperties: false,
+        properties: {
+          title: { type: "string" },
+          body: { type: "string" }
+        }
+      };
+      await fs.writeFile(schemaPath, JSON.stringify(schema), "utf8");
+
+      const result = await this._runCommand(
+        "codex",
+        [
+          "exec",
+          "--ephemeral",
+          "--sandbox",
+          "read-only",
+          "--output-schema",
+          schemaPath,
+          "--output-last-message",
+          outputPath,
+          this._buildPullRequestCodexPrompt(prompt)
+        ],
+        {
+          timeoutMs: 120_000,
+          allowNonZero: true,
+          cwd
+        }
+      );
+
+      if (!result.ok) {
+        this.logger.warn("PR message generation via codex failed", {
+          cwd,
+          error: result.error || result.stderr || "unknown error"
+        });
+        return null;
+      }
+
+      const rawOutput = await fs.readFile(outputPath, "utf8");
+      const parsed = safeJsonParse(rawOutput);
+      if (!parsed || typeof parsed !== "object") {
+        return null;
+      }
+
+      const title = this._normalizePullRequestTitle(parsed.title);
+      const body = this._normalizePullRequestBody(parsed.body);
+      return { title, body };
+    } catch (error) {
+      this.logger.warn("PR message generation via codex errored", {
+        cwd,
+        error: toErrorMessage(error)
+      });
+      return null;
+    } finally {
+      if (tempDir) {
+        await fs.rm(tempDir, { recursive: true, force: true }).catch(() => {});
+      }
+    }
+  }
+
+  async _resolvePullRequestBaseRef(cwd) {
+    const originHead = await this._runCommand(
+      "git",
+      ["-C", cwd, "symbolic-ref", "--short", "refs/remotes/origin/HEAD"],
+      { timeoutMs: 5_000, allowNonZero: true, cwd }
+    );
+    if (originHead.ok && originHead.stdout) {
+      return originHead.stdout;
+    }
+
+    const candidates = ["origin/main", "origin/master", "main", "master"];
+    for (const candidate of candidates) {
+      const exists = await this._runCommand(
+        "git",
+        ["-C", cwd, "rev-parse", "--verify", "--quiet", candidate],
+        { timeoutMs: 5_000, allowNonZero: true, cwd }
+      );
+      if (exists.code === 0) {
+        return candidate;
+      }
+    }
+
+    return null;
+  }
+
+  async _generateFallbackPullRequestMessage({ cwd, prompt }) {
+    const baseRef = await this._resolvePullRequestBaseRef(cwd);
+    const logArgs = baseRef
+      ? ["-C", cwd, "log", "--no-merges", "--pretty=format:%s", `${baseRef}..HEAD`, "-n", "6"]
+      : ["-C", cwd, "log", "--no-merges", "--pretty=format:%s", "-n", "6"];
+    const logResult = await this._runCommand("git", logArgs, {
+      timeoutMs: 8_000,
+      allowNonZero: true,
+      cwd
+    });
+    const commitSubjects = (logResult.stdout || "")
+      .split("\n")
+      .map((line) => line.trim())
+      .filter(Boolean);
+
+    const range = baseRef ? `${baseRef}...HEAD` : "HEAD~1..HEAD";
+    const filesResult = await this._runCommand(
+      "git",
+      ["-C", cwd, "diff", "--name-only", "--diff-filter=ACMR", range],
+      { timeoutMs: 8_000, allowNonZero: true, cwd }
+    );
+    const changedFiles = (filesResult.stdout || "")
+      .split("\n")
+      .map((line) => line.trim())
+      .filter(Boolean);
+
+    const statsResult = await this._runCommand(
+      "git",
+      ["-C", cwd, "diff", "--numstat", range],
+      { timeoutMs: 8_000, allowNonZero: true, cwd }
+    );
+    let additions = 0;
+    let deletions = 0;
+    for (const line of (statsResult.stdout || "").split("\n")) {
+      const [addedRaw, deletedRaw] = line.split("\t");
+      const added = Number.parseInt(addedRaw, 10);
+      const deleted = Number.parseInt(deletedRaw, 10);
+      additions += Number.isFinite(added) ? added : 0;
+      deletions += Number.isFinite(deleted) ? deleted : 0;
+    }
+
+    const branch = await this._resolveGitCurrentBranch(cwd);
+    const title = this._normalizePullRequestTitle(
+      commitSubjects[0] || (branch ? `Update ${branch}` : "Update project files")
+    );
+
+    const summaryBullets = [];
+    for (const subject of commitSubjects.slice(0, 3)) {
+      summaryBullets.push(subject);
+    }
+    if (summaryBullets.length === 0) {
+      summaryBullets.push("Update project files.");
+    }
+    if (changedFiles.length > 0) {
+      summaryBullets.push(`Modify ${changedFiles.length} file${changedFiles.length === 1 ? "" : "s"}.`);
+    }
+    if (additions > 0 || deletions > 0) {
+      summaryBullets.push(`Diff summary: +${additions} / -${deletions} lines.`);
+    }
+    if (baseRef) {
+      summaryBullets.push(`Base branch: ${baseRef}.`);
+    }
+
+    const bodyLines = ["## Summary"];
+    for (const bullet of summaryBullets.slice(0, 6)) {
+      bodyLines.push(`- ${bullet}`);
+    }
+
+    bodyLines.push("", "## Testing", "- Not run (context not provided).");
+
+    if (changedFiles.length > 0) {
+      bodyLines.push("", "## Files Changed");
+      for (const file of changedFiles.slice(0, 12)) {
+        bodyLines.push(`- \`${file}\``);
+      }
+      if (changedFiles.length > 12) {
+        bodyLines.push(`- \`...and ${changedFiles.length - 12} more\``);
+      }
+    } else if (typeof prompt === "string" && prompt.trim().length > 0) {
+      bodyLines.push("", "## Notes", "- Generated from available thread context.");
+    }
+
+    return {
+      title,
+      body: this._normalizePullRequestBody(bodyLines.join("\n"))
+    };
+  }
+
+  _extractGithubPrUrl(text) {
+    if (typeof text !== "string" || text.length === 0) {
+      return null;
+    }
+    const match = text.match(/https:\/\/github\.com\/[^\s/]+\/[^\s/]+\/pull\/\d+/);
+    return match ? match[0] : null;
+  }
+
+  async _handleGhPrCreate(params) {
+    const cwd = typeof params?.cwd === "string" && params.cwd.length > 0
+      ? params.cwd
+      : process.cwd();
+    const headBranch = typeof params?.headBranch === "string" ? params.headBranch.trim() : "";
+    const baseBranch = typeof params?.baseBranch === "string" ? params.baseBranch.trim() : "";
+    const bodyInstructions = typeof params?.bodyInstructions === "string" ? params.bodyInstructions : "";
+    const titleOverride = typeof params?.titleOverride === "string" ? params.titleOverride.trim() : "";
+    const bodyOverride = typeof params?.bodyOverride === "string" ? params.bodyOverride.trim() : "";
+
+    if (!headBranch || !baseBranch) {
+      return {
+        status: "error",
+        error: "headBranch and baseBranch are required",
+        url: null,
+        number: null
+      };
+    }
+
+    const ghStatus = await this._resolveGhCliStatus();
+    if (!ghStatus.isInstalled || !ghStatus.isAuthenticated) {
+      return {
+        status: "error",
+        error: "gh cli unavailable or unauthenticated",
+        url: null,
+        number: null
+      };
+    }
+
+    const args = [
+      "pr",
+      "create",
+      "--head",
+      headBranch,
+      "--base",
+      baseBranch
+    ];
+    const shouldFill = titleOverride.length === 0 || bodyOverride.length === 0;
+    if (shouldFill) {
+      args.push("--fill");
+    }
+    if (titleOverride.length > 0) {
+      args.push("--title", titleOverride);
+    }
+    if (bodyOverride.length > 0) {
+      args.push("--body", bodyOverride);
+    } else if (bodyInstructions.trim().length > 0) {
+      args.push("--body", bodyInstructions);
+    }
+
+    const result = await this._runCommand("gh", args, {
+      timeoutMs: 30_000,
+      allowNonZero: true,
+      cwd
+    });
+
+    if (result.ok) {
+      const url = this._extractGithubPrUrl(result.stdout) || this._extractGithubPrUrl(result.stderr);
+      const numberMatch = url ? url.match(/\/pull\/(\d+)/) : null;
+      const number = numberMatch ? Number.parseInt(numberMatch[1], 10) : null;
+      return {
+        status: "success",
+        url: url || null,
+        number: Number.isFinite(number) ? number : null
+      };
+    }
+
+    const combinedOutput = `${result.stdout || ""}\n${result.stderr || ""}`;
+    const existingUrl = this._extractGithubPrUrl(combinedOutput);
+    const alreadyExists = /already exists|a pull request for branch/i.test(combinedOutput);
+    if (alreadyExists && existingUrl) {
+      const numberMatch = existingUrl.match(/\/pull\/(\d+)/);
+      const number = numberMatch ? Number.parseInt(numberMatch[1], 10) : null;
+      return {
+        status: "success",
+        url: existingUrl,
+        number: Number.isFinite(number) ? number : null
+      };
+    }
+
+    return {
+      status: "error",
+      error: result.error || result.stderr || "failed to create pull request",
+      url: null,
+      number: null
+    };
+  }
+
   async _resolveGitMergeBase({ gitRoot, baseBranch }) {
     if (!baseBranch) {
       return {
@@ -1333,6 +1708,179 @@ export class MessageRouter {
     };
   }
 
+  async _resolveGitCurrentBranch(cwd) {
+    const result = await this._runCommand("git", ["-C", cwd, "rev-parse", "--abbrev-ref", "HEAD"], {
+      timeoutMs: 5_000,
+      allowNonZero: true,
+      cwd
+    });
+    if (!result.ok || !result.stdout || result.stdout === "HEAD") {
+      return null;
+    }
+    return result.stdout;
+  }
+
+  async _handleGitCreateBranch(params) {
+    const cwd = typeof params?.cwd === "string" && params.cwd.length > 0
+      ? params.cwd
+      : process.cwd();
+    const branch = typeof params?.branch === "string" && params.branch.trim().length > 0
+      ? params.branch.trim()
+      : null;
+
+    if (!branch) {
+      return {
+        ok: false,
+        code: null,
+        error: "branch is required",
+        stdout: "",
+        stderr: ""
+      };
+    }
+
+    const existingResult = await this._runCommand("git", ["-C", cwd, "show-ref", "--verify", "--quiet", `refs/heads/${branch}`], {
+      cwd,
+      timeoutMs: 10_000,
+      allowNonZero: true
+    });
+    if (existingResult.code === 0) {
+      return {
+        ok: true,
+        code: 0,
+        branch,
+        created: false,
+        alreadyExists: true,
+        stdout: existingResult.stdout || "",
+        stderr: existingResult.stderr || ""
+      };
+    }
+
+    const createResult = await this._runCommand("git", ["-C", cwd, "branch", branch], {
+      cwd,
+      timeoutMs: 10_000,
+      allowNonZero: true
+    });
+    if (createResult.ok) {
+      return {
+        ok: true,
+        code: createResult.code,
+        branch,
+        created: true,
+        alreadyExists: false,
+        stdout: createResult.stdout || "",
+        stderr: createResult.stderr || ""
+      };
+    }
+
+    return {
+      ok: false,
+      code: createResult.code,
+      error: createResult.error || createResult.stderr || "git branch failed",
+      stdout: createResult.stdout || "",
+      stderr: createResult.stderr || ""
+    };
+  }
+
+  async _handleGitCheckoutBranch(params) {
+    const cwd = typeof params?.cwd === "string" && params.cwd.length > 0
+      ? params.cwd
+      : process.cwd();
+    const branch = typeof params?.branch === "string" && params.branch.trim().length > 0
+      ? params.branch.trim()
+      : null;
+
+    if (!branch) {
+      return {
+        ok: false,
+        code: null,
+        error: "branch is required",
+        stdout: "",
+        stderr: ""
+      };
+    }
+
+    const checkoutResult = await this._runCommand("git", ["-C", cwd, "checkout", branch], {
+      cwd,
+      timeoutMs: 20_000,
+      allowNonZero: true
+    });
+    if (!checkoutResult.ok) {
+      return {
+        ok: false,
+        code: checkoutResult.code,
+        error: checkoutResult.error || checkoutResult.stderr || "git checkout failed",
+        stdout: checkoutResult.stdout || "",
+        stderr: checkoutResult.stderr || ""
+      };
+    }
+
+    const currentBranch = await this._resolveGitCurrentBranch(cwd);
+    return {
+      ok: true,
+      code: checkoutResult.code,
+      branch: currentBranch || branch,
+      stdout: checkoutResult.stdout || "",
+      stderr: checkoutResult.stderr || ""
+    };
+  }
+
+  async _handleGitPush(params) {
+    const cwd = typeof params?.cwd === "string" && params.cwd.length > 0
+      ? params.cwd
+      : process.cwd();
+    const explicitRemote = typeof params?.remote === "string" && params.remote.trim().length > 0
+      ? params.remote.trim()
+      : null;
+    const branch = typeof params?.branch === "string" && params.branch.trim().length > 0
+      ? params.branch.trim()
+      : null;
+    const refspec = typeof params?.refspec === "string" && params.refspec.trim().length > 0
+      ? params.refspec.trim()
+      : null;
+    const remote = explicitRemote || (
+      params?.setUpstream === true && (branch || refspec) ? "origin" : null
+    );
+
+    const args = ["-C", cwd, "push"];
+    if (params?.force === true || params?.forceWithLease === true) {
+      args.push("--force-with-lease");
+    }
+    if (params?.setUpstream === true) {
+      args.push("--set-upstream");
+    }
+    if (remote) {
+      args.push(remote);
+    }
+    if (refspec) {
+      args.push(refspec);
+    } else if (branch) {
+      args.push(branch);
+    }
+
+    const result = await this._runCommand("git", args, {
+      cwd,
+      timeoutMs: 120_000,
+      allowNonZero: true
+    });
+
+    if (result.ok) {
+      return {
+        ok: true,
+        code: result.code,
+        stdout: result.stdout || "",
+        stderr: result.stderr || ""
+      };
+    }
+
+    return {
+      ok: false,
+      code: result.code,
+      error: result.error || result.stderr || "git push failed",
+      stdout: result.stdout || "",
+      stderr: result.stderr || ""
+    };
+  }
+
   async _runCommand(command, args, { timeoutMs = 5_000, allowNonZero = false, cwd = process.cwd() } = {}) {
     return new Promise((resolve) => {
       const child = spawn(command, args, {
@@ -1471,6 +2019,128 @@ export class MessageRouter {
     return trimmed.replace(/\/+$/, "");
   }
 
+  async _resolveLocalEnvironments(params) {
+    const workspaceRoot = this._resolveLocalEnvironmentWorkspaceRoot(params?.workspaceRoot);
+    if (!workspaceRoot) {
+      return { environments: [] };
+    }
+
+    const configDir = path.join(workspaceRoot, ".codex", "environments");
+    let entries;
+    try {
+      entries = await fs.readdir(configDir, { withFileTypes: true });
+    } catch {
+      return { environments: [] };
+    }
+
+    const configFiles = entries
+      .filter((entry) => entry.isFile() && /^environment(?:-\d+)?\.toml$/i.test(entry.name))
+      .map((entry) => entry.name)
+      .sort((left, right) => {
+        const leftIsDefault = left.toLowerCase() === "environment.toml";
+        const rightIsDefault = right.toLowerCase() === "environment.toml";
+        if (leftIsDefault && !rightIsDefault) {
+          return -1;
+        }
+        if (!leftIsDefault && rightIsDefault) {
+          return 1;
+        }
+        return left.localeCompare(right, undefined, { numeric: true, sensitivity: "base" });
+      });
+
+    if (configFiles.length === 0) {
+      return { environments: [] };
+    }
+
+    const environments = await Promise.all(configFiles.map(async (fileName) => {
+      const configPath = path.join(configDir, fileName);
+      try {
+        const raw = await fs.readFile(configPath, "utf8");
+        const environment = this._parseLocalEnvironmentConfig(raw, configPath);
+        return {
+          type: "success",
+          configPath,
+          environment
+        };
+      } catch (error) {
+        return {
+          type: "error",
+          configPath,
+          error: {
+            message: toErrorMessage(error)
+          }
+        };
+      }
+    }));
+
+    return { environments };
+  }
+
+  _resolveLocalEnvironmentWorkspaceRoot(root) {
+    const normalized = this._normalizeWorkspaceRoot(root);
+    if (normalized) {
+      return path.resolve(normalized);
+    }
+
+    const activeRoot = this._normalizeWorkspaceRoot(this.activeWorkspaceRoots?.[0]);
+    if (activeRoot) {
+      return path.resolve(activeRoot);
+    }
+
+    return this.defaultWorkspaceRoot ? path.resolve(this.defaultWorkspaceRoot) : null;
+  }
+
+  _parseLocalEnvironmentConfig(raw, configPath) {
+    const name = this._parseTomlString(raw, "name") || path.basename(configPath, ".toml");
+    const versionRaw = this._parseTomlNumber(raw, "version");
+    const setupScript = this._parseTomlStringInSection(raw, "setup", "script") || "";
+
+    return {
+      version: Number.isInteger(versionRaw) ? versionRaw : 1,
+      name,
+      setup: {
+        script: setupScript
+      },
+      actions: []
+    };
+  }
+
+  _parseTomlString(raw, key) {
+    const escapedKey = key.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    const pattern = new RegExp(`^\\s*${escapedKey}\\s*=\\s*(?:"([^"]*)"|'([^']*)')\\s*$`, "m");
+    const match = raw.match(pattern);
+    if (!match) {
+      return null;
+    }
+    return match[1] ?? match[2] ?? null;
+  }
+
+  _parseTomlNumber(raw, key) {
+    const escapedKey = key.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    const pattern = new RegExp(`^\\s*${escapedKey}\\s*=\\s*(-?\\d+)\\s*$`, "m");
+    const match = raw.match(pattern);
+    if (!match) {
+      return null;
+    }
+    const value = Number.parseInt(match[1], 10);
+    return Number.isNaN(value) ? null : value;
+  }
+
+  _parseTomlStringInSection(raw, sectionName, key) {
+    const escapedSection = sectionName.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    const sectionPattern = new RegExp(`^\\s*\\[${escapedSection}\\]\\s*$`, "m");
+    const sectionMatch = sectionPattern.exec(raw);
+    if (!sectionMatch) {
+      return null;
+    }
+
+    const sectionStart = sectionMatch.index + sectionMatch[0].length;
+    const rest = raw.slice(sectionStart);
+    const nextSectionMatch = rest.match(/^\s*\[[^\]]+\]\s*$/m);
+    const sectionBody = nextSectionMatch ? rest.slice(0, nextSectionMatch.index) : rest;
+    return this._parseTomlString(sectionBody, key);
+  }
+
   _loadPersistedGlobalState() {
     if (!this.globalStatePath) {
       return;

package/src/server.mjs

@@ -114,6 +114,7 @@ async function main() {
   const config = parseConfig();
 
   const tokenResult = await ensurePersistentToken(config.tokenFile);
+  const runtimeMetadataPath = `${tokenResult.tokenFilePath}.runtime`;
   const sessionStore = new SessionStore({ ttlMs: 1000 * 60 * 60 * 12 });
   const auth = createAuthController({ token: tokenResult.token, sessionStore });
 
@@ -148,8 +149,20 @@ async function main() {
   });
   const patchedIndexHtml = await buildPatchedIndexHtml(assetBundle.indexPath);
 
+  let codexCliPath = process.env.CODEX_CLI_PATH || codexPaths.codexCliPath;
+  if (!process.env.CODEX_CLI_PATH) {
+    const bundledCliExists = await fs.access(codexPaths.codexCliPath).then(() => true).catch(() => false);
+    if (!bundledCliExists) {
+      codexCliPath = "codex";
+      logger.warn("Bundled Codex CLI not found, falling back to PATH", {
+        bundledCliPath: codexPaths.codexCliPath
+      });
+    }
+  }
+
   const appServer = new AppServerManager({
     internalPort: config.internalWsPort,
+    codexCliPath,
     logger: createLogger("app-server")
   });
 
@@ -287,6 +300,25 @@ async function main() {
     server.listen(config.port, config.bind, resolve);
   });
 
+  try {
+    await fs.writeFile(
+      runtimeMetadataPath,
+      JSON.stringify({
+        bind: config.bind,
+        port: config.port,
+        tokenFile: tokenResult.tokenFilePath,
+        pid: process.pid,
+        startedAt: Date.now()
+      }) + "\n",
+      { mode: 0o600 }
+    );
+  } catch (error) {
+    logger.warn("Failed to write runtime metadata file", {
+      path: runtimeMetadataPath,
+      error: toErrorMessage(error)
+    });
+  }
+
   const authHint = `http://${config.bind}:${config.port}/__webstrapper/auth?token=<redacted>`;
   const loginCommand = `open \"http://${config.bind}:${config.port}/__webstrapper/auth?token=$(cat ${tokenResult.tokenFilePath})\"`;
 
@@ -344,6 +376,11 @@ async function main() {
     await new Promise((resolve) => {
       server.close(() => resolve());
     });
+    try {
+      await fs.unlink(runtimeMetadataPath);
+    } catch {
+      // ignore
+    }
 
     process.exit(0);
   }