syntaur 0.5.0 → 0.5.2

package/dist/index.js

@@ -555,6 +555,53 @@ var init_fs_migration = __esm({
 // src/utils/config.ts
 import { readFile as readFile2 } from "fs/promises";
 import { resolve as resolve3, isAbsolute } from "path";
+function parseAgentCommand(value, agentId) {
+  if (typeof value !== "string" || value.trim() === "") {
+    throw new AgentConfigError(
+      `agent${agentId ? ` "${agentId}"` : ""} has empty command`
+    );
+  }
+  const expanded = expandHome(value.trim());
+  if (isAbsolute(expanded)) {
+    return resolve3(expanded);
+  }
+  if (expanded.includes("/")) {
+    throw new AgentConfigError(
+      `agent${agentId ? ` "${agentId}"` : ""} command "${value}" is a relative path \u2014 use an absolute path or a bare binary name`
+    );
+  }
+  return expanded;
+}
+function validateAgentList(agents) {
+  const seen = /* @__PURE__ */ new Set();
+  let defaults = 0;
+  for (const agent of agents) {
+    if (!AGENT_ID_PATTERN.test(agent.id)) {
+      throw new AgentConfigError(
+        `agent id "${agent.id}" is invalid \u2014 must match /^[a-z0-9][a-z0-9_-]*$/`
+      );
+    }
+    if (seen.has(agent.id)) {
+      throw new AgentConfigError(`duplicate agent id "${agent.id}"`);
+    }
+    seen.add(agent.id);
+    if (!agent.label || agent.label.trim() === "") {
+      throw new AgentConfigError(`agent "${agent.id}" has empty label`);
+    }
+    parseAgentCommand(agent.command, agent.id);
+    if (agent.promptArgPosition !== void 0 && !PROMPT_ARG_POSITIONS.includes(agent.promptArgPosition)) {
+      throw new AgentConfigError(
+        `agent "${agent.id}" has invalid promptArgPosition "${agent.promptArgPosition}" \u2014 expected first|last|none`
+      );
+    }
+    if (agent.default) defaults++;
+  }
+  if (defaults > 1) {
+    throw new AgentConfigError(
+      `more than one agent is marked default: true (only one is allowed)`
+    );
+  }
+}
 function cloneDefaultConfig() {
   return {
     ...DEFAULT_CONFIG,
@@ -571,9 +618,14 @@ function cloneDefaultConfig() {
       definitions: DEFAULT_CONFIG.types.definitions.map((d) => ({ ...d })),
       default: DEFAULT_CONFIG.types.default
     } : null,
+    agents: DEFAULT_CONFIG.agents ? DEFAULT_CONFIG.agents.map((a) => ({
+      ...a,
+      ...a.args ? { args: [...a.args] } : {}
+    })) : null,
     playbooks: {
       disabled: [...DEFAULT_CONFIG.playbooks.disabled]
-    }
+    },
+    theme: DEFAULT_CONFIG.theme ? { ...DEFAULT_CONFIG.theme } : null
   };
 }
 function parseFrontmatter(content) {
@@ -823,6 +875,71 @@ ${normalizedFm}
 ---${afterFrontmatter}`;
   await writeFileForce(configPath, newContent);
 }
+function parseThemeConfig(content) {
+  const match = content.match(/^---\n([\s\S]*?)\n---/);
+  if (!match) return null;
+  const fmBlock = match[1];
+  const blockStart = fmBlock.match(/^theme:\s*$/m);
+  if (!blockStart) return null;
+  const startIdx = fmBlock.indexOf(blockStart[0]) + blockStart[0].length;
+  const remaining = fmBlock.slice(startIdx).split("\n");
+  let preset = null;
+  for (const line of remaining) {
+    const trimmed = line.trimStart();
+    const indent = line.length - trimmed.length;
+    if (indent === 0 && trimmed.length > 0) break;
+    if (trimmed === "") continue;
+    if (indent === 2 && trimmed.startsWith("preset:")) {
+      const value = trimmed.slice("preset:".length).trim().replace(/^["']|["']$/g, "");
+      if (value.length > 0) preset = value;
+    }
+  }
+  if (!preset) return null;
+  return { preset };
+}
+function serializeThemeConfig(theme) {
+  return ["theme:", `  preset: ${theme.preset}`].join("\n");
+}
+async function writeThemeConfig(theme) {
+  const configPath = resolve3(syntaurRoot(), "config.md");
+  const themeBlock = serializeThemeConfig(theme);
+  const existing = await fileExists(configPath) ? await readFile2(configPath, "utf-8") : renderConfig({ defaultProjectDir: defaultProjectDir() });
+  const fmMatch = existing.match(/^(---\n)([\s\S]*?)\n(---)/);
+  if (!fmMatch) {
+    const content = `---
+version: "2.0"
+defaultProjectDir: ${defaultProjectDir()}
+${themeBlock}
+---
+${existing}`;
+    await writeFileForce(configPath, content);
+    return;
+  }
+  const fmBlock = fmMatch[2];
+  const afterFrontmatter = existing.slice(fmMatch[0].length);
+  const cleanedFm = stripTopLevelBlock(fmBlock, "theme");
+  const newFm = `${cleanedFm}
+${themeBlock}`.replace(/^\n+/, "");
+  const normalizedFm = newFm.replace(/\n+$/, "");
+  const newContent = `---
+${normalizedFm}
+---${afterFrontmatter}`;
+  await writeFileForce(configPath, newContent);
+}
+async function deleteThemeConfig() {
+  const configPath = resolve3(syntaurRoot(), "config.md");
+  if (!await fileExists(configPath)) return;
+  const existing = await readFile2(configPath, "utf-8");
+  const fmMatch = existing.match(/^(---\n)([\s\S]*?)\n(---)/);
+  if (!fmMatch) return;
+  const fmBlock = fmMatch[2];
+  const afterFrontmatter = existing.slice(fmMatch[0].length);
+  const cleanedFm = stripTopLevelBlock(fmBlock, "theme");
+  const newContent = `---
+${cleanedFm}
+---${afterFrontmatter}`;
+  await writeFileForce(configPath, newContent);
+}
 function stripTopLevelBlock(fmBlock, key) {
   const blockStart = fmBlock.match(new RegExp(`^${key}:\\s*$`, "m"));
   if (!blockStart) {
@@ -859,6 +976,226 @@ function parseOptionalAbsolutePath(value, fieldName) {
   }
   return resolve3(expanded);
 }
+function parseAgentsConfig(content) {
+  const match = content.match(/^---\n([\s\S]*?)\n---/);
+  if (!match) return null;
+  const fmBlock = match[1];
+  const agentsStart = fmBlock.match(/^agents:\s*$/m);
+  if (!agentsStart) return null;
+  const startIdx = fmBlock.indexOf(agentsStart[0]) + agentsStart[0].length;
+  const remaining = fmBlock.slice(startIdx);
+  const lines = remaining.split("\n");
+  const agents = [];
+  let current = null;
+  let argsCapture = null;
+  let argsBaseIndent = 0;
+  function flushCurrent() {
+    if (!current) return;
+    if (!current.id || !current.command || !current.label) {
+      current = null;
+      return;
+    }
+    agents.push({
+      id: current.id,
+      label: current.label,
+      command: current.command,
+      ...current.args && current.args.length > 0 ? { args: current.args } : {},
+      ...current.promptArgPosition ? { promptArgPosition: current.promptArgPosition } : {},
+      ...current.default ? { default: true } : {},
+      ...current.resolveFromShellAliases ? { resolveFromShellAliases: true } : {}
+    });
+    current = null;
+    argsCapture = null;
+  }
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    const trimmed = line.trimStart();
+    const indent = line.length - trimmed.length;
+    if (indent === 0 && trimmed !== "" && !trimmed.startsWith("#")) {
+      break;
+    }
+    if (argsCapture) {
+      if (indent > argsBaseIndent && trimmed.startsWith("- ")) {
+        argsCapture.push(decodeYamlScalar(trimmed.slice(2).trim()));
+        continue;
+      } else {
+        argsCapture = null;
+        if (current) current.args = current.args ?? [];
+      }
+    }
+    if (indent === 2 && trimmed.startsWith("- ")) {
+      flushCurrent();
+      current = {};
+      const rest = trimmed.slice(2).trim();
+      const colonIdx = rest.indexOf(":");
+      if (colonIdx > 0) {
+        const k = rest.slice(0, colonIdx).trim();
+        const v = rest.slice(colonIdx + 1).trim();
+        assignAgentField(current, k, v);
+      }
+      continue;
+    }
+    if (indent >= 4 && current) {
+      const colonIdx = trimmed.indexOf(":");
+      if (colonIdx <= 0) continue;
+      const k = trimmed.slice(0, colonIdx).trim();
+      const v = trimmed.slice(colonIdx + 1).trim();
+      if (k === "args" && v === "") {
+        argsCapture = [];
+        argsBaseIndent = indent;
+        current.args = argsCapture;
+        continue;
+      }
+      assignAgentField(current, k, v);
+    }
+  }
+  flushCurrent();
+  if (agents.length === 0) return [];
+  return agents;
+}
+function normalizeAgentsFromConfig(agents) {
+  if (agents === null) return null;
+  try {
+    const normalized = agents.map((agent) => ({
+      ...agent,
+      command: parseAgentCommand(agent.command, agent.id)
+    }));
+    validateAgentList(normalized);
+    return normalized;
+  } catch (err2) {
+    const msg = err2 instanceof Error ? err2.message : String(err2);
+    console.warn(
+      `Warning: ~/.syntaur/config.md agents block is invalid (${msg}) \u2014 using built-in defaults`
+    );
+    return null;
+  }
+}
+function decodeYamlScalar(value) {
+  const trimmed = value.trim();
+  if (trimmed.length >= 2 && trimmed.startsWith('"') && trimmed.endsWith('"')) {
+    const body = trimmed.slice(1, -1);
+    let out = "";
+    for (let i = 0; i < body.length; i++) {
+      const ch = body[i];
+      if (ch === "\\" && i + 1 < body.length) {
+        const next = body[i + 1];
+        switch (next) {
+          case "\\":
+            out += "\\";
+            break;
+          case '"':
+            out += '"';
+            break;
+          case "n":
+            out += "\n";
+            break;
+          case "t":
+            out += "	";
+            break;
+          case "r":
+            out += "\r";
+            break;
+          default:
+            out += next;
+            break;
+        }
+        i++;
+        continue;
+      }
+      out += ch;
+    }
+    return out;
+  }
+  if (trimmed.length >= 2 && trimmed.startsWith("'") && trimmed.endsWith("'")) {
+    return trimmed.slice(1, -1).replace(/''/g, "'");
+  }
+  return trimmed;
+}
+function assignAgentField(target, key, rawValue) {
+  const value = decodeYamlScalar(rawValue);
+  switch (key) {
+    case "id":
+      target.id = value;
+      break;
+    case "label":
+      target.label = value;
+      break;
+    case "command":
+      target.command = value;
+      break;
+    case "promptArgPosition":
+      target.promptArgPosition = value;
+      break;
+    case "default":
+      target.default = value === "true";
+      break;
+    case "resolveFromShellAliases":
+      target.resolveFromShellAliases = value === "true";
+      break;
+  }
+}
+function yamlQuoteScalar(value) {
+  if (/[\r\n]/.test(value)) {
+    throw new AgentConfigError(
+      `value contains newlines, which the agents config serializer does not support: ${JSON.stringify(value)}`
+    );
+  }
+  if (value === "" || /[:#{}[\],&*?|>!%@`"'\\\t]/.test(value) || /^\s|\s$/.test(value)) {
+    const escaped = value.replace(/\\/g, "\\\\").replace(/"/g, '\\"').replace(/\t/g, "\\t");
+    return `"${escaped}"`;
+  }
+  return value;
+}
+function serializeAgentsConfig(agents) {
+  const lines = ["agents:"];
+  for (const a of agents) {
+    lines.push(`  - id: ${yamlQuoteScalar(a.id)}`);
+    lines.push(`    label: ${yamlQuoteScalar(a.label)}`);
+    lines.push(`    command: ${yamlQuoteScalar(a.command)}`);
+    if (a.args && a.args.length > 0) {
+      lines.push(`    args:`);
+      for (const arg of a.args) {
+        lines.push(`      - ${yamlQuoteScalar(arg)}`);
+      }
+    }
+    if (a.promptArgPosition && a.promptArgPosition !== "first") {
+      lines.push(`    promptArgPosition: ${a.promptArgPosition}`);
+    }
+    if (a.default) {
+      lines.push(`    default: true`);
+    }
+    if (a.resolveFromShellAliases) {
+      lines.push(`    resolveFromShellAliases: true`);
+    }
+  }
+  return lines.join("\n");
+}
+async function writeAgentsConfig(agents) {
+  validateAgentList(agents);
+  const configPath = resolve3(syntaurRoot(), "config.md");
+  const agentsBlock = serializeAgentsConfig(agents);
+  const existing = await fileExists(configPath) ? await readFile2(configPath, "utf-8") : renderConfig({ defaultProjectDir: defaultProjectDir() });
+  const fmMatch = existing.match(/^(---\n)([\s\S]*?)\n(---)/);
+  if (!fmMatch) {
+    const content = `---
+version: "2.0"
+defaultProjectDir: ${defaultProjectDir()}
+${agentsBlock}
+---
+${existing}`;
+    await writeFileForce(configPath, content.replace(/\n\n---/, "\n---"));
+    return;
+  }
+  const fmBlock = fmMatch[2];
+  const afterFrontmatter = existing.slice(fmMatch[0].length);
+  const cleanedFm = stripTopLevelBlock(fmBlock, "agents");
+  const newFm = `${cleanedFm}
+${agentsBlock}`.replace(/^\n+/, "").replace(/\n+$/, "");
+  const newContent = `---
+${newFm}
+---${afterFrontmatter}`;
+  await writeFileForce(configPath, newContent);
+}
 async function writeStatusConfig(statuses) {
   const configPath = resolve3(syntaurRoot(), "config.md");
   const statusBlock = serializeStatusConfig(statuses);
@@ -1052,7 +1389,10 @@ async function readConfig() {
     },
     agentDefaults: {
       trustLevel: fm["agentDefaults.trustLevel"] || DEFAULT_CONFIG.agentDefaults.trustLevel,
-      autoApprove: fm["agentDefaults.autoApprove"] === "true" || DEFAULT_CONFIG.agentDefaults.autoApprove
+      autoApprove: fm["agentDefaults.autoApprove"] === "true" || DEFAULT_CONFIG.agentDefaults.autoApprove,
+      autoCreateWorktree: AUTO_CREATE_WORKTREE_VALUES.includes(
+        fm["agentDefaults.autoCreateWorktree"]
+      ) ? fm["agentDefaults.autoCreateWorktree"] : DEFAULT_CONFIG.agentDefaults.autoCreateWorktree
     },
     integrations: {
       claudePluginDir: parseOptionalAbsolutePath(
@@ -1076,10 +1416,26 @@ async function readConfig() {
     } : null,
     statuses: parseStatusConfig(content),
     types: null,
-    playbooks: parsePlaybooksConfig(fmBlock)
+    agents: normalizeAgentsFromConfig(parseAgentsConfig(content)),
+    playbooks: parsePlaybooksConfig(fmBlock),
+    theme: parseThemeConfig(content)
   };
 }
-var DEFAULT_CONFIG, migratedConfigPaths;
+function getAgents(config) {
+  return config.agents ?? BUILTIN_AGENTS;
+}
+async function updateAgentsConfig(mutation, options = {}) {
+  const config = await readConfig();
+  const previous = config.agents ?? [...BUILTIN_AGENTS];
+  const next = mutation.apply(previous);
+  validateAgentList(next);
+  if (options.dryRun) {
+    return { previous, next, written: false };
+  }
+  await writeAgentsConfig(next);
+  return { previous, next, written: true };
+}
+var DEFAULT_CONFIG, BUILTIN_AGENTS, AGENT_ID_PATTERN, PROMPT_ARG_POSITIONS, AUTO_CREATE_WORKTREE_VALUES, AgentConfigError, migratedConfigPaths;
 var init_config2 = __esm({
   "src/utils/config.ts"() {
     "use strict";
@@ -1095,7 +1451,8 @@ var init_config2 = __esm({
       },
       agentDefaults: {
         trustLevel: "medium",
-        autoApprove: false
+        autoApprove: false,
+        autoCreateWorktree: "ask"
       },
       integrations: {
         claudePluginDir: null,
@@ -1105,9 +1462,20 @@ var init_config2 = __esm({
       backup: null,
       statuses: null,
       types: null,
+      agents: null,
       playbooks: {
         disabled: []
-      }
+      },
+      theme: null
+    };
+    BUILTIN_AGENTS = [
+      { id: "claude", label: "Claude", command: "claude", default: true },
+      { id: "codex", label: "Codex", command: "codex" }
+    ];
+    AGENT_ID_PATTERN = /^[a-z0-9][a-z0-9_-]*$/;
+    PROMPT_ARG_POSITIONS = ["first", "last", "none"];
+    AUTO_CREATE_WORKTREE_VALUES = ["skip", "ask", "always"];
+    AgentConfigError = class extends Error {
     };
     migratedConfigPaths = /* @__PURE__ */ new Set();
   }
@@ -1283,6 +1651,12 @@ var init_state_machine = __esm({
 });
 
 // src/lifecycle/frontmatter.ts
+var frontmatter_exports = {};
+__export(frontmatter_exports, {
+  parseAssignmentFrontmatter: () => parseAssignmentFrontmatter,
+  updateAssignmentFile: () => updateAssignmentFile,
+  updateAssignmentWorkspace: () => updateAssignmentWorkspace
+});
 function extractFrontmatter2(fileContent) {
   const match = fileContent.match(/^---\n([\s\S]*?)\n---/);
   if (!match) {
@@ -1435,6 +1809,62 @@ function updateAssignmentFile(fileContent, updates) {
   }
   return result;
 }
+function findWorkspaceBlock(fmBlock) {
+  const headerMatch = fmBlock.match(/^workspace:\s*$/m);
+  if (!headerMatch) return null;
+  const headerStart = fmBlock.indexOf(headerMatch[0]);
+  const bodyStart = headerStart + headerMatch[0].length + 1;
+  const after = fmBlock.slice(bodyStart);
+  const lines = after.split("\n");
+  let consumed = 0;
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    if (line.length === 0) {
+      consumed += line.length + 1;
+      continue;
+    }
+    if (line[0] !== " ") break;
+    consumed += line.length + 1;
+  }
+  const bodyEnd = Math.min(bodyStart + consumed, fmBlock.length);
+  return { headerStart, bodyStart, bodyEnd };
+}
+function updateAssignmentWorkspace(fileContent, partial) {
+  const fmMatch = fileContent.match(/^(---\n)([\s\S]*?)(\n---)/);
+  if (!fmMatch) {
+    throw new Error("No frontmatter found in assignment file. Expected --- delimiters.");
+  }
+  const fmBlock = fmMatch[2];
+  const fields = ["repository", "worktreePath", "branch", "parentBranch"];
+  const block = findWorkspaceBlock(fmBlock);
+  let newFm = fmBlock;
+  if (block) {
+    let body = fmBlock.slice(block.bodyStart, block.bodyEnd);
+    for (const field of fields) {
+      if (!(field in partial)) continue;
+      const value = partial[field] ?? null;
+      const formatted = formatYamlValue(value);
+      const lineRegex = new RegExp(`^(\\s+${field}:)\\s*.*$`, "m");
+      if (lineRegex.test(body)) {
+        body = body.replace(lineRegex, `$1 ${formatted}`);
+      } else {
+        const trimmed = body.replace(/\n+$/, "");
+        body = `${trimmed}${trimmed.length > 0 ? "\n" : ""}  ${field}: ${formatted}
+`;
+      }
+    }
+    newFm = fmBlock.slice(0, block.bodyStart) + body + fmBlock.slice(block.bodyEnd);
+  } else {
+    const lines = ["workspace:"];
+    for (const field of fields) {
+      const value = field in partial ? partial[field] ?? null : null;
+      lines.push(`  ${field}: ${formatYamlValue(value)}`);
+    }
+    newFm = `${fmBlock.replace(/\n+$/, "")}
+${lines.join("\n")}`;
+  }
+  return `${fmMatch[1]}${newFm}${fmMatch[3]}${fileContent.slice(fmMatch[0].length)}`;
+}
 var init_frontmatter = __esm({
   "src/lifecycle/frontmatter.ts"() {
     "use strict";
@@ -4672,7 +5102,7 @@ function App({ projectsDir: projectsDir2, onLaunch }) {
     collapseNode,
     currentNode
   } = useTreeState(nodes, filteredIds);
-  useInput((input3, key) => {
+  useInput((input4, key) => {
     if (searchActive) {
       if (key.escape) {
         setSearchActive(false);
@@ -4685,19 +5115,19 @@ function App({ projectsDir: projectsDir2, onLaunch }) {
       }
       return;
     }
-    if (input3 === "q" || key.escape) {
+    if (input4 === "q" || key.escape) {
       exit();
       return;
     }
-    if (input3 === "/") {
+    if (input4 === "/") {
       setSearchActive(true);
       return;
     }
-    if (key.upArrow || input3 === "k") {
+    if (key.upArrow || input4 === "k") {
       moveUp();
       return;
     }
-    if (key.downArrow || input3 === "j") {
+    if (key.downArrow || input4 === "j") {
       moveDown();
       return;
     }
@@ -4786,22 +5216,71 @@ var init_App = __esm({
 // src/tui/launch.ts
 var launch_exports = {};
 __export(launch_exports, {
-  launchAgent: () => launchAgent
+  INITIAL_PROMPT: () => INITIAL_PROMPT,
+  buildAgentArgv: () => buildAgentArgv,
+  formatFallbackCwdWarning: () => formatFallbackCwdWarning,
+  launchAgent: () => launchAgent,
+  shellQuote: () => shellQuote
 });
 import { spawn as spawn2 } from "child_process";
 import { mkdir as mkdir5, writeFile as writeFile9 } from "fs/promises";
-import { resolve as resolve32 } from "path";
+import { isAbsolute as isAbsolute3, resolve as resolve32 } from "path";
+function formatFallbackCwdWarning(opts) {
+  const missing = [];
+  if (!opts.worktreePath) missing.push("worktreePath");
+  if (!opts.branch) missing.push("branch");
+  if (missing.length === 0) return null;
+  const fields = missing.map((m) => `workspace.${m}`).join(" and ");
+  return `syntaur: ${fields} not set for ${opts.assignmentSlug} \u2014 launching in ${opts.workspaceDir}`;
+}
+function shellQuote(arg) {
+  if (arg === "") return "''";
+  return `'${arg.replace(/'/g, `'\\''`)}'`;
+}
+function buildAgentArgv(agent, prompt, env = process.env) {
+  const position = agent.promptArgPosition ?? "first";
+  const baseArgs = [...agent.args ?? []];
+  const agentArgs = position === "first" ? [prompt, ...baseArgs] : position === "last" ? [...baseArgs, prompt] : baseArgs;
+  if (agent.resolveFromShellAliases) {
+    const requested = env.SHELL;
+    let shell = requested;
+    let warning = null;
+    if (!shell || !isAbsolute3(shell)) {
+      warning = `syntaur: $SHELL ${requested ? `("${requested}") is not absolute` : "is unset"} \u2014 falling back to /bin/sh for shell-alias resolution`;
+      shell = "/bin/sh";
+    }
+    const quoted = [agent.command, ...agentArgs].map(shellQuote).join(" ");
+    return {
+      argv: { command: shell, args: ["-i", "-c", quoted] },
+      shellFallbackWarning: warning
+    };
+  }
+  return {
+    argv: { command: agent.command, args: agentArgs },
+    shellFallbackWarning: null
+  };
+}
 async function launchAgent(options) {
-  const { projectsDir: projectsDir2, projectSlug, assignmentSlug, agent } = options;
-  const command = AGENT_COMMANDS[agent];
+  const { projectsDir: projectsDir2, projectSlug, assignmentSlug, agent, cwdOverride } = options;
+  const exitWith = options.onExit ?? ((code) => process.exit(code));
   const detail = await getAssignmentDetail(projectsDir2, projectSlug, assignmentSlug);
   if (!detail) {
     console.error(`Assignment not found: ${projectSlug}/${assignmentSlug}`);
     process.exit(1);
   }
-  const workspaceDir = detail.workspace.worktreePath ?? (detail.workspace.repository?.startsWith("/") ? detail.workspace.repository : null) ?? process.cwd();
   const projectDir = resolve32(projectsDir2, projectSlug);
   const assignmentDir = resolve32(projectDir, "assignments", assignmentSlug);
+  const resolvedFromWorkspace = cwdOverride ?? detail.workspace.worktreePath ?? (detail.workspace.repository?.startsWith("/") ? detail.workspace.repository : null);
+  const workspaceDir = resolvedFromWorkspace ?? process.cwd();
+  if (!cwdOverride) {
+    const warning = formatFallbackCwdWarning({
+      assignmentSlug,
+      workspaceDir,
+      worktreePath: detail.workspace.worktreePath,
+      branch: detail.workspace.branch
+    });
+    if (warning) console.warn(warning);
+  }
   const contextDir = resolve32(workspaceDir, ".syntaur");
   await mkdir5(contextDir, { recursive: true });
   const context = {
@@ -4818,39 +5297,161 @@ async function launchAgent(options) {
     resolve32(contextDir, "context.json"),
     JSON.stringify(context, null, 2) + "\n"
   );
-  return new Promise((resolvePromise, reject) => {
-    const initialPrompt = `Read the current Syntaur assignment at ${assignmentDir}/assignment.md and give me a brief summary: title, status, priority, objective, and acceptance criteria.`;
-    const child = spawn2(command, [initialPrompt], {
+  const { argv, shellFallbackWarning } = buildAgentArgv(
+    agent,
+    INITIAL_PROMPT(assignmentDir)
+  );
+  if (shellFallbackWarning) {
+    console.warn(shellFallbackWarning);
+  }
+  return new Promise((resolvePromise) => {
+    const child = spawn2(argv.command, argv.args, {
       cwd: workspaceDir,
       stdio: "inherit"
     });
     child.on("error", (err2) => {
-      if (err2.code === "ENOENT") {
-        console.error(`${agent} CLI not found. Is \`${command}\` installed and in your PATH?`);
+      const code = err2.code;
+      if (code === "ENOENT") {
+        console.error(
+          `syntaur: agent "${agent.id}" command "${agent.command}" not found. If "${agent.command}" is a shell alias, set resolveFromShellAliases: true on this agent in ~/.syntaur/config.md.`
+        );
+      } else if (code === "EACCES") {
+        console.error(
+          `syntaur: agent "${agent.id}" command "${agent.command}" is not executable (EACCES). Check file permissions.`
+        );
       } else {
-        console.error(`Failed to launch ${agent}:`, err2.message);
+        console.error(
+          `syntaur: failed to launch agent "${agent.id}" (${code ?? "unknown"}): ${err2.message}`
+        );
       }
-      process.exit(1);
+      resolvePromise();
+      exitWith(1);
     });
     child.on("exit", (code) => {
-      process.exit(code ?? 0);
+      resolvePromise();
+      exitWith(code ?? 0);
     });
   });
 }
-var AGENT_COMMANDS;
+var INITIAL_PROMPT;
 var init_launch = __esm({
   "src/tui/launch.ts"() {
     "use strict";
     init_api();
-    AGENT_COMMANDS = {
-      claude: "c",
-      codex: "cx"
+    INITIAL_PROMPT = (assignmentDir) => `Read the current Syntaur assignment at ${assignmentDir}/assignment.md and give me a brief summary: title, status, priority, objective, and acceptance criteria.`;
+  }
+});
+
+// src/utils/git-worktree.ts
+var git_worktree_exports = {};
+__export(git_worktree_exports, {
+  GitWorktreeError: () => GitWorktreeError,
+  createWorktree: () => createWorktree,
+  createWorktreeAndRecord: () => createWorktreeAndRecord,
+  deleteBranch: () => deleteBranch,
+  formatRollbackError: () => formatRollbackError,
+  removeWorktree: () => removeWorktree
+});
+import { spawn as spawn3 } from "child_process";
+import { readFile as readFile20 } from "fs/promises";
+function run(command, args, cwd) {
+  return new Promise((resolvePromise) => {
+    const child = spawn3(command, args, { cwd, stdio: ["ignore", "pipe", "pipe"] });
+    let stdout = "";
+    let stderr = "";
+    child.stdout.on("data", (chunk) => stdout += chunk.toString());
+    child.stderr.on("data", (chunk) => stderr += chunk.toString());
+    child.on("error", (err2) => {
+      resolvePromise({ code: -1, stdout, stderr: stderr + String(err2) });
+    });
+    child.on("close", (code) => {
+      resolvePromise({ code: code ?? -1, stdout, stderr });
+    });
+  });
+}
+async function createWorktree(opts) {
+  const { repository, branch, worktreePath, parentBranch } = opts;
+  const result = await run(
+    "git",
+    ["-C", repository, "worktree", "add", "-b", branch, worktreePath, parentBranch]
+  );
+  if (result.code !== 0) {
+    throw new GitWorktreeError(
+      `git worktree add failed (exit ${result.code}): ${result.stderr.trim() || "(no stderr)"}`,
+      result.stderr
+    );
+  }
+}
+async function removeWorktree(repository, worktreePath) {
+  const result = await run(
+    "git",
+    ["-C", repository, "worktree", "remove", "--force", worktreePath]
+  );
+  return { ok: result.code === 0, stderr: result.stderr };
+}
+async function deleteBranch(repository, branch) {
+  const result = await run("git", ["-C", repository, "branch", "-D", branch]);
+  return { ok: result.code === 0, stderr: result.stderr };
+}
+async function createWorktreeAndRecord(opts) {
+  const { assignmentPath, repository, branch, worktreePath, parentBranch } = opts;
+  await createWorktree({ repository, branch, worktreePath, parentBranch });
+  try {
+    const content = await readFile20(assignmentPath, "utf-8");
+    const updated = updateAssignmentWorkspace(content, {
+      repository,
+      worktreePath,
+      branch,
+      parentBranch
+    });
+    await writeFileForce(assignmentPath, updated);
+  } catch (writeErr) {
+    const cleanup = await removeWorktree(repository, worktreePath);
+    const branchCleanup = await deleteBranch(repository, branch);
+    const writeMsg = writeErr instanceof Error ? writeErr.message : String(writeErr);
+    throw new Error(
+      formatRollbackError({
+        writeMsg,
+        worktreePath,
+        branch,
+        worktreeCleanup: cleanup,
+        branchCleanup
+      })
+    );
+  }
+}
+function formatRollbackError(opts) {
+  const { writeMsg, worktreePath, branch, worktreeCleanup, branchCleanup } = opts;
+  const wtMsg = worktreeCleanup.stderr.trim() || "(no stderr)";
+  const brMsg = branchCleanup.stderr.trim() || "(no stderr)";
+  if (!worktreeCleanup.ok && !branchCleanup.ok) {
+    return `Failed to update assignment frontmatter AND failed to clean up both worktree and branch. Write error: ${writeMsg}. Worktree cleanup error: ${wtMsg}. Branch cleanup error: ${brMsg}. Orphan worktree at ${worktreePath} and orphan branch "${branch}" \u2014 remove them manually.`;
+  }
+  if (!worktreeCleanup.ok) {
+    return `Failed to update assignment frontmatter AND failed to clean up worktree. Write error: ${writeMsg}. Worktree cleanup error: ${wtMsg}. Orphan worktree at ${worktreePath} \u2014 remove it manually.`;
+  }
+  if (!branchCleanup.ok) {
+    return `Failed to update assignment frontmatter: ${writeMsg}. Rolled back git worktree at ${worktreePath}, but could not delete branch "${branch}": ${brMsg}. Remove the branch manually.`;
+  }
+  return `Failed to update assignment frontmatter: ${writeMsg}. Rolled back git worktree at ${worktreePath} and branch "${branch}".`;
+}
+var GitWorktreeError;
+var init_git_worktree = __esm({
+  "src/utils/git-worktree.ts"() {
+    "use strict";
+    init_frontmatter();
+    init_fs();
+    GitWorktreeError = class extends Error {
+      constructor(message, stderr) {
+        super(message);
+        this.stderr = stderr;
+      }
     };
   }
 });
 
 // src/index.ts
-import { Command as Command4 } from "commander";
+import { Command as Command5 } from "commander";
 
 // src/commands/init.ts
 init_paths();
@@ -6124,8 +6725,8 @@ async function migrateFromMarkdown(projectsDir2) {
   return allSessions.length;
 }
 async function parseMarkdownSessionsIndex(filePath, projectSlug) {
-  const { readFile: readFile30 } = await import("fs/promises");
-  const raw = await readFile30(filePath, "utf-8");
+  const { readFile: readFile32 } = await import("fs/promises");
+  const raw = await readFile32(filePath, "utf-8");
   const sessions = [];
   const lines = raw.split("\n");
   let inTable = false;
@@ -7939,8 +8540,8 @@ ${entry}`;
   });
   return router;
 }
-function slugifyLocal(input3) {
-  return input3.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "") || "untitled";
+function slugifyLocal(input4) {
+  return input4.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "") || "untitled";
 }
 async function appendCommentTo(assignmentDir, assignmentRef, req, res, reloadDetail) {
   const commentsPath = resolve15(assignmentDir, "comments.md");
@@ -8554,8 +9155,8 @@ function createTodosRouter(todosDir2, broadcast) {
   router.post("/:workspace/archive", async (req, res) => {
     try {
       const { archivePath: archivePath2 } = await Promise.resolve().then(() => (init_parser2(), parser_exports));
-      const { resolve: resolve46 } = await import("path");
-      const { readFile: readFile30 } = await import("fs/promises");
+      const { resolve: resolve47 } = await import("path");
+      const { readFile: readFile32 } = await import("fs/promises");
       const { writeFileForce: writeFileForce2 } = await Promise.resolve().then(() => (init_fs(), fs_exports));
       const workspace = getWorkspaceParam(req.params.workspace);
       const checklist = await readChecklist(todosDir2, workspace);
@@ -8571,10 +9172,10 @@ function createTodosRouter(todosDir2, broadcast) {
         (e) => e.itemIds.every((id) => completedIds.has(id))
       );
       const archFile = archivePath2(todosDir2, workspace, checklist.archiveInterval);
-      await ensureDir(resolve46(todosDir2, "archive"));
+      await ensureDir(resolve47(todosDir2, "archive"));
       let archContent = "";
       if (await fileExists(archFile)) {
-        archContent = await readFile30(archFile, "utf-8");
+        archContent = await readFile32(archFile, "utf-8");
         archContent = archContent.trimEnd() + "\n\n";
       } else {
         archContent = `---
@@ -10158,6 +10759,43 @@ function createDashboardServer(options) {
       res.status(500).json({ error: "Failed to reset status config" });
     }
   });
+  const THEME_PRESET_SLUGS = ["default", "ocean", "forest", "sunset"];
+  const DEFAULT_THEME_PRESET = "default";
+  app.get("/api/config/theme", async (_req, res) => {
+    try {
+      const config = await readConfig();
+      const preset = config.theme?.preset ?? DEFAULT_THEME_PRESET;
+      res.json({ preset, custom: config.theme !== null });
+    } catch (error) {
+      console.error("Error getting theme config:", error);
+      res.status(500).json({ error: "Failed to get theme config" });
+    }
+  });
+  app.post("/api/config/theme", async (req, res) => {
+    try {
+      const { preset } = req.body ?? {};
+      if (typeof preset !== "string" || !THEME_PRESET_SLUGS.includes(preset)) {
+        res.status(400).json({
+          error: `preset must be one of: ${THEME_PRESET_SLUGS.join(", ")}`
+        });
+        return;
+      }
+      await writeThemeConfig({ preset });
+      res.json({ preset, custom: true });
+    } catch (error) {
+      console.error("Error saving theme config:", error);
+      res.status(500).json({ error: "Failed to save theme config" });
+    }
+  });
+  app.delete("/api/config/theme", async (_req, res) => {
+    try {
+      await deleteThemeConfig();
+      res.json({ preset: DEFAULT_THEME_PRESET, custom: false });
+    } catch (error) {
+      console.error("Error resetting theme config:", error);
+      res.status(500).json({ error: "Failed to reset theme config" });
+    }
+  });
   app.get("/api/projects", async (req, res) => {
     try {
       let projects = await listProjects(projectsDir2);
@@ -10297,7 +10935,9 @@ function createDashboardServer(options) {
   app.use("/api/projects/:projectId/todos", createProjectTodosRouter(projectsDir2, broadcast));
   app.use("/api/backup", createBackupRouter());
   if (serveStaticUi && dashboardDistPath) {
-    app.use("/assets", express.static(resolve21(dashboardDistPath, "assets")));
+    const sendOpts = { dotfiles: "allow" };
+    app.use("/assets", express.static(resolve21(dashboardDistPath, "assets"), sendOpts));
+    app.use(express.static(dashboardDistPath, { ...sendOpts, index: false, fallthrough: true }));
     app.get("{*path}", async (req, res) => {
       if (req.path.startsWith("/api") || req.path === "/ws" || req.path.startsWith("/assets")) {
         res.status(404).json({ error: "Not Found" });
@@ -10310,7 +10950,7 @@ function createDashboardServer(options) {
         );
         return;
       }
-      res.sendFile(indexPath, (err2) => {
+      res.sendFile(indexPath, sendOpts, (err2) => {
         if (err2) {
           console.error("Error sending dashboard index.html:", err2);
           if (!res.headersSent) res.status(500).send("Dashboard load error");
@@ -12673,10 +13313,29 @@ async function trackSessionCommand(options) {
 
 // src/commands/browse.ts
 init_config2();
+init_paths();
+init_fs();
+import { spawnSync as spawnSync2 } from "child_process";
+import { resolve as resolve33, isAbsolute as isAbsolute4 } from "path";
+import { readFile as readFile21 } from "fs/promises";
+import { select, confirm as confirm2, input as input3 } from "@inquirer/prompts";
 async function browseCommand(options) {
   const config = await readConfig();
   const projectsDir2 = config.defaultProjectDir;
-  const agent = options.agent;
+  const agents = getAgents(config);
+  if (agents.length === 0) {
+    console.error(
+      "No agents configured. Add one with `syntaur agents add --id <id> --label <label> --command <path>`."
+    );
+    process.exit(1);
+  }
+  const preSelectedAgent = options.agent ? agents.find((a) => a.id === options.agent) : void 0;
+  if (options.agent && !preSelectedAgent) {
+    console.error(
+      `Unknown agent id "${options.agent}". Configured: ${agents.map((a) => a.id).join(", ")}`
+    );
+    process.exit(1);
+  }
   const { render } = await import("ink");
   const React2 = await import("react");
   const { App: App2 } = await Promise.resolve().then(() => (init_App(), App_exports));
@@ -12687,7 +13346,19 @@ async function browseCommand(options) {
       unmount();
       unmount = null;
     }
-    await launchAgent2({ ...launchOpts, agent });
+    const agent = preSelectedAgent ?? await pickAgent(agents);
+    const cwdOverride = await ensureWorktree({
+      projectsDir: launchOpts.projectsDir,
+      projectSlug: launchOpts.projectSlug,
+      assignmentSlug: launchOpts.assignmentSlug,
+      worktreePromptEnabled: options.worktreePrompt !== false,
+      autoCreateWorktree: config.agentDefaults.autoCreateWorktree
+    });
+    await launchAgent2({
+      ...launchOpts,
+      agent,
+      ...cwdOverride ? { cwdOverride } : {}
+    });
   };
   const instance = render(
     React2.createElement(App2, { projectsDir: projectsDir2, onLaunch })
@@ -12695,9 +13366,164 @@ async function browseCommand(options) {
   unmount = instance.unmount;
   await instance.waitUntilExit();
 }
+async function pickAgent(agents) {
+  if (agents.length === 1) return agents[0];
+  if (!isInteractiveTerminal()) {
+    const fallback = agents.find((a) => a.default) ?? agents[0];
+    console.warn(
+      `syntaur: multiple agents configured but no TTY \u2014 using "${fallback.id}".`
+    );
+    return fallback;
+  }
+  const defaultAgent = agents.find((a) => a.default) ?? agents[0];
+  const id = await select({
+    message: "Launch which agent?",
+    choices: agents.map((a) => ({ name: a.label, value: a.id, description: a.command })),
+    default: defaultAgent.id
+  });
+  const picked = agents.find((a) => a.id === id);
+  if (!picked) throw new Error(`Internal error: picker returned unknown agent id "${id}"`);
+  return picked;
+}
+async function ensureWorktree(opts) {
+  const assignmentPath = resolve33(
+    opts.projectsDir,
+    opts.projectSlug,
+    "assignments",
+    opts.assignmentSlug,
+    "assignment.md"
+  );
+  if (!await fileExists(assignmentPath)) {
+    return void 0;
+  }
+  const content = await readFile21(assignmentPath, "utf-8");
+  const { parseAssignmentFrontmatter: parseAssignmentFrontmatter2 } = await Promise.resolve().then(() => (init_frontmatter(), frontmatter_exports));
+  const fm = parseAssignmentFrontmatter2(content);
+  const { workspace } = fm;
+  if (workspace.worktreePath && workspace.branch) {
+    return void 0;
+  }
+  if (!opts.worktreePromptEnabled) {
+    return void 0;
+  }
+  if (opts.autoCreateWorktree === "skip") {
+    return void 0;
+  }
+  const defaults = computeWorktreeDefaults({
+    projectSlug: opts.projectSlug,
+    assignmentSlug: opts.assignmentSlug,
+    existing: workspace
+  });
+  if (!defaults.repository) {
+    console.warn(
+      `syntaur: cannot infer repository for ${opts.assignmentSlug} \u2014 skipping worktree prompt`
+    );
+    return void 0;
+  }
+  if (opts.autoCreateWorktree === "always") {
+    return await runCreate({
+      assignmentPath,
+      repository: defaults.repository,
+      branch: defaults.branch,
+      parentBranch: defaults.parentBranch,
+      worktreePath: defaults.worktreePath
+    });
+  }
+  if (!isInteractiveTerminal()) {
+    return void 0;
+  }
+  const proceed = await confirm2({
+    message: `This assignment has no git worktree/branch configured. Create one?`,
+    default: true
+  });
+  if (!proceed) {
+    return void 0;
+  }
+  const repository = await input3({
+    message: "Repository path:",
+    default: defaults.repository
+  });
+  const branch = await input3({
+    message: "Branch name:",
+    default: defaults.branch
+  });
+  const parentBranch = await input3({
+    message: "Parent branch:",
+    default: defaults.parentBranch
+  });
+  const worktreePath = await input3({
+    message: "Worktree path:",
+    default: defaults.worktreePath
+  });
+  return await runCreate({
+    assignmentPath,
+    repository,
+    branch,
+    parentBranch,
+    worktreePath
+  });
+}
+function computeWorktreeDefaults(opts) {
+  const repository = opts.existing.repository ?? detectCurrentGitRoot();
+  const branch = opts.projectSlug ? `syntaur/${opts.projectSlug}/${opts.assignmentSlug}` : `syntaur/${opts.assignmentSlug}`;
+  const parentBranch = opts.existing.parentBranch ?? detectCurrentBranch() ?? "main";
+  const worktreeBase = resolve33(
+    syntaurRoot(),
+    "worktrees",
+    opts.projectSlug || "standalone",
+    opts.assignmentSlug
+  );
+  return {
+    ...repository ? { repository } : {},
+    branch,
+    parentBranch,
+    worktreePath: worktreeBase
+  };
+}
+function detectCurrentGitRoot() {
+  const result = spawnSync2("git", ["rev-parse", "--show-toplevel"], {
+    encoding: "utf-8"
+  });
+  if (result.status !== 0) return void 0;
+  const out = result.stdout.trim();
+  return out.length > 0 ? out : void 0;
+}
+function detectCurrentBranch() {
+  const result = spawnSync2("git", ["rev-parse", "--abbrev-ref", "HEAD"], {
+    encoding: "utf-8"
+  });
+  if (result.status !== 0) return void 0;
+  const out = result.stdout.trim();
+  if (!out || out === "HEAD") return void 0;
+  return out;
+}
+async function runCreate(opts) {
+  const { createWorktreeAndRecord: createWorktreeAndRecord2, GitWorktreeError: GitWorktreeError2 } = await Promise.resolve().then(() => (init_git_worktree(), git_worktree_exports));
+  const expandedWorktree = expandHome(opts.worktreePath);
+  const absWorktree = isAbsolute4(expandedWorktree) ? expandedWorktree : resolve33(expandedWorktree);
+  try {
+    await createWorktreeAndRecord2({
+      assignmentPath: opts.assignmentPath,
+      repository: opts.repository,
+      branch: opts.branch,
+      worktreePath: absWorktree,
+      parentBranch: opts.parentBranch
+    });
+    console.log(`syntaur: created worktree at ${absWorktree} on branch ${opts.branch}`);
+    return absWorktree;
+  } catch (err2) {
+    const msg = err2 instanceof Error ? err2.message : String(err2);
+    if (err2 instanceof GitWorktreeError2) {
+      console.error(`syntaur: ${msg}`);
+    } else {
+      console.error(`syntaur: ${msg}`);
+    }
+    process.exit(1);
+  }
+}
 
 // src/commands/create-playbook.ts
-import { resolve as resolve33 } from "path";
+import { resolve as resolve34 } from "path";
 init_timestamp();
 init_paths();
 init_fs();
@@ -12714,7 +13540,7 @@ async function createPlaybookCommand(name, options) {
   }
   const dir = playbooksDir();
   await ensureDir(dir);
-  const filePath = resolve33(dir, `${slug}.md`);
+  const filePath = resolve34(dir, `${slug}.md`);
   if (await fileExists(filePath)) {
     throw new Error(
       `Playbook "${slug}" already exists at ${filePath}
@@ -12736,8 +13562,8 @@ init_paths();
 init_fs();
 init_parser();
 init_config2();
-import { readdir as readdir12, readFile as readFile20 } from "fs/promises";
-import { resolve as resolve34 } from "path";
+import { readdir as readdir12, readFile as readFile22 } from "fs/promises";
+import { resolve as resolve35 } from "path";
 async function listPlaybooksCommand(options = {}) {
   const dir = playbooksDir();
   if (!await fileExists(dir)) {
@@ -12752,8 +13578,8 @@ async function listPlaybooksCommand(options = {}) {
   );
   const rows = [];
   for (const entry of mdFiles) {
-    const filePath = resolve34(dir, entry.name);
-    const raw = await readFile20(filePath, "utf-8");
+    const filePath = resolve35(dir, entry.name);
+    const raw = await readFile22(filePath, "utf-8");
     const parsed = parsePlaybook(raw);
     const slug = parsed.slug || entry.name.replace(/\.md$/, "");
     const disabled = disabledSet.has(slug);
@@ -12835,8 +13661,8 @@ init_parser2();
 init_fs();
 init_config2();
 import { Command } from "commander";
-import { readFile as readFile21 } from "fs/promises";
-import { resolve as resolve35 } from "path";
+import { readFile as readFile23 } from "fs/promises";
+import { resolve as resolve36 } from "path";
 var WORKSPACE_REGEX2 = /^[a-z0-9_][a-z0-9-]*$/;
 async function resolveScope(options) {
   const flagCount = [Boolean(options.project), Boolean(options.workspace), Boolean(options.global)].filter(Boolean).length;
@@ -12848,7 +13674,7 @@ async function resolveScope(options) {
       throw new Error(`Invalid project slug: "${options.project}".`);
     }
     const config = await readConfig();
-    const projectMd = resolve35(config.defaultProjectDir, options.project, "project.md");
+    const projectMd = resolve36(config.defaultProjectDir, options.project, "project.md");
     if (!await fileExists(projectMd)) {
       throw new Error(`Project "${options.project}" not found.`);
     }
@@ -13142,10 +13968,10 @@ todoCommand.command("archive").description("Archive completed todos and their lo
       (e) => e.itemIds.every((id) => completedIds.has(id))
     );
     const archFile = archivePath(todosPath, workspace, checklist.archiveInterval);
-    await ensureDir(resolve35(todosPath, "archive"));
+    await ensureDir(resolve36(todosPath, "archive"));
     let archContent = "";
     if (await fileExists(archFile)) {
-      archContent = await readFile21(archFile, "utf-8");
+      archContent = await readFile23(archFile, "utf-8");
       archContent = archContent.trimEnd() + "\n\n";
     } else {
       archContent = `---
@@ -13335,7 +14161,7 @@ import { Command as Command3 } from "commander";
 
 // src/utils/doctor/index.ts
 import { fileURLToPath as fileURLToPath7 } from "url";
-import { readFile as readFile25 } from "fs/promises";
+import { readFile as readFile27 } from "fs/promises";
 import { dirname as dirname11, join as join5 } from "path";
 
 // src/utils/doctor/context.ts
@@ -13343,11 +14169,11 @@ init_config2();
 init_paths();
 init_fs();
 import Database2 from "better-sqlite3";
-import { resolve as resolve36 } from "path";
+import { resolve as resolve37 } from "path";
 async function buildCheckContext(cwd = process.cwd()) {
   const config = await readConfig();
   const root = syntaurRoot();
-  const dbPath = resolve36(root, "syntaur.db");
+  const dbPath = resolve37(root, "syntaur.db");
   let db2 = null;
   let dbError = null;
   if (await fileExists(dbPath)) {
@@ -13381,8 +14207,8 @@ function closeCheckContext(ctx) {
 // src/utils/doctor/checks/env.ts
 init_fs();
 init_paths();
-import { resolve as resolve37, isAbsolute as isAbsolute3 } from "path";
-import { readFile as readFile22, stat as stat4 } from "fs/promises";
+import { resolve as resolve38, isAbsolute as isAbsolute5 } from "path";
+import { readFile as readFile24, stat as stat4 } from "fs/promises";
 import { fileURLToPath as fileURLToPath6 } from "url";
 import { dirname as dirname10, join as join4 } from "path";
 var CATEGORY = "env";
@@ -13422,7 +14248,7 @@ var configValid = {
   category: CATEGORY,
   title: "~/.syntaur/config.md is valid",
   async run(ctx) {
-    const configPath = resolve37(ctx.syntaurRoot, "config.md");
+    const configPath = resolve38(ctx.syntaurRoot, "config.md");
     if (!await fileExists(configPath)) {
       return {
         id: this.id,
@@ -13439,7 +14265,7 @@ var configValid = {
         autoFixable: false
       };
     }
-    const content = await readFile22(configPath, "utf-8");
+    const content = await readFile24(configPath, "utf-8");
     const fmMatch = content.match(/^---\n([\s\S]*?)\n---/);
     if (!fmMatch || fmMatch[1].trim() === "") {
       return {
@@ -13476,7 +14302,7 @@ var configValid = {
       };
     }
     const expanded = expandHome(rawProjectDir);
-    if (!isAbsolute3(expanded)) {
+    if (!isAbsolute5(expanded)) {
       return {
         id: this.id,
         category: this.category,
@@ -13719,7 +14545,7 @@ async function readLocalPkg() {
     for (let i = 0; i < 6; i++) {
       const candidate = join4(dir, "package.json");
       try {
-        const text = await readFile22(candidate, "utf-8");
+        const text = await readFile24(candidate, "utf-8");
         return JSON.parse(text);
       } catch {
         dir = dirname10(dir);
@@ -13771,7 +14597,7 @@ function versionGte(a, b) {
 
 // src/utils/doctor/checks/structure.ts
 init_fs();
-import { resolve as resolve38 } from "path";
+import { resolve as resolve39 } from "path";
 import { readdir as readdir13, stat as stat5 } from "fs/promises";
 var CATEGORY2 = "structure";
 var KNOWN_TOP_LEVEL = /* @__PURE__ */ new Set([
@@ -13791,7 +14617,7 @@ var projectsDir = {
   category: CATEGORY2,
   title: "projects/ directory exists",
   async run(ctx) {
-    const p = resolve38(ctx.syntaurRoot, "projects");
+    const p = resolve39(ctx.syntaurRoot, "projects");
     if (!await fileExists(p)) {
       return {
         id: this.id,
@@ -13816,7 +14642,7 @@ var playbooksDir2 = {
   category: CATEGORY2,
   title: "playbooks/ directory exists",
   async run(ctx) {
-    const p = resolve38(ctx.syntaurRoot, "playbooks");
+    const p = resolve39(ctx.syntaurRoot, "playbooks");
     if (!await fileExists(p)) {
       return {
         id: this.id,
@@ -13841,7 +14667,7 @@ var todosDirValid = {
   category: CATEGORY2,
   title: "todos/ directory is readable (if present)",
   async run(ctx) {
-    const p = resolve38(ctx.syntaurRoot, "todos");
+    const p = resolve39(ctx.syntaurRoot, "todos");
     if (!await fileExists(p)) {
       return {
         id: this.id,
@@ -13872,7 +14698,7 @@ var serversDirValid = {
   category: CATEGORY2,
   title: "servers/ directory is readable (if present)",
   async run(ctx) {
-    const p = resolve38(ctx.syntaurRoot, "servers");
+    const p = resolve39(ctx.syntaurRoot, "servers");
     if (!await fileExists(p)) {
       return {
         id: this.id,
@@ -13917,7 +14743,7 @@ var knownFilesRecognized = {
       title: this.title,
       status: "warn",
       detail: `unexpected top-level entries: ${unexpected.join(", ")}`,
-      affected: unexpected.map((n) => resolve38(ctx.syntaurRoot, n)),
+      affected: unexpected.map((n) => resolve39(ctx.syntaurRoot, n)),
       remediation: {
         kind: "manual",
         suggestion: "Review these entries \u2014 they may be leftover state from older versions",
@@ -13946,7 +14772,7 @@ function pass2(check) {
 
 // src/utils/doctor/checks/project.ts
 init_fs();
-import { resolve as resolve39 } from "path";
+import { resolve as resolve40 } from "path";
 import { readdir as readdir14, stat as stat6 } from "fs/promises";
 var CATEGORY3 = "project";
 var REQUIRED_PROJECT_FILES = [
@@ -13976,10 +14802,10 @@ async function listProjects2(ctx) {
   for (const e of entries) {
     if (!e.isDirectory()) continue;
     if (e.name.startsWith(".") || e.name.startsWith("_")) continue;
-    const projectDir = resolve39(dir, e.name);
+    const projectDir = resolve40(dir, e.name);
     let looksLikeProject = false;
     for (const marker of PROJECT_MARKERS) {
-      if (await fileExists(resolve39(projectDir, marker))) {
+      if (await fileExists(resolve40(projectDir, marker))) {
         looksLikeProject = true;
         break;
       }
@@ -13998,7 +14824,7 @@ var requiredFiles = {
     for (const projectDir of projects) {
       const missing = [];
       for (const rel of REQUIRED_PROJECT_FILES) {
-        const p = resolve39(projectDir, rel);
+        const p = resolve40(projectDir, rel);
         if (!await fileExists(p)) missing.push(rel);
       }
       if (missing.length === 0) continue;
@@ -14008,7 +14834,7 @@ var requiredFiles = {
         title: this.title,
         status: "error",
         detail: `project at ${projectDir} is missing: ${missing.join(", ")}`,
-        affected: missing.map((m) => resolve39(projectDir, m)),
+        affected: missing.map((m) => resolve40(projectDir, m)),
         remediation: {
           kind: "manual",
           suggestion: "Recreate the missing scaffold files from templates",
@@ -14031,7 +14857,7 @@ var manifestStale = {
     const projects = await listProjects2(ctx);
     const results = [];
     for (const projectDir of projects) {
-      const manifestPath = resolve39(projectDir, "manifest.md");
+      const manifestPath = resolve40(projectDir, "manifest.md");
       if (!await fileExists(manifestPath)) continue;
       const manifestMtime = (await stat6(manifestPath)).mtimeMs;
       const newestAssignment = await newestAssignmentMtime(projectDir);
@@ -14080,7 +14906,7 @@ var orphanFiles = {
         title: this.title,
         status: "warn",
         detail: `project at ${projectDir} has unexpected entries: ${orphans.join(", ")}`,
-        affected: orphans.map((o) => resolve39(projectDir, o)),
+        affected: orphans.map((o) => resolve40(projectDir, o)),
         autoFixable: false
       });
     }
@@ -14090,7 +14916,7 @@ var orphanFiles = {
 };
 var projectChecks = [requiredFiles, manifestStale, orphanFiles];
 async function newestAssignmentMtime(projectDir) {
-  const assignmentsRoot = resolve39(projectDir, "assignments");
+  const assignmentsRoot = resolve40(projectDir, "assignments");
   if (!await fileExists(assignmentsRoot)) return 0;
   let newest = 0;
   let entries;
@@ -14101,7 +14927,7 @@ async function newestAssignmentMtime(projectDir) {
   }
   for (const e of entries) {
     if (!e.isDirectory()) continue;
-    const assignmentMd = resolve39(assignmentsRoot, e.name, "assignment.md");
+    const assignmentMd = resolve40(assignmentsRoot, e.name, "assignment.md");
     try {
       const s = await stat6(assignmentMd);
       if (s.mtimeMs > newest) newest = s.mtimeMs;
@@ -14125,8 +14951,8 @@ init_fs();
 init_parser();
 init_types();
 init_paths();
-import { resolve as resolve40 } from "path";
-import { readdir as readdir15, readFile as readFile23 } from "fs/promises";
+import { resolve as resolve41 } from "path";
+import { readdir as readdir15, readFile as readFile25 } from "fs/promises";
 var CATEGORY4 = "assignment";
 var STATUSES_REQUIRING_HANDOFF = /* @__PURE__ */ new Set(["review", "completed"]);
 async function listAssignments(ctx) {
@@ -14137,16 +14963,16 @@ async function listAssignments(ctx) {
     for (const m of projects) {
       if (!m.isDirectory()) continue;
       if (m.name.startsWith(".") || m.name.startsWith("_")) continue;
-      const assignmentsDir2 = resolve40(projectsDir2, m.name, "assignments");
+      const assignmentsDir2 = resolve41(projectsDir2, m.name, "assignments");
       if (!await fileExists(assignmentsDir2)) continue;
       const entries = await readdir15(assignmentsDir2, { withFileTypes: true });
       for (const a of entries) {
         if (!a.isDirectory()) continue;
         if (a.name.startsWith(".") || a.name.startsWith("_")) continue;
-        const assignmentDir = resolve40(assignmentsDir2, a.name);
-        const assignmentMd = resolve40(assignmentDir, "assignment.md");
+        const assignmentDir = resolve41(assignmentsDir2, a.name);
+        const assignmentMd = resolve41(assignmentDir, "assignment.md");
         const entry = {
-          projectDir: resolve40(projectsDir2, m.name),
+          projectDir: resolve41(projectsDir2, m.name),
           projectSlug: m.name,
           assignmentDir,
           assignmentSlug: a.name,
@@ -14166,8 +14992,8 @@ async function listAssignments(ctx) {
     for (const a of entries) {
       if (!a.isDirectory()) continue;
       if (a.name.startsWith(".") || a.name.startsWith("_")) continue;
-      const assignmentDir = resolve40(standaloneRoot, a.name);
-      const assignmentMd = resolve40(assignmentDir, "assignment.md");
+      const assignmentDir = resolve41(standaloneRoot, a.name);
+      const assignmentMd = resolve41(assignmentDir, "assignment.md");
       const entry = {
         projectDir: standaloneRoot,
         projectSlug: null,
@@ -14245,7 +15071,7 @@ var invalidStatus = {
     const allowed = configuredStatuses(ctx);
     const results = [];
     for (const a of withAssignmentMd) {
-      const path = resolve40(a.assignmentDir, "assignment.md");
+      const path = resolve41(a.assignmentDir, "assignment.md");
       const parsed = await parseSafe(path);
       if (!parsed) continue;
       if (!allowed.has(parsed.status)) {
@@ -14278,7 +15104,7 @@ var workspaceMissing = {
     const terminal = terminalStatuses(ctx);
     const results = [];
     for (const a of withAssignmentMd) {
-      const path = resolve40(a.assignmentDir, "assignment.md");
+      const path = resolve41(a.assignmentDir, "assignment.md");
       const parsed = await parseSafe(path);
       if (!parsed) continue;
       if (terminal.has(parsed.status)) continue;
@@ -14325,12 +15151,12 @@ var requiredFilesByStatus = {
     const { withAssignmentMd } = await listAssignments(ctx);
     const results = [];
     for (const a of withAssignmentMd) {
-      const assignmentPath = resolve40(a.assignmentDir, "assignment.md");
+      const assignmentPath = resolve41(a.assignmentDir, "assignment.md");
       const parsed = await parseSafe(assignmentPath);
       if (!parsed) continue;
       const missing = [];
       if (STATUSES_REQUIRING_HANDOFF.has(parsed.status)) {
-        const handoffPath = resolve40(a.assignmentDir, "handoff.md");
+        const handoffPath = resolve41(a.assignmentDir, "handoff.md");
         if (!await fileExists(handoffPath)) missing.push("handoff.md");
       }
       if (missing.length === 0) continue;
@@ -14340,7 +15166,7 @@ var requiredFilesByStatus = {
         title: this.title,
         status: "warn",
         detail: `${a.projectSlug}/${a.assignmentSlug} (status: ${parsed.status}) is missing ${missing.join(", ")}`,
-        affected: missing.map((m) => resolve40(a.assignmentDir, m)),
+        affected: missing.map((m) => resolve41(a.assignmentDir, m)),
         remediation: {
           kind: "manual",
           suggestion: `Create the missing ${missing.join(" and ")} files for this assignment`,
@@ -14363,7 +15189,7 @@ var companionFilesScaffolded = {
     for (const a of withAssignmentMd) {
       const missing = [];
       for (const filename of ["progress.md", "comments.md"]) {
-        if (!await fileExists(resolve40(a.assignmentDir, filename))) {
+        if (!await fileExists(resolve41(a.assignmentDir, filename))) {
           missing.push(filename);
         }
       }
@@ -14375,7 +15201,7 @@ var companionFilesScaffolded = {
         title: this.title,
         status: "warn",
         detail: `${label} is missing ${missing.join(" and ")} (pre-v2.0 assignment \u2014 not required, but scaffolding them keeps the dashboard and CLIs consistent)`,
-        affected: missing.map((m) => resolve40(a.assignmentDir, m)),
+        affected: missing.map((m) => resolve41(a.assignmentDir, m)),
         remediation: {
           kind: "manual",
           suggestion: `Create ${missing.join(" and ")} with the renderProgress/renderComments templates, or re-scaffold via the CLI`,
@@ -14408,7 +15234,7 @@ var typeDefinition = {
     const { withAssignmentMd } = await listAssignments(ctx);
     const results = [];
     for (const a of withAssignmentMd) {
-      const path = resolve40(a.assignmentDir, "assignment.md");
+      const path = resolve41(a.assignmentDir, "assignment.md");
       const parsed = await parseSafe(path);
       if (!parsed) continue;
       if (!parsed.type) continue;
@@ -14442,7 +15268,7 @@ var projectFrontmatterMatchesContainer = {
     const { withAssignmentMd } = await listAssignments(ctx);
     const results = [];
     for (const a of withAssignmentMd) {
-      const path = resolve40(a.assignmentDir, "assignment.md");
+      const path = resolve41(a.assignmentDir, "assignment.md");
       const parsed = await parseSafe(path);
       if (!parsed) continue;
       if (a.standalone) {
@@ -14497,7 +15323,7 @@ var assignmentChecks = [
 ];
 async function parseSafe(path) {
   try {
-    const content = await readFile23(path, "utf-8");
+    const content = await readFile25(path, "utf-8");
     return parseAssignmentFull(content);
   } catch {
     return null;
@@ -14516,7 +15342,7 @@ function pass4(check, detail) {
 
 // src/utils/doctor/checks/dashboard.ts
 init_fs();
-import { resolve as resolve41 } from "path";
+import { resolve as resolve42 } from "path";
 var CATEGORY5 = "dashboard";
 var dbReachable = {
   id: "dashboard.db-reachable",
@@ -14530,7 +15356,7 @@ var dbReachable = {
         title: this.title,
         status: "error",
         detail: `could not open syntaur.db: ${ctx.dbError ?? "unknown error"}`,
-        affected: [resolve41(ctx.syntaurRoot, "syntaur.db")],
+        affected: [resolve42(ctx.syntaurRoot, "syntaur.db")],
         remediation: {
           kind: "manual",
           suggestion: "Start the dashboard once (`syntaur dashboard`) to initialize the DB, or restore it from backup",
@@ -14548,7 +15374,7 @@ var dbReachable = {
           title: this.title,
           status: "error",
           detail: 'syntaur.db is missing the expected "sessions" table',
-          affected: [resolve41(ctx.syntaurRoot, "syntaur.db")],
+          affected: [resolve42(ctx.syntaurRoot, "syntaur.db")],
           autoFixable: false
         };
       }
@@ -14560,7 +15386,7 @@ var dbReachable = {
         title: this.title,
         status: "error",
         detail: `syntaur.db query failed: ${err2 instanceof Error ? err2.message : String(err2)}`,
-        affected: [resolve41(ctx.syntaurRoot, "syntaur.db")],
+        affected: [resolve42(ctx.syntaurRoot, "syntaur.db")],
         autoFixable: false
       };
     }
@@ -14586,7 +15412,7 @@ var ghostSessions = {
     const results = [];
     for (const row of rows) {
       if (!row.project_slug) continue;
-      const projectPath = resolve41(projectsDir2, row.project_slug, "project.md");
+      const projectPath = resolve42(projectsDir2, row.project_slug, "project.md");
       if (!await fileExists(projectPath)) {
         results.push({
           id: this.id,
@@ -14605,7 +15431,7 @@ var ghostSessions = {
         continue;
       }
       if (row.assignment_slug) {
-        const assignmentPath = resolve41(
+        const assignmentPath = resolve42(
           projectsDir2,
           row.project_slug,
           "assignments",
@@ -14762,8 +15588,8 @@ function skipped2(check, reason) {
 init_fs();
 init_parser();
 init_types();
-import { resolve as resolve42 } from "path";
-import { readFile as readFile24 } from "fs/promises";
+import { resolve as resolve43 } from "path";
+import { readFile as readFile26 } from "fs/promises";
 var CATEGORY7 = "workspace";
 var ASSIGNMENT_FIELDS = ["projectSlug", "assignmentSlug", "projectDir", "assignmentDir"];
 function hasAnyAssignmentField(ctx) {
@@ -14775,12 +15601,12 @@ function isStandaloneSession(ctx) {
   return !hasAnyAssignmentField(ctx) && typeof ctx.sessionId === "string" && ctx.sessionId.length > 0;
 }
 async function loadContext(ctx) {
-  const path = resolve42(ctx.cwd, ".syntaur", "context.json");
+  const path = resolve43(ctx.cwd, ".syntaur", "context.json");
   if (!await fileExists(path)) {
     return { data: null, path, exists: false, parseError: null };
   }
   try {
-    const raw = await readFile24(path, "utf-8");
+    const raw = await readFile26(path, "utf-8");
     return { data: JSON.parse(raw), path, exists: true, parseError: null };
   } catch (err2) {
     return {
@@ -14855,7 +15681,7 @@ var contextAssignmentResolves = {
     if (!exists) return skipped3(this, "no context to resolve");
     if (isStandaloneSession(data)) return skipped3(this, "standalone session context \u2014 no assignment to resolve");
     if (!data?.assignmentDir) return skipped3(this, "context has no assignmentDir");
-    const assignmentMd = resolve42(data.assignmentDir, "assignment.md");
+    const assignmentMd = resolve43(data.assignmentDir, "assignment.md");
     if (!await fileExists(assignmentMd)) {
       return {
         id: this.id,
@@ -14884,10 +15710,10 @@ var contextTerminal = {
     if (!exists) return skipped3(this, "no context to check");
     if (isStandaloneSession(data)) return skipped3(this, "standalone session context \u2014 no assignment to check");
     if (!data?.assignmentDir) return skipped3(this, "context has no assignmentDir");
-    const assignmentMd = resolve42(data.assignmentDir, "assignment.md");
+    const assignmentMd = resolve43(data.assignmentDir, "assignment.md");
     if (!await fileExists(assignmentMd)) return skipped3(this, "assignment file missing");
     try {
-      const content = await readFile24(assignmentMd, "utf-8");
+      const content = await readFile26(assignmentMd, "utf-8");
       const parsed = parseAssignmentFull(content);
       const terminal = terminalStatuses2(ctx);
       if (terminal.has(parsed.status)) {
@@ -14939,6 +15765,97 @@ function skipped3(check, reason) {
   };
 }
 
+// src/utils/doctor/checks/agents.ts
+init_config2();
+import { isAbsolute as isAbsolute6 } from "path";
+import { access as access2, constants as fsConstants } from "fs/promises";
+import { spawnSync as spawnSync3 } from "child_process";
+var CATEGORY8 = "agents";
+var agentsResolvable = {
+  id: "agents.commands-resolvable",
+  category: CATEGORY8,
+  title: "All configured agent commands resolve",
+  async run(ctx) {
+    const agents = getAgents(ctx.config);
+    if (agents.length === 0) {
+      return {
+        id: this.id,
+        category: this.category,
+        title: this.title,
+        status: "warn",
+        detail: "No agents configured and no built-in defaults available",
+        remediation: {
+          kind: "manual",
+          suggestion: "Run `syntaur agents add --id <id> --label <label> --command <path>`",
+          command: null
+        },
+        autoFixable: false
+      };
+    }
+    const results = [];
+    for (const agent of agents) {
+      results.push(await checkAgent(agent));
+    }
+    return results;
+  }
+};
+async function checkAgent(agent) {
+  const base = {
+    id: `agents.resolvable.${agent.id}`,
+    category: CATEGORY8,
+    title: `Agent "${agent.id}" command resolves`
+  };
+  if (agent.resolveFromShellAliases) {
+    return {
+      ...base,
+      status: "pass",
+      detail: `shell-alias resolution enabled for "${agent.command}" \u2014 will run via $SHELL -i -c`,
+      autoFixable: false
+    };
+  }
+  if (isAbsolute6(agent.command)) {
+    try {
+      await access2(agent.command, fsConstants.X_OK);
+      return { ...base, status: "pass", autoFixable: false };
+    } catch (err2) {
+      const code = err2.code;
+      const detail = code === "ENOENT" ? `absolute path "${agent.command}" does not exist` : code === "EACCES" ? `absolute path "${agent.command}" exists but is not executable (chmod +x?)` : `absolute path "${agent.command}" failed access check (${code ?? "unknown"})`;
+      return {
+        ...base,
+        status: "warn",
+        detail,
+        remediation: {
+          kind: "manual",
+          suggestion: `Update with \`syntaur agents set ${agent.id} --command <path>\` or fix the file permissions`,
+          command: null
+        },
+        autoFixable: false
+      };
+    }
+  }
+  const result = spawnSync3("which", [agent.command], { encoding: "utf-8" });
+  if (result.status === 0 && result.stdout.trim().length > 0) {
+    return {
+      ...base,
+      status: "pass",
+      detail: `resolved "${agent.command}" \u2192 ${result.stdout.trim()}`,
+      autoFixable: false
+    };
+  }
+  return {
+    ...base,
+    status: "warn",
+    detail: `bare command "${agent.command}" not found on PATH`,
+    remediation: {
+      kind: "manual",
+      suggestion: `Install the binary, point at an absolute path with \`syntaur agents set ${agent.id} --command <abs-path>\`, or enable shell-alias resolution with \`syntaur agents set ${agent.id} --resolve-from-shell-aliases\``,
+      command: null
+    },
+    autoFixable: false
+  };
+}
+var agentChecks = [agentsResolvable];
+
 // src/utils/doctor/registry.ts
 function allChecks() {
   return [
@@ -14948,7 +15865,8 @@ function allChecks() {
     ...assignmentChecks,
     ...dashboardChecks,
     ...integrationChecks,
-    ...workspaceChecks
+    ...workspaceChecks,
+    ...agentChecks
   ];
 }
 
@@ -15034,7 +15952,7 @@ async function readVersion() {
     let dir = dirname11(here);
     for (let i = 0; i < 6; i++) {
       try {
-        const raw = await readFile25(join5(dir, "package.json"), "utf-8");
+        const raw = await readFile27(join5(dir, "package.json"), "utf-8");
         const parsed = JSON.parse(raw);
         return typeof parsed.version === "string" ? parsed.version : null;
       } catch {
@@ -15167,12 +16085,218 @@ var doctorCommand = new Command3("doctor").description("Diagnose Syntaur state a
   }
 });
 
+// src/commands/agents.ts
+init_config2();
+import { Command as Command4 } from "commander";
+var agentsCommand = new Command4("agents").description(
+  "Manage configurable agents used by `syntaur browse` and future launch flows"
+);
+agentsCommand.command("list").description("List configured agents (or built-in defaults if none are configured)").action(async () => {
+  try {
+    const config = await readConfig();
+    const agents = getAgents(config);
+    const source = config.agents ? "config" : "built-in defaults";
+    console.log(`Agents (${source}):`);
+    for (const agent of agents) {
+      const flags = [];
+      if (agent.default) flags.push("default");
+      if (agent.resolveFromShellAliases) flags.push("shell-alias");
+      if (agent.promptArgPosition) flags.push(`prompt=${agent.promptArgPosition}`);
+      const flagStr = flags.length > 0 ? ` [${flags.join(", ")}]` : "";
+      const args = agent.args && agent.args.length > 0 ? ` ${agent.args.join(" ")}` : "";
+      console.log(`  ${agent.id.padEnd(12)} ${agent.label.padEnd(20)} ${agent.command}${args}${flagStr}`);
+    }
+  } catch (error) {
+    reportAndExit(error);
+  }
+});
+agentsCommand.command("add").description("Add a new agent to ~/.syntaur/config.md").requiredOption("--id <id>", "Agent id (slug)").requiredOption("--label <label>", "Display label").requiredOption("--command <command>", "Absolute path or bare binary name").option("--args <csv>", "Comma-separated default args").option("--prompt-arg-position <position>", "first | last | none").option("--default", "Mark this agent as the default launch target").option("--resolve-from-shell-aliases", "Run via $SHELL -i -c (for shell aliases)").option("--dry-run", "Validate and print the proposed config without writing").action(async (options) => {
+  try {
+    const agent = buildAgentFromOptions(options, null);
+    const mutation = {
+      kind: "add",
+      apply: (current) => {
+        if (current.some((a) => a.id === agent.id)) {
+          throw new AgentConfigError(`agent "${agent.id}" already exists`);
+        }
+        const next = agent.default ? current.map((a) => ({ ...a, default: false })) : [...current];
+        return [...next, agent];
+      }
+    };
+    const result = await updateAgentsConfig(mutation, {
+      dryRun: Boolean(options.dryRun)
+    });
+    reportMutation("add", result);
+  } catch (error) {
+    reportAndExit(error);
+  }
+});
+agentsCommand.command("remove <id>").description("Remove an agent from ~/.syntaur/config.md").option("--dry-run", "Validate and print the proposed config without writing").action(async (id, options) => {
+  try {
+    const mutation = {
+      kind: "remove",
+      apply: (current) => {
+        if (!current.some((a) => a.id === id)) {
+          throw new AgentConfigError(`unknown agent id "${id}"`);
+        }
+        return current.filter((a) => a.id !== id);
+      }
+    };
+    const result = await updateAgentsConfig(mutation, {
+      dryRun: Boolean(options.dryRun)
+    });
+    reportMutation("remove", result);
+  } catch (error) {
+    reportAndExit(error);
+  }
+});
+agentsCommand.command("set <id>").description("Update one or more fields on an existing agent").option("--label <label>", "Display label").option("--command <command>", "Absolute path or bare binary name").option("--args <csv>", "Comma-separated default args").option("--prompt-arg-position <position>", "first | last | none").option("--default", "Mark this agent as the default (clears any prior default)").option("--no-default", "Unset the default flag on this agent").option("--resolve-from-shell-aliases", "Run via $SHELL -i -c (for shell aliases)").option("--no-resolve-from-shell-aliases", "Disable shell-alias resolution for this agent").option("--dry-run", "Validate and print the proposed config without writing").action(async (id, options) => {
+  try {
+    const mutation = {
+      kind: "set",
+      apply: (current) => {
+        const existing = current.find((a) => a.id === id);
+        if (!existing) {
+          throw new AgentConfigError(`unknown agent id "${id}"`);
+        }
+        const merged = mergeOptionsIntoAgent(existing, options);
+        const defaultFlip = options.default === true;
+        return current.map((a) => {
+          if (a.id === id) return merged;
+          if (defaultFlip) return { ...a, default: false };
+          return a;
+        });
+      }
+    };
+    const result = await updateAgentsConfig(mutation, {
+      dryRun: Boolean(options.dryRun)
+    });
+    reportMutation("set", result);
+  } catch (error) {
+    reportAndExit(error);
+  }
+});
+agentsCommand.command("reorder <ids>").description("Reorder agents (comma-separated ids, must cover every configured agent exactly once)").option("--dry-run", "Validate and print the proposed config without writing").action(async (ids, options) => {
+  try {
+    const newOrder = ids.split(",").map((s) => s.trim()).filter(Boolean);
+    const mutation = {
+      kind: "reorder",
+      apply: (current) => {
+        const seen = /* @__PURE__ */ new Set();
+        for (const id of newOrder) {
+          if (seen.has(id)) {
+            throw new AgentConfigError(`duplicate id "${id}" in reorder list`);
+          }
+          seen.add(id);
+        }
+        const currentIds = new Set(current.map((a) => a.id));
+        const missing = current.filter((a) => !seen.has(a.id)).map((a) => a.id);
+        const extra = newOrder.filter((id) => !currentIds.has(id));
+        if (missing.length > 0 || extra.length > 0) {
+          const parts = [];
+          if (missing.length) parts.push(`missing: ${missing.join(", ")}`);
+          if (extra.length) parts.push(`unknown: ${extra.join(", ")}`);
+          throw new AgentConfigError(
+            `reorder list does not match current agents (${parts.join("; ")})`
+          );
+        }
+        return newOrder.map((id) => current.find((a) => a.id === id));
+      }
+    };
+    const result = await updateAgentsConfig(mutation, {
+      dryRun: Boolean(options.dryRun)
+    });
+    reportMutation("reorder", result);
+  } catch (error) {
+    reportAndExit(error);
+  }
+});
+function buildAgentFromOptions(options, existing) {
+  const agent = {
+    id: options.id,
+    label: options.label,
+    command: parseAgentCommand(options.command, options.id)
+  };
+  const args = parseArgsCsv(options.args);
+  if (args) agent.args = args;
+  if (options.promptArgPosition) {
+    agent.promptArgPosition = options.promptArgPosition;
+  }
+  if (options.default) agent.default = true;
+  if (options.resolveFromShellAliases) agent.resolveFromShellAliases = true;
+  validateAgentList([...existing ? [] : [], agent]);
+  return agent;
+}
+function mergeOptionsIntoAgent(existing, options) {
+  const merged = { ...existing };
+  if (options.label !== void 0) merged.label = options.label;
+  if (options.command !== void 0) {
+    merged.command = parseAgentCommand(options.command, existing.id);
+  }
+  if (options.args !== void 0) {
+    const parsed = parseArgsCsv(options.args);
+    if (parsed) merged.args = parsed;
+    else delete merged.args;
+  }
+  if (options.promptArgPosition !== void 0) {
+    merged.promptArgPosition = options.promptArgPosition;
+  }
+  if (options.default === true) merged.default = true;
+  if (options.default === false) delete merged.default;
+  if (options.resolveFromShellAliases === true) merged.resolveFromShellAliases = true;
+  if (options.resolveFromShellAliases === false) delete merged.resolveFromShellAliases;
+  return merged;
+}
+function parseArgsCsv(csv) {
+  if (csv === void 0) return null;
+  const parts = csv.split(",").map((s) => s.trim()).filter((s) => s.length > 0);
+  return parts.length > 0 ? parts : null;
+}
+function reportMutation(action, result) {
+  const diff = renderDiff(result.previous, result.next);
+  if (result.written) {
+    console.log(`Agents updated (${action}):`);
+    console.log(diff);
+  } else {
+    console.log(`Dry run (${action}) \u2014 no changes written:`);
+    console.log(diff);
+  }
+}
+function renderDiff(prev, next) {
+  const prevLines = prev.map(formatAgentLine);
+  const nextLines = next.map(formatAgentLine);
+  const prevSet = new Set(prevLines);
+  const nextSet = new Set(nextLines);
+  const out = [];
+  for (const line of prevLines) {
+    if (!nextSet.has(line)) out.push(`  - ${line}`);
+  }
+  for (const line of nextLines) {
+    if (!prevSet.has(line)) out.push(`  + ${line}`);
+  }
+  if (out.length === 0) out.push("  (no changes)");
+  return out.join("\n");
+}
+function formatAgentLine(a) {
+  const flags = [];
+  if (a.default) flags.push("default");
+  if (a.resolveFromShellAliases) flags.push("shell-alias");
+  if (a.promptArgPosition) flags.push(`prompt=${a.promptArgPosition}`);
+  if (a.args && a.args.length > 0) flags.push(`args=[${a.args.join(", ")}]`);
+  const suffix = flags.length > 0 ? ` (${flags.join(", ")})` : "";
+  return `${a.id}: ${a.label} \u2192 ${a.command}${suffix}`;
+}
+function reportAndExit(error) {
+  console.error("Error:", error instanceof Error ? error.message : String(error));
+  process.exit(1);
+}
+
 // src/commands/comment.ts
 init_paths();
 init_fs();
 init_config2();
-import { resolve as resolve43 } from "path";
-import { readFile as readFile26 } from "fs/promises";
+import { resolve as resolve44 } from "path";
+import { readFile as readFile28 } from "fs/promises";
 init_timestamp();
 init_assignment_resolver();
 function shortId() {
@@ -15204,7 +16328,7 @@ async function commentCommand(target, text, options = {}) {
     if (!isValidSlug(target)) {
       throw new Error(`Invalid assignment slug "${target}".`);
     }
-    assignmentDir = resolve43(baseDir, options.project, "assignments", target);
+    assignmentDir = resolve44(baseDir, options.project, "assignments", target);
     assignmentRef = target;
   } else {
     const resolved = await resolveAssignmentById(baseDir, assignmentsDir(), target);
@@ -15214,13 +16338,13 @@ async function commentCommand(target, text, options = {}) {
     assignmentDir = resolved.assignmentDir;
     assignmentRef = resolved.standalone ? resolved.id : resolved.assignmentSlug;
   }
-  const commentsPath = resolve43(assignmentDir, "comments.md");
+  const commentsPath = resolve44(assignmentDir, "comments.md");
   const timestamp = nowTimestamp();
   const author = options.author ?? process.env.USER ?? "unknown";
   let currentContent;
   let currentCount = 0;
   if (await fileExists(commentsPath)) {
-    currentContent = await readFile26(commentsPath, "utf-8");
+    currentContent = await readFile28(commentsPath, "utf-8");
     const countMatch = currentContent.match(/^entryCount:\s*(\d+)/m);
     if (countMatch) currentCount = parseInt(countMatch[1], 10);
   } else {
@@ -15257,8 +16381,8 @@ ${entry}`;
 init_paths();
 init_fs();
 init_config2();
-import { resolve as resolve44 } from "path";
-import { readFile as readFile27 } from "fs/promises";
+import { resolve as resolve45 } from "path";
+import { readFile as readFile29 } from "fs/promises";
 init_timestamp();
 init_assignment_resolver();
 function setTopLevelField3(content, key, value) {
@@ -15283,7 +16407,7 @@ async function requestCommand(target, text, options = {}) {
     if (!isValidSlug(target)) {
       throw new Error(`Invalid assignment slug "${target}".`);
     }
-    assignmentDir = resolve44(baseDir, options.project, "assignments", target);
+    assignmentDir = resolve45(baseDir, options.project, "assignments", target);
     targetRef = target;
   } else {
     const resolved = await resolveAssignmentById(baseDir, assignmentsDir(), target);
@@ -15293,12 +16417,12 @@ async function requestCommand(target, text, options = {}) {
     assignmentDir = resolved.assignmentDir;
     targetRef = resolved.standalone ? resolved.id : resolved.assignmentSlug;
   }
-  const assignmentMdPath = resolve44(assignmentDir, "assignment.md");
+  const assignmentMdPath = resolve45(assignmentDir, "assignment.md");
   if (!await fileExists(assignmentMdPath)) {
     throw new Error(`assignment.md not found at ${assignmentMdPath}`);
   }
   const source = options.from ?? process.env.SYNTAUR_ASSIGNMENT ?? "unknown";
-  let content = await readFile27(assignmentMdPath, "utf-8");
+  let content = await readFile29(assignmentMdPath, "utf-8");
   const todoLine = `- [ ] ${text.trim()} (from: ${source})`;
   const todosHeading = /^## Todos\s*$/m;
   if (todosHeading.test(content)) {
@@ -15366,20 +16490,20 @@ async function getDefaultCommandName() {
 init_paths();
 init_fs();
 import { fileURLToPath as fileURLToPath9 } from "url";
-import { readFile as readFile29 } from "fs/promises";
-import { dirname as dirname13, join as join7, resolve as resolve45 } from "path";
-import { spawn as spawn3 } from "child_process";
+import { readFile as readFile31 } from "fs/promises";
+import { dirname as dirname13, join as join7, resolve as resolve46 } from "path";
+import { spawn as spawn4 } from "child_process";
 import { createInterface as createInterface2 } from "readline/promises";
 
 // src/utils/version.ts
 import { fileURLToPath as fileURLToPath8 } from "url";
-import { readFile as readFile28 } from "fs/promises";
+import { readFile as readFile30 } from "fs/promises";
 import { dirname as dirname12, join as join6 } from "path";
 async function readPackageVersion(scriptUrl) {
   try {
     const scriptPath = fileURLToPath8(scriptUrl);
     const pkgRoot = dirname12(dirname12(scriptPath));
-    const raw = await readFile28(join6(pkgRoot, "package.json"), "utf-8");
+    const raw = await readFile30(join6(pkgRoot, "package.json"), "utf-8");
     const parsed = JSON.parse(raw);
     return typeof parsed.version === "string" ? parsed.version : null;
   } catch {
@@ -15388,7 +16512,7 @@ async function readPackageVersion(scriptUrl) {
 }
 
 // src/utils/npx-prompt.ts
-var STATE_FILE = resolve45(syntaurRoot(), "npx-install.json");
+var STATE_FILE = resolve46(syntaurRoot(), "npx-install.json");
 var META_ARGS = /* @__PURE__ */ new Set(["-h", "--help", "-V", "--version", "help"]);
 var GLOBAL_VERSION_TIMEOUT_MS = 2e3;
 function isRunningViaNpx(scriptUrl) {
@@ -15409,7 +16533,7 @@ function isRunningViaNpx(scriptUrl) {
 async function readState() {
   if (!await fileExists(STATE_FILE)) return null;
   try {
-    const raw = await readFile29(STATE_FILE, "utf-8");
+    const raw = await readFile31(STATE_FILE, "utf-8");
     return JSON.parse(raw);
   } catch {
     return null;
@@ -15432,7 +16556,7 @@ async function resolveNpmBin() {
 async function installGlobally() {
   const { cmd, shell } = await resolveNpmBin();
   return new Promise((resolvePromise) => {
-    const child = spawn3(cmd, ["install", "-g", "syntaur"], {
+    const child = spawn4(cmd, ["install", "-g", "syntaur"], {
       stdio: "inherit",
       shell
     });
@@ -15443,7 +16567,7 @@ async function installGlobally() {
 async function readGlobalVersion() {
   const { cmd, shell } = await resolveNpmBin();
   const rootPath = await new Promise((resolvePromise) => {
-    const child = spawn3(cmd, ["root", "-g"], {
+    const child = spawn4(cmd, ["root", "-g"], {
       shell,
       stdio: ["ignore", "pipe", "ignore"]
     });
@@ -15468,7 +16592,7 @@ async function readGlobalVersion() {
   try {
     const manifestPath = join7(rootPath, "syntaur", "package.json");
     if (!await fileExists(manifestPath)) return null;
-    const raw = await readFile29(manifestPath, "utf-8");
+    const raw = await readFile31(manifestPath, "utf-8");
     const parsed = JSON.parse(raw);
     return typeof parsed.version === "string" ? parsed.version : null;
   } catch {
@@ -15587,7 +16711,7 @@ async function maybePromptInstall(scriptUrl) {
 
 // src/index.ts
 await maybePromptInstall(import.meta.url);
-var program = new Command4();
+var program = new Command5();
 var version = await readPackageVersion(import.meta.url) ?? "0.0.0";
 program.name("syntaur").description("CLI scaffolding tool for the Syntaur protocol").version(version);
 program.command("init").description("Initialize ~/.syntaur/ directory structure and config").option("--force", "Overwrite existing config file").action(async (options) => {
@@ -15878,7 +17002,7 @@ program.command("track-session").description("Register an agent session (optiona
     process.exit(1);
   }
 });
-program.command("browse").description("Interactive TUI browser for projects and assignments").option("--agent <type>", "Agent to launch: claude or codex", "claude").action(async (options) => {
+program.command("browse").description("Interactive TUI browser for projects and assignments").option("--agent <id>", "Bypass the agent picker and launch the given configured agent id").option("--no-worktree-prompt", "Skip the prompt to create a worktree when one is missing").action(async (options) => {
   try {
     await browseCommand(options);
   } catch (error) {
@@ -15936,6 +17060,7 @@ program.command("disable-playbook").description("Disable a playbook so agents no
 program.addCommand(todoCommand);
 program.addCommand(backupCommand);
 program.addCommand(doctorCommand);
+program.addCommand(agentsCommand);
 if (process.argv.length <= 2) {
   process.argv.push(await getDefaultCommandName());
 }