maesttro 0.1.2 → 0.2.0

package/dist/maesttro.js

@@ -0,0 +1,2106 @@
+#!/usr/bin/env node
+
+// src/credential-store.ts
+import {
+  chmodSync,
+  mkdirSync,
+  readFileSync,
+  renameSync,
+  rmSync,
+  writeFileSync
+} from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+
+// src/run-command.ts
+import { spawnSync } from "node:child_process";
+var runCommand = (command, args, input) => {
+  const result = spawnSync(command, args, {
+    input,
+    encoding: "utf8",
+    stdio: ["pipe", "pipe", "ignore"]
+  });
+  return {
+    status: result.error ? null : result.status,
+    stdout: result.stdout ?? ""
+  };
+};
+function commandExists(run, command) {
+  return run("sh", ["-c", `command -v ${command}`]).status === 0;
+}
+
+// src/credential-store.ts
+var SERVICE = "maesttro";
+var ACCOUNT = "github";
+function encode(token) {
+  return Buffer.from(JSON.stringify(token)).toString("base64");
+}
+function decode(encoded) {
+  try {
+    const token = JSON.parse(Buffer.from(encoded.trim(), "base64").toString("utf8"));
+    return typeof token.access_token === "string" ? token : undefined;
+  } catch {
+    return;
+  }
+}
+function keychainStore(run = runCommand) {
+  const identity = ["-s", SERVICE, "-a", ACCOUNT];
+  return {
+    kind: "macOS keychain",
+    load: () => {
+      const result = run("security", [
+        "find-generic-password",
+        ...identity,
+        "-w"
+      ]);
+      return result.status === 0 ? decode(result.stdout) : undefined;
+    },
+    save: (token) => {
+      const command = `add-generic-password -U ${identity.join(" ")} -w ${encode(token)}
+`;
+      const result = run("security", ["-i"], command);
+      if (result.status !== 0)
+        throw new Error("Could not write to keychain");
+    },
+    clear: () => {
+      run("security", ["delete-generic-password", ...identity]);
+    }
+  };
+}
+function secretToolStore(run = runCommand) {
+  const attributes = ["service", SERVICE, "account", ACCOUNT];
+  return {
+    kind: "Secret Service (secret-tool)",
+    load: () => {
+      const result = run("secret-tool", ["lookup", ...attributes]);
+      return result.status === 0 ? decode(result.stdout) : undefined;
+    },
+    save: (token) => {
+      const result = run("secret-tool", ["store", `--label=${SERVICE}`, ...attributes], encode(token));
+      if (result.status !== 0) {
+        throw new Error("Could not write to the Secret Service");
+      }
+    },
+    clear: () => {
+      run("secret-tool", ["clear", ...attributes]);
+    }
+  };
+}
+function fileStore(path = join(homedir(), ".config", "maesttro", "credentials.json")) {
+  return {
+    kind: `file (${path})`,
+    load: () => {
+      try {
+        return decode(readFileSync(path, "utf8"));
+      } catch {
+        return;
+      }
+    },
+    save: (token) => {
+      mkdirSync(dirname(path), { recursive: true, mode: 448 });
+      const temporary = `${path}.tmp`;
+      writeFileSync(temporary, encode(token), { mode: 384 });
+      chmodSync(temporary, 384);
+      renameSync(temporary, path);
+    },
+    clear: () => {
+      rmSync(path, { force: true });
+    }
+  };
+}
+function selectCredentialStore({
+  platform = process.platform,
+  env = process.env,
+  run = runCommand
+} = {}) {
+  if (env.MAESTTRO_CREDENTIAL_STORE === "file")
+    return fileStore();
+  if (platform === "darwin")
+    return keychainStore(run);
+  if (platform === "linux" && commandExists(run, "secret-tool")) {
+    return secretToolStore(run);
+  }
+  return fileStore();
+}
+
+// src/github-api.ts
+function githubApiUrl(env = process.env) {
+  return env.MAESTTRO_GITHUB_API_URL?.trim() || "https://api.github.com";
+}
+
+// src/github-app.ts
+var DEFAULT_GITHUB_APP_CLIENT_ID = "Iv23lig1wvF2RtVsAMWo";
+function githubAppClientId(env = process.env) {
+  return env.MAESTTRO_GITHUB_CLIENT_ID?.trim() || DEFAULT_GITHUB_APP_CLIENT_ID;
+}
+
+// src/device-flow.ts
+var DEVICE_CODE_URL = "https://github.com/login/device/code";
+var ACCESS_TOKEN_URL = "https://github.com/login/oauth/access_token";
+var DEVICE_GRANT = "urn:ietf:params:oauth:grant-type:device_code";
+var SLOW_DOWN_PENALTY_SECONDS = 5;
+
+class DeviceFlowError extends Error {
+  code;
+  constructor(code) {
+    super(`GitHub login failed: ${code}`);
+    this.code = code;
+    this.name = "DeviceFlowError";
+  }
+}
+var defaultSleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+async function postForm(fetchImpl, url, form) {
+  const response = await fetchImpl(url, {
+    method: "POST",
+    headers: {
+      Accept: "application/json",
+      "Content-Type": "application/x-www-form-urlencoded"
+    },
+    body: new URLSearchParams(form),
+    signal: AbortSignal.timeout(15000)
+  });
+  const body = await response.json().catch(() => ({}));
+  if (!response.ok && typeof body.error !== "string") {
+    throw new DeviceFlowError(`http_${response.status}`);
+  }
+  return body;
+}
+function asGrant(body) {
+  if (typeof body.access_token !== "string") {
+    throw new DeviceFlowError(typeof body.error === "string" ? body.error : "malformed_response");
+  }
+  return {
+    access_token: body.access_token,
+    expires_in: body.expires_in,
+    refresh_token: body.refresh_token,
+    refresh_token_expires_in: body.refresh_token_expires_in
+  };
+}
+async function requestDeviceCode({
+  clientId,
+  fetch: fetchImpl = fetch
+}) {
+  const body = await postForm(fetchImpl, DEVICE_CODE_URL, {
+    client_id: clientId
+  });
+  if (typeof body.device_code !== "string") {
+    throw new DeviceFlowError(typeof body.error === "string" ? body.error : "malformed_response");
+  }
+  return body;
+}
+async function pollForGrant({
+  clientId,
+  deviceCode,
+  fetch: fetchImpl = fetch,
+  sleep = defaultSleep,
+  now = Date.now
+}) {
+  const deadline = now() + deviceCode.expires_in * 1000;
+  let intervalSeconds = deviceCode.interval;
+  while (now() < deadline) {
+    await sleep(intervalSeconds * 1000);
+    const body = await postForm(fetchImpl, ACCESS_TOKEN_URL, {
+      client_id: clientId,
+      device_code: deviceCode.device_code,
+      grant_type: DEVICE_GRANT
+    });
+    if (body.error === "authorization_pending")
+      continue;
+    if (body.error === "slow_down") {
+      intervalSeconds = typeof body.interval === "number" ? body.interval : intervalSeconds + SLOW_DOWN_PENALTY_SECONDS;
+      continue;
+    }
+    return asGrant(body);
+  }
+  throw new DeviceFlowError("expired_token");
+}
+async function refreshGrant({
+  clientId,
+  refreshToken,
+  fetch: fetchImpl = fetch
+}) {
+  const body = await postForm(fetchImpl, ACCESS_TOKEN_URL, {
+    client_id: clientId,
+    grant_type: "refresh_token",
+    refresh_token: refreshToken
+  });
+  return asGrant(body);
+}
+
+// src/user-token.ts
+var EXPIRY_MARGIN_MS = 5 * 60 * 1000;
+function isoAfter(now, seconds) {
+  return seconds === undefined ? undefined : new Date(now + seconds * 1000).toISOString();
+}
+function userTokenFromGrant(grant, now) {
+  return {
+    access_token: grant.access_token,
+    expires_at: isoAfter(now, grant.expires_in),
+    refresh_token: grant.refresh_token,
+    refresh_expires_at: isoAfter(now, grant.refresh_token_expires_in)
+  };
+}
+function stillValid(expiresAt, now) {
+  return expiresAt === undefined || Date.parse(expiresAt) - EXPIRY_MARGIN_MS > now;
+}
+function isAccessValid(token, now) {
+  return stillValid(token.expires_at, now);
+}
+function isRefreshable(token, now) {
+  return token.refresh_token !== undefined && stillValid(token.refresh_expires_at, now);
+}
+
+// src/github-login.ts
+async function deviceLogin(dependencies) {
+  const now = dependencies.now ?? Date.now;
+  const deviceCode = await requestDeviceCode(dependencies);
+  dependencies.announce(`To give maesttro GitHub access, open ${deviceCode.verification_uri} and enter code ${deviceCode.user_code}`);
+  const grant = await pollForGrant({ ...dependencies, deviceCode });
+  const token = userTokenFromGrant(grant, now());
+  dependencies.store.save(token);
+  return token;
+}
+async function refreshUserToken(dependencies) {
+  const now = dependencies.now ?? Date.now;
+  const grant = await refreshGrant({
+    ...dependencies,
+    refreshToken: dependencies.token.refresh_token
+  });
+  const token = userTokenFromGrant(grant, now());
+  dependencies.store.save(token);
+  return token;
+}
+async function currentUserToken(dependencies) {
+  const now = (dependencies.now ?? Date.now)();
+  const stored = dependencies.store.load();
+  if (stored && isAccessValid(stored, now))
+    return stored;
+  if (stored && isRefreshable(stored, now)) {
+    try {
+      return await refreshUserToken({ ...dependencies, token: stored });
+    } catch (error) {
+      if (!(error instanceof DeviceFlowError))
+        throw error;
+      dependencies.store.clear();
+    }
+  }
+  return dependencies.interactive ? deviceLogin(dependencies) : undefined;
+}
+
+// src/account.ts
+async function githubLogin(token, fetchImpl = fetch) {
+  const response = await fetchImpl(new URL("/user", githubApiUrl()), {
+    headers: {
+      Accept: "application/vnd.github+json",
+      Authorization: `Bearer ${token}`,
+      "User-Agent": "maesttro"
+    },
+    signal: AbortSignal.timeout(1e4)
+  });
+  if (!response.ok)
+    return;
+  const body = await response.json();
+  return body.login;
+}
+function loginDependencies() {
+  return {
+    clientId: githubAppClientId(),
+    store: selectCredentialStore(),
+    announce: (message) => console.log(message)
+  };
+}
+function describeExpiry(iso) {
+  return iso ? new Date(iso).toLocaleString() : "never";
+}
+async function login() {
+  const dependencies = loginDependencies();
+  const token = await deviceLogin(dependencies);
+  const name = await githubLogin(token.access_token);
+  console.log(`Logged in to GitHub${name ? ` as ${name}` : ""}. Stored in ${dependencies.store.kind}.`);
+}
+async function ensureLogin() {
+  const dependencies = loginDependencies();
+  const token = await currentUserToken({ ...dependencies, interactive: true });
+  const name = token && await githubLogin(token.access_token);
+  console.log(name ? `Logged in to GitHub as ${name}. Stored in ${dependencies.store.kind}.` : "GitHub login did not complete. Run `maesttro login` to retry.");
+}
+function logout() {
+  const { store } = loginDependencies();
+  store.clear();
+  console.log(`Logged out. Removed GitHub credentials from ${store.kind}.`);
+}
+async function status() {
+  const dependencies = loginDependencies();
+  const token = await currentUserToken({ ...dependencies, interactive: false });
+  if (!token) {
+    console.log("Not logged in to GitHub. Run `maesttro login`.");
+    process.exitCode = 1;
+    return;
+  }
+  const name = await githubLogin(token.access_token);
+  console.log([
+    `GitHub: ${name ? `logged in as ${name}` : "token rejected — run `maesttro login`"}`,
+    `Store: ${dependencies.store.kind}`,
+    `Access token expires: ${describeExpiry(token.expires_at)}`,
+    `Refresh token expires: ${describeExpiry(token.refresh_expires_at)}`
+  ].join(`
+`));
+  if (!name)
+    process.exitCode = 1;
+}
+
+// src/configure.ts
+import {
+  cpSync,
+  existsSync,
+  mkdirSync as mkdirSync2,
+  readdirSync,
+  readFileSync as readFileSync2,
+  writeFileSync as writeFileSync2
+} from "node:fs";
+import { homedir as homedir2 } from "node:os";
+import { dirname as dirname3, join as join3 } from "node:path";
+
+// src/clients.ts
+var CLIENTS = {
+  claude: {
+    label: "Claude Code",
+    npmPackage: "@anthropic-ai/claude-code",
+    binary: "claude",
+    configDir: "/home/agent/.claude"
+  },
+  opencode: {
+    label: "opencode",
+    npmPackage: "opencode-ai",
+    binary: "opencode",
+    configDir: "/home/agent/.config/opencode"
+  },
+  codex: {
+    label: "OpenAI Codex CLI",
+    npmPackage: "@openai/codex",
+    binary: "codex",
+    configDir: "/home/agent/.codex"
+  }
+};
+var DEFAULT_CLIENT = "claude";
+function isClientKey(value) {
+  return Object.hasOwn(CLIENTS, value);
+}
+
+// src/host-instructions.ts
+var HOST_STAGING_DIR = "/opt/maesttro-host";
+var STAGED_DIRECTORIES = [
+  ".claude/agents",
+  ".claude/commands",
+  ".claude/skills"
+];
+var INSTRUCTION_FILES = [
+  ".claude/CLAUDE.md",
+  ".config/opencode/AGENTS.md",
+  ".codex/AGENTS.md"
+];
+var STAGED_PATHS = [...INSTRUCTION_FILES, ...STAGED_DIRECTORIES];
+
+// src/paths.ts
+import { dirname as dirname2, join as join2, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+var PACKAGE_ROOT = resolve(dirname2(fileURLToPath(import.meta.url)), "..");
+var DOCKERFILE_DIR = join2(PACKAGE_ROOT, "docker");
+var IMAGE = "maesttro-runner:latest";
+var VOLUME = process.env.MAESTTRO_VOLUME?.trim() || "maesttro-home";
+
+// src/sandbox-context.ts
+function sandboxContextFromEnv(env) {
+  return {
+    sessionId: env.MAESTTRO_SESSION_ID,
+    base: env.MAESTTRO_BASE,
+    repo: env.MAESTTRO_REPO,
+    githubAccess: env.MAESTTRO_GITHUB === "on"
+  };
+}
+function sandboxInstructions(context) {
+  const base = context.base ?? "the default branch";
+  const github = context.githubAccess ? [
+    `- \`gh\` works for ${context.repo ?? "this repo"} only: issues, pull requests, comments. Its token is short-lived and refreshed for you.`,
+    "- Merging pull requests and deleting remote branches are not possible from here. A person merges."
+  ] : [
+    "- GitHub access is unavailable in this session, so `gh` has no token. Local git work still works."
+  ];
+  return [
+    "# Maesttro sandbox",
+    "",
+    "You are running inside Maesttro's isolated sandbox container. These rules describe what the environment allows, so plan around them.",
+    "",
+    "## Your workspace",
+    "",
+    `- The current directory is an isolated clone of the repository${context.sessionId ? ` for this session (\`${context.sessionId}\`)` : ""}, detached at \`${base}\`. It is the only checkout you can see or change; your main checkout is not here.`,
+    "- Before your first commit, create a branch for the task: `git switch -c <short-descriptive-name>`. Keep one branch per task.",
+    "- Work in this directory. Anything outside it is not persisted.",
+    "- Commit on a branch you create here. The user pushes it from their machine with `maesttro push`; the sandbox cannot push, merge, or delete remote branches.",
+    "",
+    "## Pushing",
+    "",
+    "- `git push` does not work here: the sandbox has read-only access to the remote. This is deliberate.",
+    '- When a branch is ready, commit everything, then tell the user: "Ready to push: <branch>. Run `maesttro push <branch>` from the repository root."',
+    "- After the user confirms it is pushed, `git fetch` and continue. Open the pull request with `gh pr create --head <branch>` if asked to.",
+    "",
+    "## GitHub",
+    "",
+    ...github,
+    ""
+  ].join(`
+`);
+}
+
+// src/configure.ts
+var SANDBOX_MARKER = "/etc/maesttro/sandbox";
+function isObject(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function withoutComments(value) {
+  return Object.fromEntries(Object.entries(value).filter(([key]) => !key.startsWith("_comment")).map(([key, inner]) => [
+    key,
+    isObject(inner) ? withoutComments(inner) : inner
+  ]));
+}
+function mergeJson(existing, curated) {
+  const merged = { ...existing };
+  for (const [key, value] of Object.entries(curated)) {
+    const current = merged[key];
+    merged[key] = isObject(current) && isObject(value) ? mergeJson(current, value) : value;
+  }
+  return merged;
+}
+function readJson(path) {
+  try {
+    const parsed = JSON.parse(readFileSync2(path, "utf8"));
+    return isObject(parsed) ? parsed : {};
+  } catch {
+    return {};
+  }
+}
+function applyProviderConfigs({
+  home,
+  configsDir = join3(DOCKERFILE_DIR, "configs")
+}) {
+  const written = [];
+  for (const [key, client] of Object.entries(CLIENTS)) {
+    const source = join3(configsDir, key);
+    if (!existsSync(source))
+      continue;
+    const targetDir = join3(home, client.configDir.replace(/^\/home\/agent\/?/, ""));
+    for (const name of readdirSync(source)) {
+      if (!name.endsWith(".json"))
+        continue;
+      const curated = withoutComments(readJson(join3(source, name)));
+      if (Object.keys(curated).length === 0)
+        continue;
+      const target = join3(targetDir, name);
+      mkdirSync2(targetDir, { recursive: true });
+      const merged = mergeJson(readJson(target), curated);
+      writeFileSync2(target, `${JSON.stringify(merged, null, 2)}
+`);
+      written.push(target);
+    }
+  }
+  return written;
+}
+function stageHostInstructions({
+  home,
+  staging = HOST_STAGING_DIR,
+  context
+}) {
+  for (const directory of STAGED_DIRECTORIES) {
+    const source = join3(staging, directory);
+    if (!existsSync(source))
+      continue;
+    try {
+      cpSync(source, join3(home, directory), { recursive: true, force: true });
+    } catch {}
+  }
+  const instructions = sandboxInstructions(context);
+  for (const file of INSTRUCTION_FILES) {
+    const source = join3(staging, file);
+    const hostCopy = existsSync(source) ? readFileSync2(source, "utf8") : "";
+    const target = join3(home, file);
+    mkdirSync2(dirname3(target), { recursive: true });
+    writeFileSync2(target, hostCopy ? `${hostCopy.trimEnd()}
+
+${instructions}` : instructions);
+  }
+}
+function configure({
+  home = homedir2(),
+  inSandbox = existsSync(SANDBOX_MARKER),
+  env = process.env
+} = {}) {
+  applyProviderConfigs({ home });
+  if (inSandbox) {
+    stageHostInstructions({ home, context: sandboxContextFromEnv(env) });
+  }
+}
+
+// src/doctor.ts
+import { execSync as execSync2 } from "node:child_process";
+
+// src/broker-client.ts
+var DEFAULT_BROKER_URL = "http://100.64.0.2";
+function brokerUrl(env = process.env) {
+  return env.MAESTTRO_BROKER_URL?.trim() || DEFAULT_BROKER_URL;
+}
+
+class BrokerError extends Error {
+  code;
+  status;
+  constructor(code, status) {
+    super(code);
+    this.code = code;
+    this.status = status;
+    this.name = "BrokerError";
+  }
+}
+function isSessionToken(body) {
+  const candidate = body;
+  return typeof candidate?.token === "string" && typeof candidate.expires_at === "string" && typeof candidate.committer?.name === "string" && typeof candidate.committer?.email === "string";
+}
+async function requestSessionToken({
+  broker,
+  userToken,
+  repo,
+  fetch: fetchImpl = fetch
+}) {
+  let response;
+  try {
+    response = await fetchImpl(new URL("/stagehand/token", broker), {
+      method: "POST",
+      headers: {
+        Authorization: `Bearer ${userToken}`,
+        "Content-Type": "application/json"
+      },
+      body: JSON.stringify({ repo }),
+      signal: AbortSignal.timeout(1e4)
+    });
+  } catch {
+    throw new BrokerError("broker_unreachable");
+  }
+  const body = await response.json().catch(() => null);
+  if (response.ok && isSessionToken(body))
+    return body;
+  const code = body?.error;
+  throw new BrokerError(typeof code === "string" ? code : "broker_unreachable", response.status);
+}
+async function brokerHealthy(broker, fetchImpl = fetch, timeoutMs = 2000) {
+  try {
+    const response = await fetchImpl(new URL("/stagehand/health", broker), {
+      signal: AbortSignal.timeout(timeoutMs)
+    });
+    const body = await response.json();
+    return response.ok && body?.status === "ok";
+  } catch {
+    return false;
+  }
+}
+async function revokeSessionToken(token, fetchImpl = fetch, apiUrl = githubApiUrl()) {
+  try {
+    await fetchImpl(new URL("/installation/token", apiUrl), {
+      method: "DELETE",
+      headers: {
+        Accept: "application/vnd.github+json",
+        Authorization: `Bearer ${token}`,
+        "User-Agent": "maesttro"
+      },
+      signal: AbortSignal.timeout(5000)
+    });
+  } catch {}
+}
+
+// src/host-identity.ts
+function hostIdentityEnv() {
+  if (typeof process.getuid !== "function" || typeof process.getgid !== "function") {
+    return {};
+  }
+  return {
+    MAESTTRO_HOST_UID: String(process.getuid()),
+    MAESTTRO_HOST_GID: String(process.getgid())
+  };
+}
+function hostIdentityFlags() {
+  return Object.entries(hostIdentityEnv()).map(([name, value]) => `-e ${name}=${value}`).join(" ");
+}
+
+// src/legacy-token.ts
+import { execSync } from "node:child_process";
+var LEGACY_HOSTS = "~/.config/gh/hosts.yml";
+var PURGE_LEGACY_TOKEN = [
+  `if [ -e ${LEGACY_HOSTS} ]; then rm -f ${LEGACY_HOSTS}; echo FOUND; fi`,
+  "git config --global --remove-section credential.https://github.com 2>/dev/null || true",
+  "git config --global --remove-section credential.https://gist.github.com 2>/dev/null || true"
+].join("; ");
+var DETECT_LEGACY_TOKEN = `if [ -e ${LEGACY_HOSTS} ]; then echo FOUND; else echo CLEAN; fi`;
+function inVolume(command) {
+  return execSync(`docker run --rm ${hostIdentityFlags()} -v ${VOLUME}:/home/agent ${IMAGE} "${command}"`).toString();
+}
+function purgeLegacyToken() {
+  return inVolume(PURGE_LEGACY_TOKEN).includes("FOUND");
+}
+function hasLegacyToken() {
+  return inVolume(DETECT_LEGACY_TOKEN).includes("FOUND");
+}
+var REVOKE_NOTICE = "Removed a long-lived GitHub token that an older maesttro stored in the sandbox volume. Revoke it on GitHub too: https://github.com/settings/tokens?type=beta";
+function purgeLegacyTokenOnce({
+  config,
+  saveConfig,
+  purge = purgeLegacyToken,
+  announce
+}) {
+  if (config.legacyTokenPurged)
+    return;
+  if (purge())
+    announce(REVOKE_NOTICE);
+  saveConfig({ ...config, legacyTokenPurged: true });
+}
+
+// src/repo.ts
+import { appendFileSync, mkdirSync as mkdirSync3, realpathSync } from "node:fs";
+import { join as join4 } from "node:path";
+var MINIMUM_GIT = [2, 48];
+var WORKTREES_DIR = ".worktrees";
+
+class LaunchError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "LaunchError";
+  }
+}
+function git(run, cwd, args) {
+  const result = run("git", ["-C", cwd, ...args]);
+  return { ok: result.status === 0, out: result.stdout.trim() };
+}
+function parseGitVersion(output) {
+  const match = output.match(/git version (\d+)\.(\d+)/);
+  return match ? [Number(match[1]), Number(match[2])] : undefined;
+}
+function meetsMinimumGit(version) {
+  const [major, minor] = version;
+  return major > MINIMUM_GIT[0] || major === MINIMUM_GIT[0] && minor >= MINIMUM_GIT[1];
+}
+function requireGit(run) {
+  const version = parseGitVersion(run("git", ["--version"]).stdout);
+  const minimum = MINIMUM_GIT.join(".");
+  if (!version) {
+    throw new LaunchError(`git not found. maesttro needs git ${minimum} or newer.`);
+  }
+  if (!meetsMinimumGit(version)) {
+    throw new LaunchError(`git ${version.join(".")} is too old. maesttro needs git ${minimum} or newer; please upgrade.`);
+  }
+}
+function repoRoot(run, cwd) {
+  const top = git(run, cwd, ["rev-parse", "--show-toplevel"]);
+  if (!top.ok) {
+    throw new LaunchError("Run maesttro from the root of a git repository.");
+  }
+  const commonDir = git(run, cwd, [
+    "rev-parse",
+    "--path-format=absolute",
+    "--git-common-dir"
+  ]).out;
+  const root = realpathSync(top.out);
+  if (realpathSync(commonDir) !== join4(root, ".git")) {
+    throw new LaunchError("This is a git worktree. Run maesttro from the main checkout; each session gets its own isolated clone.");
+  }
+  if (realpathSync(cwd) !== root) {
+    throw new LaunchError(`Run maesttro from the repository root: ${root}`);
+  }
+  return root;
+}
+function fetchOrigin(run, root) {
+  return git(run, root, ["fetch", "--quiet", "origin"]).ok;
+}
+function defaultBranch(run, root) {
+  const head = git(run, root, [
+    "symbolic-ref",
+    "--short",
+    "refs/remotes/origin/HEAD"
+  ]);
+  if (head.ok && head.out)
+    return head.out;
+  for (const candidate of ["origin/main", "origin/master"]) {
+    if (git(run, root, ["rev-parse", "--verify", "--quiet", candidate]).ok) {
+      return candidate;
+    }
+  }
+  throw new LaunchError("Can't find the default branch of origin. Run `git remote set-head origin --auto`.");
+}
+function ensureWorktreesDir(run, root) {
+  mkdirSync3(join4(root, WORKTREES_DIR), { recursive: true });
+  if (git(run, root, ["check-ignore", "-q", `${WORKTREES_DIR}/`]).ok)
+    return;
+  const info = join4(root, ".git", "info");
+  mkdirSync3(info, { recursive: true });
+  appendFileSync(join4(info, "exclude"), `
+${WORKTREES_DIR}/
+`);
+}
+function snapshotRefs(run, root) {
+  const listed = git(run, root, [
+    "for-each-ref",
+    "--format=%(refname) %(objectname)",
+    "refs/heads",
+    "refs/tags"
+  ]);
+  const refs = {};
+  for (const line of listed.out.split(`
+`)) {
+    const [name, sha] = line.split(" ");
+    if (name && sha)
+      refs[name] = sha;
+  }
+  return refs;
+}
+function revision(run, root, rev) {
+  const parsed = git(run, root, [
+    "rev-parse",
+    "--verify",
+    "--quiet",
+    `${rev}^{commit}`
+  ]);
+  return parsed.ok ? parsed.out : undefined;
+}
+
+// src/doctor.ts
+async function check(label, probe) {
+  try {
+    const detail = await probe();
+    console.log(`  [ok]   ${label}${detail ? ` — ${detail}` : ""}`);
+    return true;
+  } catch (error) {
+    const reason = error instanceof Error && error.message ? error.message : "";
+    console.log(`  [fail] ${label}${reason ? ` — ${reason}` : ""}`);
+    return false;
+  }
+}
+function inSandbox(command, { withVolume = true } = {}) {
+  const volume = withVolume ? `-v ${VOLUME}:/home/agent ` : "";
+  return execSync2(`docker run --rm ${hostIdentityFlags()} ${volume}${IMAGE} "${command}"`).toString();
+}
+async function doctor() {
+  console.log(`== maesttro doctor ==
+`);
+  const broker = brokerUrl();
+  const checks = [
+    [
+      "Docker daemon reachable",
+      () => {
+        execSync2("docker info", { stdio: "ignore" });
+      }
+    ],
+    [
+      "git on this machine is new enough",
+      () => {
+        requireGit(runCommand);
+        return runCommand("git", ["--version"]).stdout.trim();
+      }
+    ],
+    [
+      "Sandbox image built",
+      () => `built ${execSync2(`docker image inspect ${IMAGE} --format "{{.Created}}"`).toString().trim()}`
+    ],
+    [
+      "Persistent volume exists",
+      () => {
+        execSync2(`docker volume inspect ${VOLUME}`, { stdio: "ignore" });
+      }
+    ],
+    [
+      "No long-lived GitHub token in the volume",
+      () => {
+        if (hasLegacyToken())
+          throw new Error("run `maesttro setup` to remove it");
+      }
+    ],
+    [
+      "Logged in to GitHub",
+      async () => {
+        const token = await currentUserToken({
+          clientId: githubAppClientId(),
+          store: selectCredentialStore(),
+          announce: () => {},
+          interactive: false
+        });
+        if (!token)
+          throw new Error("run `maesttro login`");
+        const name = await githubLogin(token.access_token);
+        if (!name)
+          throw new Error("token rejected, run `maesttro login`");
+        return name;
+      }
+    ],
+    [
+      "Token broker reachable",
+      async () => {
+        if (!await brokerHealthy(broker)) {
+          throw new Error(`${broker} (on the tailnet?)`);
+        }
+        return broker;
+      }
+    ],
+    [
+      "Personal SSH key NOT visible inside sandbox (isolation intact)",
+      () => {
+        const out = inSandbox("cat ~/.ssh/id_rsa 2>&1 || echo MISSING");
+        if (!out.includes("MISSING") && !out.includes("No such file")) {
+          throw new Error("isolation broken");
+        }
+      }
+    ],
+    ...Object.values(CLIENTS).map((client) => [
+      `Client available: ${client.label}`,
+      () => {
+        inSandbox(`which ${client.binary}`, { withVolume: false });
+      }
+    ])
+  ];
+  const results = [];
+  for (const [label, probe] of checks)
+    results.push(await check(label, probe));
+  console.log();
+  if (results.every(Boolean)) {
+    console.log("All checks passed.");
+    return;
+  }
+  console.log("Some checks failed — run `maesttro setup` or `maesttro update` to fix, or check the failing item above.");
+  process.exit(1);
+}
+
+// src/help.ts
+var HELP = `maesttro — isolated sandbox for local coding agents
+
+Usage:
+  maesttro                Start a session from the repo root: new clone, default client (claude)
+  maesttro <client>        Same, with a specific client — see \`maesttro list\`
+  maesttro resume <id>     Continue a kept session in its clone
+  maesttro sessions        List this repo's sessions (\`sessions remove <id>\` to drop one)
+  maesttro push [branch]   Push a branch a session created, after showing what goes out
+  maesttro list            Show available clients
+  maesttro setup           One-time: build image, create volume, log in to GitHub
+  maesttro login           Log in to GitHub (device flow) so sessions get repo access
+  maesttro logout          Remove the stored GitHub credentials
+  maesttro status          Show GitHub login status
+  maesttro configure       Apply maesttro's client configs (also runs inside the sandbox)
+  maesttro update          Update the package and rebuild the image with refreshed client configs
+  maesttro doctor          Health check — Docker, image, volume, GitHub login, broker, isolation, clients
+  maesttro help            Show this message
+`;
+
+// src/launch.ts
+import { execSync as execSync3, spawn } from "node:child_process";
+import { existsSync as existsSync3, rmSync as rmSync5 } from "node:fs";
+import { constants, homedir as homedir4 } from "node:os";
+import { join as join10 } from "node:path";
+
+// src/backup.ts
+import { createHash } from "node:crypto";
+import { mkdirSync as mkdirSync5, readdirSync as readdirSync2, rmSync as rmSync2 } from "node:fs";
+import { basename, join as join6 } from "node:path";
+
+// src/maesttro-home.ts
+import {
+  appendFileSync as appendFileSync2,
+  mkdirSync as mkdirSync4,
+  readFileSync as readFileSync3,
+  renameSync as renameSync2,
+  writeFileSync as writeFileSync3
+} from "node:fs";
+import { homedir as homedir3 } from "node:os";
+import { join as join5 } from "node:path";
+function maesttroHome() {
+  return join5(homedir3(), ".config", "maesttro");
+}
+function configPath() {
+  return join5(maesttroHome(), "config.json");
+}
+function readMaesttroConfig() {
+  try {
+    return JSON.parse(readFileSync3(configPath(), "utf8"));
+  } catch {
+    return {};
+  }
+}
+function writeMaesttroConfig(config) {
+  mkdirSync4(maesttroHome(), { recursive: true, mode: 448 });
+  const temporary = `${configPath()}.tmp`;
+  writeFileSync3(temporary, `${JSON.stringify(config, null, 2)}
+`);
+  renameSync2(temporary, configPath());
+}
+function fileSessionLog(path = join5(maesttroHome(), "maesttro.log")) {
+  return (event, detail) => {
+    try {
+      mkdirSync4(maesttroHome(), { recursive: true, mode: 448 });
+      appendFileSync2(path, `${new Date().toISOString()} ${event}${detail ? ` ${detail}` : ""}
+`);
+    } catch {}
+  };
+}
+
+// src/backup.ts
+var BACKUPS_KEPT = 5;
+function shortHash(value) {
+  return createHash("sha256").update(value).digest("hex").slice(0, 8);
+}
+function backupDir(repoRoot, home = maesttroHome()) {
+  return join6(home, "backups", `${basename(repoRoot)}-${shortHash(repoRoot)}`);
+}
+function refsFingerprint(refs) {
+  const sorted = Object.keys(refs).sort().map((ref) => `${ref} ${refs[ref]}`);
+  return shortHash(sorted.join(`
+`));
+}
+function backupRepo({
+  run,
+  repoRoot,
+  refs,
+  sessionId,
+  dir = backupDir(repoRoot),
+  now = new Date,
+  keep = BACKUPS_KEPT
+}) {
+  if (Object.keys(refs).length === 0)
+    return;
+  mkdirSync5(dir, { recursive: true, mode: 448 });
+  const fingerprint = refsFingerprint(refs);
+  const existing = readdirSync2(dir).filter((name) => name.endsWith(".bundle")).sort();
+  const latest = existing.at(-1);
+  if (latest?.endsWith(`-${fingerprint}.bundle`)) {
+    return { path: join6(dir, latest), reused: true };
+  }
+  const stamp = now.toISOString().replace(/[:.]/g, "-");
+  const path = join6(dir, `${stamp}-${sessionId}-${fingerprint}.bundle`);
+  if (!git(run, repoRoot, ["bundle", "create", "--quiet", path, "--all"]).ok) {
+    return;
+  }
+  for (const stale of [...existing, basename(path)].sort().slice(0, -keep)) {
+    rmSync2(join6(dir, stale), { force: true });
+  }
+  return { path, reused: false };
+}
+
+// src/refresher.ts
+var REFRESH_LEAD_MS = 10 * 60 * 1000;
+var WALL_CLOCK_TICK_MS = 60 * 1000;
+var FIRST_BACKOFF_MS = 5 * 1000;
+var MAX_BACKOFF_MS = 5 * 60 * 1000;
+var nodeTimers = {
+  setTimeout: (callback, ms) => setTimeout(callback, ms).unref(),
+  clearTimeout: (handle) => clearTimeout(handle),
+  setInterval: (callback, ms) => setInterval(callback, ms).unref(),
+  clearInterval: (handle) => clearInterval(handle)
+};
+function startRefresher({
+  initial,
+  refresh,
+  onRefreshed,
+  onFailed,
+  now = Date.now,
+  timers = nodeTimers
+}) {
+  let current = initial;
+  let nextAttemptAt = 0;
+  let backoffMs = FIRST_BACKOFF_MS;
+  let inFlight;
+  let stopped = false;
+  let pending;
+  function refreshDueAt(token) {
+    const expiresAt = Date.parse(token.expires_at);
+    const halfRemaining = (expiresAt - now()) / 2;
+    return expiresAt - Math.min(REFRESH_LEAD_MS, Math.max(halfRemaining, 0));
+  }
+  nextAttemptAt = refreshDueAt(initial);
+  function scheduleAt(at) {
+    timers.clearTimeout(pending);
+    pending = timers.setTimeout(check, Math.max(at - now(), 0));
+  }
+  async function attempt() {
+    try {
+      const token = await refresh();
+      if (stopped)
+        return;
+      current = token;
+      backoffMs = FIRST_BACKOFF_MS;
+      nextAttemptAt = refreshDueAt(token);
+      onRefreshed(token);
+    } catch (error) {
+      if (stopped)
+        return;
+      nextAttemptAt = now() + backoffMs;
+      onFailed(error, backoffMs);
+      backoffMs = Math.min(backoffMs * 2, MAX_BACKOFF_MS);
+    }
+    scheduleAt(nextAttemptAt);
+  }
+  function check() {
+    if (stopped)
+      return Promise.resolve();
+    if (inFlight)
+      return inFlight;
+    if (now() < nextAttemptAt)
+      return Promise.resolve();
+    inFlight = attempt().finally(() => {
+      inFlight = undefined;
+    });
+    return inFlight;
+  }
+  const tick = timers.setInterval(check, WALL_CLOCK_TICK_MS);
+  scheduleAt(nextAttemptAt);
+  return {
+    current: () => current,
+    check,
+    stop: () => {
+      stopped = true;
+      timers.clearTimeout(pending);
+      timers.clearInterval(tick);
+    }
+  };
+}
+
+// src/session-dir.ts
+import {
+  chmodSync as chmodSync2,
+  mkdirSync as mkdirSync6,
+  mkdtempSync,
+  renameSync as renameSync3,
+  rmSync as rmSync3,
+  writeFileSync as writeFileSync4
+} from "node:fs";
+import { tmpdir } from "node:os";
+import { join as join7 } from "node:path";
+var CONTAINER_GH_CONFIG_DIR = "/home/agent/.config/gh-maesttro";
+function writeAtomically(path, content) {
+  const temporary = `${path}.tmp`;
+  writeFileSync4(temporary, content, { mode: 420 });
+  chmodSync2(temporary, 420);
+  renameSync3(temporary, path);
+}
+function hostsYaml(token, user) {
+  return [
+    "github.com:",
+    `    oauth_token: ${JSON.stringify(token)}`,
+    `    user: ${JSON.stringify(user)}`,
+    "    git_protocol: https",
+    ""
+  ].join(`
+`);
+}
+function createSessionDir(parent = tmpdir()) {
+  const root = mkdtempSync(join7(parent, "maesttro-"));
+  chmodSync2(root, 448);
+  const ghDir = join7(root, "gh");
+  mkdirSync6(ghDir);
+  chmodSync2(ghDir, 493);
+  writeAtomically(join7(ghDir, "config.yml"), `version: "1"
+`);
+  return {
+    ghDir,
+    writeToken: (token, user) => writeAtomically(join7(ghDir, "hosts.yml"), hostsYaml(token, user)),
+    writeStatus: (status) => writeAtomically(join7(ghDir, "status"), `${status}
+`),
+    remove: () => rmSync3(root, { recursive: true, force: true })
+  };
+}
+
+// src/github-session.ts
+var UNAVAILABLE = "GitHub access unavailable";
+var WITHOUT = "running without gh";
+function refusalNotice(code, repo) {
+  switch (code) {
+    case "broker_unreachable":
+      return `${UNAVAILABLE} (broker unreachable) — ${WITHOUT}`;
+    case "app_not_installed":
+      return `${UNAVAILABLE}: the GitHub App is not installed on ${repo} — ${WITHOUT}`;
+    case "repo_not_visible_to_user":
+      return `${UNAVAILABLE}: your GitHub account cannot see ${repo} — ${WITHOUT}`;
+    case "user_token_invalid":
+    case "not_logged_in":
+      return `${UNAVAILABLE}: GitHub login expired, run \`maesttro login\` — ${WITHOUT}`;
+    default:
+      return `${UNAVAILABLE} (${code}) — ${WITHOUT}`;
+  }
+}
+function identityEnv(author, committer) {
+  const env = {};
+  if (author) {
+    env.GIT_AUTHOR_NAME = author.name;
+    env.GIT_AUTHOR_EMAIL = author.email;
+  }
+  const effectiveCommitter = committer ?? author;
+  if (effectiveCommitter) {
+    env.GIT_COMMITTER_NAME = effectiveCommitter.name;
+    env.GIT_COMMITTER_EMAIL = effectiveCommitter.email;
+  }
+  return env;
+}
+function withEnvFlags(dockerArgs, env) {
+  return [...dockerArgs, ...Object.keys(env).flatMap((name) => ["-e", name])];
+}
+function errorCode(error) {
+  if (error instanceof BrokerError)
+    return error.code;
+  if (error instanceof Error && error.name === "DeviceFlowError") {
+    return "not_logged_in";
+  }
+  return error instanceof Error && error.message === "not_logged_in" ? "not_logged_in" : "unexpected_error";
+}
+function withoutGitHub(author, notice) {
+  const env = {
+    GH_CONFIG_DIR: CONTAINER_GH_CONFIG_DIR,
+    ...identityEnv(author, undefined)
+  };
+  return {
+    dockerArgs: withEnvFlags([], env),
+    env,
+    notice,
+    close: async () => {}
+  };
+}
+async function openGitHubSession({
+  repo,
+  author,
+  broker,
+  login,
+  log,
+  fetch: fetchImpl = fetch,
+  createDir = createSessionDir
+}) {
+  if (!repo)
+    return withoutGitHub(author);
+  const mint = async ({ interactive }) => {
+    if (!await brokerHealthy(broker, fetchImpl)) {
+      throw new BrokerError("broker_unreachable");
+    }
+    const userToken = await currentUserToken({ ...login, interactive });
+    if (!userToken)
+      throw new Error("not_logged_in");
+    return requestSessionToken({
+      broker,
+      userToken: userToken.access_token,
+      repo,
+      fetch: fetchImpl
+    });
+  };
+  let initial;
+  try {
+    initial = await mint({ interactive: true });
+  } catch (error) {
+    const code = errorCode(error);
+    log("session.github_unavailable", `${repo} ${code}`);
+    return withoutGitHub(author, refusalNotice(code, repo));
+  }
+  const dir = createDir();
+  const publish = (token) => {
+    dir.writeToken(token.token, token.committer.name);
+    dir.writeStatus(`ok, token expires ${token.expires_at}`);
+  };
+  publish(initial);
+  log("session.token_minted", `${repo} expires ${initial.expires_at}`);
+  const refresher = startRefresher({
+    initial,
+    refresh: () => mint({ interactive: false }),
+    onRefreshed: (token) => {
+      publish(token);
+      log("session.token_refreshed", `${repo} expires ${token.expires_at}`);
+    },
+    onFailed: (error, retryInMs) => {
+      const code = errorCode(error);
+      dir.writeStatus(`refresh failing (${code}), retrying in ${Math.round(retryInMs / 1000)}s`);
+      log("session.refresh_failed", `${repo} ${code}`);
+    }
+  });
+  const env = {
+    GH_CONFIG_DIR: CONTAINER_GH_CONFIG_DIR,
+    ...identityEnv(author, initial.committer)
+  };
+  return {
+    dockerArgs: withEnvFlags(["-v", `${dir.ghDir}:${CONTAINER_GH_CONFIG_DIR}:ro`], env),
+    env,
+    close: async () => {
+      refresher.stop();
+      await revokeSessionToken(refresher.current().token, fetchImpl);
+      dir.remove();
+      log("session.closed", repo);
+    }
+  };
+}
+
+// src/prompt.ts
+import { createInterface } from "node:readline";
+function ask(question) {
+  const readline = createInterface({
+    input: process.stdin,
+    output: process.stdout
+  });
+  return new Promise((resolve) => readline.question(question, (answer) => {
+    readline.close();
+    resolve(answer.trim());
+  }));
+}
+
+// src/session-clone.ts
+import {
+  copyFileSync,
+  existsSync as existsSync2,
+  lstatSync,
+  mkdirSync as mkdirSync7,
+  readdirSync as readdirSync3,
+  readFileSync as readFileSync4
+} from "node:fs";
+import { join as join8 } from "node:path";
+
+// src/sanitize.ts
+function stripControl(text) {
+  let out = "";
+  for (const char of text) {
+    const code = char.codePointAt(0) ?? 0;
+    if (code >= 32 && code !== 127)
+      out += char;
+  }
+  return out;
+}
+var VALID_BRANCH = /^[A-Za-z0-9](?:[A-Za-z0-9._/-]*[A-Za-z0-9_-])?$/;
+function isSafeBranchName(name) {
+  if (name.length === 0 || name.length > 255)
+    return false;
+  if (!VALID_BRANCH.test(name))
+    return false;
+  if (name.includes(".."))
+    return false;
+  if (name.includes("//"))
+    return false;
+  if (name.includes("@{"))
+    return false;
+  if (name.endsWith(".lock"))
+    return false;
+  for (const segment of name.split("/")) {
+    if (segment.length === 0 || segment.startsWith(".") || segment.endsWith(".")) {
+      return false;
+    }
+  }
+  return true;
+}
+
+// src/session-clone.ts
+var HARDENING = [
+  "-c",
+  "core.fsmonitor=",
+  "-c",
+  "core.hooksPath=/dev/null",
+  "-c",
+  "core.pager=cat",
+  "-c",
+  "protocol.file.allow=never"
+];
+var SHA = /^[0-9a-f]{40}([0-9a-f]{24})?$/;
+var OBJECT_SUBDIR = /^[0-9a-f]{2}$/;
+var HEADS_PREFIX = "refs/heads/";
+function agentGit(run, dir, args) {
+  return git(run, dir, [...HARDENING, ...args]);
+}
+function createSessionClone(run, root, clonePath, baseSha) {
+  const cloned = git(run, root, [
+    "clone",
+    "--quiet",
+    "--shared",
+    "--no-checkout",
+    root,
+    clonePath
+  ]);
+  if (!cloned.ok) {
+    throw new LaunchError(`Could not create the session clone at ${clonePath}`);
+  }
+  const heads = agentGit(run, clonePath, [
+    "for-each-ref",
+    "--format=delete %(refname)",
+    "refs/heads"
+  ]);
+  if (heads.out) {
+    run("git", ["-C", clonePath, "update-ref", "--stdin"], `${heads.out}
+`);
+  }
+  const detached = agentGit(run, clonePath, ["checkout", "--detach", baseSha]);
+  if (!detached.ok) {
+    throw new LaunchError(`Could not check out ${baseSha} in the session clone`);
+  }
+}
+function realDir(path) {
+  try {
+    return lstatSync(path).isDirectory();
+  } catch {
+    return false;
+  }
+}
+function dirents(dir) {
+  try {
+    return readdirSync3(dir, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+}
+function cloneGitDir(clonePath) {
+  const gitDir = join8(clonePath, ".git");
+  return realDir(gitDir) ? gitDir : undefined;
+}
+function readSha(path) {
+  try {
+    if (!lstatSync(path).isFile())
+      return;
+    const text = readFileSync4(path, "utf8").trim();
+    return SHA.test(text) ? text : undefined;
+  } catch {
+    return;
+  }
+}
+function packedRefs(gitDir) {
+  const refs = new Map;
+  let text;
+  try {
+    text = readFileSync4(join8(gitDir, "packed-refs"), "utf8");
+  } catch {
+    return refs;
+  }
+  for (const line of text.split(`
+`)) {
+    if (!line || line.startsWith("#") || line.startsWith("^"))
+      continue;
+    const [sha, ref] = line.split(" ");
+    if (sha && ref && SHA.test(sha))
+      refs.set(ref, sha);
+  }
+  return refs;
+}
+function cloneBranches(clonePath) {
+  const gitDir = cloneGitDir(clonePath);
+  if (!gitDir)
+    return [];
+  const names = new Set;
+  const walk = (dir, prefix) => {
+    for (const entry of dirents(dir)) {
+      if (entry.isSymbolicLink())
+        continue;
+      const name = prefix ? `${prefix}/${entry.name}` : entry.name;
+      if (entry.isDirectory())
+        walk(join8(dir, entry.name), name);
+      else if (entry.isFile())
+        names.add(name);
+    }
+  };
+  walk(join8(gitDir, "refs", "heads"), "");
+  for (const ref of packedRefs(gitDir).keys()) {
+    if (ref.startsWith(HEADS_PREFIX))
+      names.add(ref.slice(HEADS_PREFIX.length));
+  }
+  return [...names].filter(isSafeBranchName).sort();
+}
+function branchTip(clonePath, branch) {
+  if (!isSafeBranchName(branch))
+    return;
+  const gitDir = cloneGitDir(clonePath);
+  if (!gitDir)
+    return;
+  return readSha(join8(gitDir, "refs", "heads", branch)) ?? packedRefs(gitDir).get(`${HEADS_PREFIX}${branch}`);
+}
+function cloneHead(clonePath) {
+  const gitDir = cloneGitDir(clonePath);
+  if (!gitDir)
+    return;
+  let text;
+  try {
+    if (!lstatSync(join8(gitDir, "HEAD")).isFile())
+      return;
+    text = readFileSync4(join8(gitDir, "HEAD"), "utf8").trim();
+  } catch {
+    return;
+  }
+  if (text.startsWith("ref:")) {
+    const ref = text.slice(4).trim();
+    return ref.startsWith(HEADS_PREFIX) ? { branch: ref.slice(HEADS_PREFIX.length) } : {};
+  }
+  return SHA.test(text) ? { detached: text } : {};
+}
+function cloneHasWork(clonePath, baseSha) {
+  if (cloneBranches(clonePath).length > 0)
+    return true;
+  const head = cloneHead(clonePath);
+  return head?.detached !== undefined && head.detached !== baseSha;
+}
+function copyObjectFiles(fromDir, intoDir) {
+  let created = false;
+  for (const entry of dirents(fromDir)) {
+    if (!entry.isFile())
+      continue;
+    const dest = join8(intoDir, entry.name);
+    if (existsSync2(dest))
+      continue;
+    if (!created) {
+      mkdirSync7(intoDir, { recursive: true });
+      created = true;
+    }
+    copyFileSync(join8(fromDir, entry.name), dest);
+  }
+}
+function importObjects(run, root, clonePath, tip) {
+  const gitDir = cloneGitDir(clonePath);
+  if (!gitDir)
+    return false;
+  const objects = join8(gitDir, "objects");
+  if (!realDir(objects))
+    return false;
+  const into = join8(root, ".git", "objects");
+  for (const entry of dirents(objects)) {
+    if (entry.name === "info" || entry.isSymbolicLink() || !entry.isDirectory()) {
+      continue;
+    }
+    if (!OBJECT_SUBDIR.test(entry.name) && entry.name !== "pack")
+      continue;
+    copyObjectFiles(join8(objects, entry.name), join8(into, entry.name));
+  }
+  return git(run, root, ["cat-file", "-e", `${tip}^{commit}`]).ok;
+}
+
+// src/sessions.ts
+import { randomBytes } from "node:crypto";
+import {
+  mkdirSync as mkdirSync8,
+  readdirSync as readdirSync4,
+  readFileSync as readFileSync5,
+  renameSync as renameSync4,
+  rmSync as rmSync4,
+  writeFileSync as writeFileSync5
+} from "node:fs";
+import { join as join9 } from "node:path";
+function newSessionId() {
+  return `maesttro-${randomBytes(4).toString("hex")}`;
+}
+function sessionsDir(home = maesttroHome()) {
+  return join9(home, "sessions");
+}
+function saveSession(record, dir = sessionsDir()) {
+  mkdirSync8(dir, { recursive: true, mode: 448 });
+  const path = join9(dir, `${record.id}.json`);
+  writeFileSync5(`${path}.tmp`, `${JSON.stringify(record, null, 2)}
+`);
+  renameSync4(`${path}.tmp`, path);
+}
+function readSession(id, dir = sessionsDir()) {
+  try {
+    return JSON.parse(readFileSync5(join9(dir, `${id}.json`), "utf8"));
+  } catch {
+    return;
+  }
+}
+function deleteSession(id, dir = sessionsDir()) {
+  rmSync4(join9(dir, `${id}.json`), { force: true });
+}
+function sessionsForRepo(repoRoot, dir = sessionsDir()) {
+  let names;
+  try {
+    names = readdirSync4(dir).filter((name) => name.endsWith(".json"));
+  } catch {
+    return [];
+  }
+  return names.map((name) => readSession(name.slice(0, -".json".length), dir)).filter((record) => record?.repoRoot === repoRoot).sort((a, b) => a.createdAt.localeCompare(b.createdAt));
+}
+
+// src/workspace-git.ts
+var GITHUB_REMOTE = /^(?:https:\/\/(?:[^@/]+@)?github\.com\/|git@github\.com:|ssh:\/\/git@github\.com\/)([A-Za-z0-9_.-]+)\/([A-Za-z0-9_.-]+?)(?:\.git)?\/?$/;
+function githubRepoFromRemote(remote) {
+  const match = remote.trim().match(GITHUB_REMOTE);
+  return match ? `${match[1]}/${match[2]}` : undefined;
+}
+function gitOutput(run, workspace, args) {
+  const result = run("git", ["-C", workspace, ...args]);
+  const value = result.stdout.trim();
+  return result.status === 0 && value ? value : undefined;
+}
+function workspaceRepo(run, workspace) {
+  const expanded = gitOutput(run, workspace, ["remote", "get-url", "origin"]);
+  const configured = gitOutput(run, workspace, [
+    "config",
+    "--get",
+    "remote.origin.url"
+  ]);
+  return [expanded, configured].map((remote) => remote ? githubRepoFromRemote(remote) : undefined).find(Boolean);
+}
+function workspaceAuthor(run, workspace) {
+  const name = gitOutput(run, workspace, ["config", "user.name"]);
+  const email = gitOutput(run, workspace, ["config", "user.email"]);
+  return name && email ? { name, email } : undefined;
+}
+
+// src/launch.ts
+var CONTAINER_REPO = "/workspace";
+var CONTAINER_PACKAGE = "/opt/maesttro";
+function resolveCommand(args) {
+  const [first, ...rest] = args;
+  if (first === undefined)
+    return CLIENTS[DEFAULT_CLIENT].binary;
+  if (isClientKey(first))
+    return [CLIENTS[first].binary, ...rest].join(" ");
+  return args.join(" ");
+}
+function containerCommand(command) {
+  return `node ${CONTAINER_PACKAGE}/dist/maesttro.js configure || echo "maesttro: in-container setup failed" >&2; ${command}`;
+}
+function sessionMounts({
+  repoRoot,
+  sessionDir,
+  packageRoot,
+  hostHome,
+  stagedPaths,
+  sharedSkills
+}) {
+  const objects = join10(repoRoot, ".git", "objects");
+  const mounts = [
+    { host: VOLUME, container: "/home/agent" },
+    { host: objects, container: objects, readOnly: true },
+    { host: sessionDir, container: CONTAINER_REPO },
+    { host: packageRoot, container: CONTAINER_PACKAGE, readOnly: true },
+    ...stagedPaths.map((path) => ({
+      host: join10(hostHome, path),
+      container: `${HOST_STAGING_DIR}/${path}`,
+      readOnly: true
+    }))
+  ];
+  if (sharedSkills) {
+    mounts.push({
+      host: sharedSkills,
+      container: "/home/agent/.claude/skills",
+      readOnly: true
+    });
+  }
+  return { mounts, workdir: CONTAINER_REPO };
+}
+function dockerRunArgs({
+  command,
+  mounts,
+  workdir,
+  extra = []
+}) {
+  const volumes = mounts.flatMap(({ host, container, readOnly }) => [
+    "-v",
+    `${host}:${container}${readOnly ? ":ro" : ""}`
+  ]);
+  return [
+    "run",
+    "-it",
+    "--rm",
+    ...volumes,
+    ...extra,
+    "-w",
+    workdir,
+    IMAGE,
+    command
+  ];
+}
+function listClients() {
+  const rows = Object.entries(CLIENTS).map(([key, client]) => `  ${key.padEnd(10)} ${client.label}  (${client.npmPackage})`);
+  return [
+    `Available clients:
+`,
+    ...rows,
+    `
+Default: ${DEFAULT_CLIENT}. Run \`maesttro <client>\` to pick one, or \`maesttro <client> -- <args>\` to pass args through.`
+  ].join(`
+`);
+}
+function ensureReady() {
+  try {
+    execSync3(`docker image inspect ${IMAGE}`, { stdio: "ignore" });
+    execSync3(`docker volume inspect ${VOLUME}`, { stdio: "ignore" });
+  } catch {
+    throw new LaunchError("Sandbox isn't set up yet. Run `maesttro setup` first.");
+  }
+}
+function sharedSkillsDir() {
+  const dir = process.env.AGENT_SHARED_SKILLS ?? join10(homedir4(), "agent-shared", "skills");
+  return existsSync3(dir) ? dir : undefined;
+}
+async function resolveAuthor(workspace) {
+  const fromRepo = workspaceAuthor(runCommand, workspace);
+  if (fromRepo)
+    return fromRepo;
+  const config = readMaesttroConfig();
+  if (config.author)
+    return config.author;
+  if (!process.stdin.isTTY)
+    return;
+  console.log("No git identity found for this repo. Commits in the sandbox need an author (stored in ~/.config/maesttro/config.json).");
+  const name = await ask("Author name: ");
+  const email = await ask("Author email: ");
+  if (!name || !email)
+    return;
+  writeMaesttroConfig({ ...config, author: { name, email } });
+  return { name, email };
+}
+function startSession(run, root) {
+  ensureWorktreesDir(run, root);
+  if (!fetchOrigin(run, root)) {
+    console.log("Couldn't fetch origin; starting from the last fetched state.");
+  }
+  const base = defaultBranch(run, root);
+  const baseSha = revision(run, root, base);
+  if (!baseSha)
+    throw new LaunchError(`Can't resolve ${base}.`);
+  const id = newSessionId();
+  const sessionDir = join10(root, WORKTREES_DIR, id);
+  createSessionClone(run, root, sessionDir, baseSha);
+  return {
+    id,
+    repoRoot: root,
+    worktree: sessionDir,
+    base,
+    baseSha,
+    createdAt: new Date().toISOString(),
+    refs: {}
+  };
+}
+function resumeSession(root, id) {
+  const session = readSession(id);
+  if (!session || session.repoRoot !== root) {
+    throw new LaunchError(`No session ${id} in this repo. See \`maesttro sessions\`.`);
+  }
+  if (!existsSync3(session.worktree)) {
+    throw new LaunchError(`The clone for ${id} is gone: ${session.worktree}`);
+  }
+  return session;
+}
+function preserveBranches(run, session) {
+  const preserved = [];
+  for (const branch of cloneBranches(session.worktree)) {
+    const tip = branchTip(session.worktree, branch);
+    if (!tip)
+      continue;
+    if (importObjects(run, session.repoRoot, session.worktree, tip)) {
+      git(run, session.repoRoot, [
+        "update-ref",
+        `refs/maesttro/${session.id}/${branch}`,
+        tip
+      ]);
+      preserved.push(branch);
+    }
+  }
+  return preserved;
+}
+function finishSession(run, session) {
+  if (!existsSync3(session.worktree)) {
+    deleteSession(session.id);
+    return;
+  }
+  const preserved = preserveBranches(run, session);
+  if (!cloneHasWork(session.worktree, session.baseSha)) {
+    rmSync5(session.worktree, { recursive: true, force: true });
+    deleteSession(session.id);
+    return;
+  }
+  const head = cloneHead(session.worktree);
+  const detachedWork = head?.detached !== undefined && head.detached !== session.baseSha;
+  console.log(`
+Session ${session.id} kept. Continue with \`maesttro resume ${session.id}\`.`);
+  if (preserved.length > 0) {
+    console.log(`Branches from this session: ${preserved.join(", ")}. Push with \`maesttro push\`.`);
+  } else if (detachedWork) {
+    console.log("You have commits on a detached HEAD. Resume and `git switch -c <name>` to keep them.");
+  }
+}
+function exitCodeOf(code, signal) {
+  if (code !== null)
+    return code;
+  return signal ? 128 + (constants.signals[signal] ?? 0) : 1;
+}
+var FORWARDED_SIGNALS = ["SIGINT", "SIGTERM", "SIGHUP"];
+async function launch({
+  args,
+  resume
+}) {
+  const run = runCommand;
+  ensureReady();
+  requireGit(run);
+  const root = repoRoot(run, process.cwd());
+  purgeLegacyTokenOnce({
+    config: readMaesttroConfig(),
+    saveConfig: writeMaesttroConfig,
+    announce: (message) => console.log(message)
+  });
+  const started = resume ? resumeSession(root, resume) : startSession(run, root);
+  const backup = backupRepo({
+    run,
+    repoRoot: root,
+    refs: snapshotRefs(run, root),
+    sessionId: started.id
+  });
+  const saved = { ...started, backup: started.backup ?? backup?.path };
+  saveSession(saved);
+  console.log(`Session ${saved.id}: clone .worktrees/${saved.id} at ${saved.base}${backup ? `, backup ${backup.reused ? "reused" : "written"}` : ""}.`);
+  const repo = workspaceRepo(run, root);
+  if (repo && !resume) {
+    git(run, saved.worktree, [
+      "remote",
+      "set-url",
+      "origin",
+      `https://github.com/${repo}.git`
+    ]);
+  }
+  const github = await openGitHubSession({
+    repo,
+    author: await resolveAuthor(root),
+    broker: brokerUrl(),
+    login: {
+      clientId: githubAppClientId(),
+      store: selectCredentialStore(),
+      announce: (message) => console.log(message)
+    },
+    log: fileSessionLog()
+  });
+  if (github.notice)
+    console.log(github.notice);
+  const hostHome = homedir4();
+  const { mounts, workdir } = sessionMounts({
+    repoRoot: root,
+    sessionDir: saved.worktree,
+    packageRoot: PACKAGE_ROOT,
+    hostHome,
+    stagedPaths: STAGED_PATHS.filter((path) => existsSync3(join10(hostHome, path))),
+    sharedSkills: sharedSkillsDir()
+  });
+  const sessionEnv = {
+    ...github.env,
+    MAESTTRO_SESSION_ID: saved.id,
+    MAESTTRO_BASE: saved.base,
+    MAESTTRO_GITHUB: github.notice || !repo ? "off" : "on",
+    ...hostIdentityEnv(),
+    ...repo ? { MAESTTRO_REPO: repo } : {}
+  };
+  const envFlags = [
+    "MAESTTRO_SESSION_ID",
+    "MAESTTRO_BASE",
+    "MAESTTRO_GITHUB",
+    "MAESTTRO_HOST_UID",
+    "MAESTTRO_HOST_GID"
+  ].concat(repo ? ["MAESTTRO_REPO"] : []).flatMap((name) => ["-e", name]);
+  const child = spawn("docker", dockerRunArgs({
+    command: containerCommand(resolveCommand(args)),
+    mounts,
+    workdir,
+    extra: [...github.dockerArgs, ...envFlags]
+  }), { stdio: "inherit", env: { ...process.env, ...sessionEnv } });
+  const forward = (signal) => child.kill(signal);
+  for (const signal of FORWARDED_SIGNALS)
+    process.on(signal, forward);
+  const exitCode = await new Promise((resolve) => {
+    child.on("exit", (code, signal) => resolve(exitCodeOf(code, signal)));
+    child.on("error", () => resolve(127));
+  });
+  for (const signal of FORWARDED_SIGNALS)
+    process.off(signal, forward);
+  await github.close();
+  finishSession(run, saved);
+  process.exit(exitCode);
+}
+
+// src/push.ts
+import { spawnSync as spawnSync2 } from "node:child_process";
+function pushCandidates(sessions) {
+  const candidates = new Map;
+  for (const session of sessions) {
+    const defaultBranch = session.base.replace(/^origin\//, "");
+    for (const branch of cloneBranches(session.worktree)) {
+      if (branch === defaultBranch || !isSafeBranchName(branch))
+        continue;
+      candidates.set(branch, {
+        branch,
+        base: session.base,
+        baseSha: session.baseSha,
+        sessionId: session.id,
+        dir: session.worktree
+      });
+    }
+  }
+  return candidates;
+}
+function planPush({
+  requested,
+  candidates
+}) {
+  const names = [...candidates.keys()];
+  if (requested) {
+    const candidate = candidates.get(requested);
+    if (candidate)
+      return { ok: true, candidate };
+    return {
+      ok: false,
+      candidates: names,
+      reason: `${requested} wasn't created by a maesttro session in this repo (or is the default branch).`
+    };
+  }
+  const [only] = names;
+  if (names.length === 1 && only) {
+    return { ok: true, candidate: candidates.get(only) };
+  }
+  return {
+    ok: false,
+    candidates: names,
+    reason: names.length === 0 ? "No session in this repo has a branch ready to push." : "Several session branches are ready; pick one."
+  };
+}
+async function choose(candidates) {
+  if (!process.stdin.isTTY)
+    return;
+  console.log(candidates.map((name, index) => `  ${index + 1}) ${name}`).join(`
+`));
+  const answer = await ask("Branch to push: ");
+  return candidates[Number(answer) - 1];
+}
+function describe(run, root, branch, base, tip) {
+  const commits = git(run, root, [
+    "log",
+    "--format=  %h %s (%an / %cn)",
+    `${base}..${tip}`
+  ]).out;
+  const stat = git(run, root, ["diff", "--stat", `${base}...${tip}`]).out;
+  return [
+    `Pushing ${branch} to origin (compared with ${base}):`,
+    stripControl(commits) || "  (no new commits)",
+    stat ? `
+${stripControl(stat)}` : ""
+  ].join(`
+`);
+}
+async function push({ args }) {
+  const run = runCommand;
+  const yes = args.includes("--yes") || args.includes("-y");
+  const requested = args.find((arg) => !arg.startsWith("-"));
+  let root;
+  try {
+    root = repoRoot(run, process.cwd());
+  } catch (error) {
+    throw error instanceof LaunchError ? error : new LaunchError(String(error));
+  }
+  const candidates = pushCandidates(sessionsForRepo(root));
+  let plan = planPush({ requested, candidates });
+  if (!plan.ok && !requested && plan.candidates.length > 1) {
+    const picked = await choose(plan.candidates);
+    if (picked)
+      plan = planPush({ requested: picked, candidates });
+  }
+  if (!plan.ok) {
+    console.error(plan.reason);
+    process.exitCode = 1;
+    return;
+  }
+  const { branch, base, baseSha, dir, sessionId } = plan.candidate;
+  const tip = branchTip(dir, branch);
+  if (!tip || !importObjects(run, root, dir, tip)) {
+    console.error(`Could not read ${branch} from session ${sessionId}.`);
+    process.exitCode = 1;
+    return;
+  }
+  git(run, root, ["update-ref", `refs/maesttro/${sessionId}/${branch}`, tip]);
+  console.log(describe(run, root, branch, base, tip));
+  if (!yes) {
+    if (!process.stdin.isTTY) {
+      console.error("Not a terminal; re-run with --yes to push without confirming.");
+      process.exitCode = 1;
+      return;
+    }
+    const answer = await ask(`
+Push? [y/N] `);
+    if (!/^y(es)?$/i.test(answer)) {
+      console.log("Not pushed.");
+      return;
+    }
+  }
+  const pushed = spawnSync2("git", ["-C", root, "push", "origin", `${tip}:refs/heads/${branch}`], { stdio: "inherit" });
+  if (pushed.status === 0) {
+    console.log(`Pushed ${branch}. Base for comparison was ${baseSha.slice(0, 8)}.`);
+  }
+  process.exitCode = pushed.status ?? 1;
+}
+
+// src/sessions-command.ts
+import { existsSync as existsSync4, rmSync as rmSync6 } from "node:fs";
+function sessionsCommand({ args }) {
+  const run = runCommand;
+  const root = repoRoot(run, process.cwd());
+  const [action, id] = args;
+  if (action === "remove") {
+    const session = id ? readSession(id) : undefined;
+    if (!session || session.repoRoot !== root) {
+      console.error(`No session ${id ?? "(missing id)"} in this repo.`);
+      process.exitCode = 1;
+      return;
+    }
+    if (existsSync4(session.worktree)) {
+      const preserved = preserveBranches(run, session);
+      const head = cloneHead(session.worktree);
+      if (preserved.length === 0 && head?.detached !== undefined && head.detached !== session.baseSha) {
+        console.error(`${session.id} has commits on a detached HEAD not on any branch; resume and create a branch first.`);
+        process.exitCode = 1;
+        return;
+      }
+      rmSync6(session.worktree, { recursive: true, force: true });
+      const kept = preserved.length > 0 ? ` Its branches are kept as refs/maesttro/${session.id}/*.` : "";
+      console.log(`Removed session ${session.id}.${kept}`);
+    } else {
+      console.log(`Removed session ${session.id}.`);
+    }
+    deleteSession(session.id);
+    return;
+  }
+  const sessions = sessionsForRepo(root);
+  if (sessions.length === 0) {
+    console.log("No maesttro sessions in this repo.");
+    return;
+  }
+  for (const session of sessions) {
+    const branches = existsSync4(session.worktree) ? cloneBranches(session.worktree) : undefined;
+    const where = branches === undefined ? "clone missing" : branches.length > 0 ? `branches: ${branches.join(", ")}` : "no branches yet";
+    console.log(`  ${session.id}  ${session.createdAt.slice(0, 16)}  ${where}`);
+  }
+  console.log("\n`maesttro resume <id>` continues one; `maesttro sessions remove <id>` removes its clone.");
+}
+
+// src/setup.ts
+import { execSync as execSync4 } from "node:child_process";
+function run(command) {
+  execSync4(command, { stdio: "inherit" });
+}
+function ensureDocker() {
+  try {
+    execSync4("docker info", { stdio: "ignore" });
+  } catch {
+    console.error("Docker doesn't seem to be running. Start Docker Desktop (or the docker daemon) and try again.");
+    process.exit(1);
+  }
+}
+async function setup({ args }) {
+  console.log(`== maesttro setup ==
+`);
+  ensureDocker();
+  console.log("-> Building sandbox image (this pulls node:22-slim + installs CLIs, first run only)...");
+  run(`docker build -t ${IMAGE} "${DOCKERFILE_DIR}"`);
+  console.log(`
+-> Ensuring persistent volume exists...`);
+  execSync4(`docker volume create ${VOLUME}`, { stdio: "ignore" });
+  console.log(`
+-> Removing any long-lived GitHub token from the volume...`);
+  if (purgeLegacyToken())
+    console.log(`   ${REVOKE_NOTICE}`);
+  writeMaesttroConfig({ ...readMaesttroConfig(), legacyTokenPurged: true });
+  if (args[0]) {
+    console.log("   Ignoring the token argument: sessions now get short-lived tokens through `maesttro login`.");
+  }
+  console.log(`
+-> Logging in to GitHub...`);
+  await ensureLogin();
+  console.log(`
+-> Verifying isolation...`);
+  console.log("   personal SSH key should NOT be visible:");
+  run(`docker run --rm ${hostIdentityFlags()} -v ${VOLUME}:/home/agent ${IMAGE} "cat ~/.ssh/id_rsa 2>&1 || true"`);
+  console.log("\nSetup complete. Run `maesttro` from any project directory to start a session,");
+  console.log("or `maesttro list` to see available clients.");
+}
+
+// src/update.ts
+import { execSync as execSync5 } from "node:child_process";
+import { readFileSync as readFileSync6 } from "node:fs";
+import { join as join11 } from "node:path";
+function installedPackageName() {
+  const manifest = JSON.parse(readFileSync6(join11(PACKAGE_ROOT, "package.json"), "utf8"));
+  return manifest.name;
+}
+function update() {
+  console.log(`== maesttro update ==
+`);
+  const packageName = installedPackageName();
+  console.log(`-> Updating ${packageName} package...`);
+  execSync5(`npm i -g ${packageName}@latest`, { stdio: "inherit" });
+  console.log(`
+-> Rebuilding sandbox image with refreshed client configs...`);
+  execSync5(`docker build -t ${IMAGE} "${DOCKERFILE_DIR}"`, { stdio: "inherit" });
+  console.log(`
+Update complete. Bot identity and your project files are untouched —`);
+  console.log("only the image (client versions + curated configs) was refreshed.");
+}
+
+// src/main.ts
+var defaultCommands = {
+  launch,
+  push,
+  sessions: sessionsCommand,
+  configure: () => configure(),
+  setup,
+  update,
+  doctor,
+  login,
+  logout,
+  status,
+  print: (text) => console.log(text)
+};
+async function main(argv, commands = defaultCommands) {
+  const [command, ...rest] = argv;
+  switch (command) {
+    case undefined:
+      await commands.launch({ args: [] });
+      return;
+    case "setup":
+      await commands.setup({ args: rest });
+      return;
+    case "update":
+      await commands.update();
+      return;
+    case "doctor":
+      await commands.doctor();
+      return;
+    case "login":
+      await commands.login();
+      return;
+    case "logout":
+      await commands.logout();
+      return;
+    case "status":
+      await commands.status();
+      return;
+    case "push":
+      await commands.push({ args: rest });
+      return;
+    case "sessions":
+      await commands.sessions({ args: rest });
+      return;
+    case "resume": {
+      const [id, ...clientArgs] = rest;
+      if (!id) {
+        commands.print("Usage: maesttro resume <session-id> [client] [args...]");
+        return;
+      }
+      await commands.launch({ args: clientArgs, resume: id });
+      return;
+    }
+    case "configure":
+      await commands.configure();
+      return;
+    case "list":
+      commands.print(listClients());
+      return;
+    case "help":
+    case "--help":
+    case "-h":
+      commands.print(HELP);
+      return;
+    default:
+      await commands.launch({ args: argv });
+  }
+}
+
+// src/cli.ts
+main(process.argv.slice(2)).catch((error) => {
+  console.error(error instanceof Error ? error.message : String(error));
+  process.exit(1);
+});