@ricsam/r5dctl 0.0.58 → 0.0.60

package/README.md

@@ -78,6 +78,13 @@ r5dctl -s <session-id> prompt --mode plan --model max "..."
 r5dctl -s <session-id> answer-questions -a1 "Recipe Collection" -a2 "Both Manual & AI"
 r5dctl -s <session-id> answer-env-request -e KEY=value --context "Generate the remaining salts"
 
+r5dctl -p <project> agent start --worker <label> --source worktree:main debug "Fix the failing tests"
+r5dctl agent status <session-id>
+r5dctl agent prompt --worker <label> <session-id> "Also check the migration"
+r5dctl agent merge --worker <label> <session-id>
+r5dctl agent stop <session-id>
+r5dctl agent finish-merge --worker <label> <resolver-session-id> --summary "Resolved the conflicts"
+
 r5dctl -p <project> -b <branch> shell
 r5dctl -p <project> -b <branch> shell -c "bun test"
 
@@ -92,6 +99,8 @@ r5dctl k8s usage --window 7d
 r5dctl k8s usage --workload default/api --window 7d --json
 ```
 
+Branch agents are independent sessions on automatically created branches. `agent start` requires an explicit worker and `--source worktree:<branch>`; it never infers either from the local directory. The source is the named branch worktree, including its committed and uncommitted files. Starting returns after that worktree has been copied into the new branch worktree and queued; execution continues asynchronously. Follow-up, merge, and resolver commands must name the session's bound worker; they do not move work between workers implicitly. A prompt response reports whether it was `queued` into an active generation or `started` as a new generation. Use `agent status` to inspect progress, then `agent merge` after the agent reaches a terminal state. A conflicting merge starts a resolver session; stop that resolver for manual takeover and use `agent finish-merge` after resolving and reviewing its worktree.
+
 `shell` connects to the same live worker PTY as the web Shell tab. Without `-c` it attaches the local terminal interactively. With `-c`/`--command`, it runs the supplied shell expression, streams combined PTY output, and exits with the remote command's status. Because command output uses a PTY, stdout and stderr are combined and programs may emit colors or other terminal control sequences.
 
 `ps list` shows active long-running commands managed by r5d. It does not expose the worker host's general OS process table or interactive PTYs. Global project, branch, and session options filter the list, while `--worker` selects a worker label. `ps stop` sends `SIGTERM` to the selected run. Inside an r5d-provided worker shell, the temporary credential can only list and stop runs on that shell's worker.

package/dist/cjs/cli.cjs

@@ -30,6 +30,7 @@ var cli_exports = {};
 __export(cli_exports, {
   advanceTransientDevicePollBackoff: () => advanceTransientDevicePollBackoff,
   collectK8sUsage: () => collectK8sUsage,
+  dispatchBranchAgentCommand: () => dispatchBranchAgentCommand,
   formatK8sCpu: () => formatK8sCpu,
   formatK8sMemory: () => formatK8sMemory,
   formatProcessAge: () => formatProcessAge,
@@ -41,6 +42,7 @@ __export(cli_exports, {
   handleAuthLogin: () => handleAuthLogin,
   main: () => main,
   parseAnswerFlags: () => parseAnswerFlags,
+  parseBranchAgentCommand: () => parseBranchAgentCommand,
   parseConversationRenderArgs: () => parseConversationRenderArgs,
   parseConversationWorkDetailArgs: () => parseConversationWorkDetailArgs,
   parseEnvFlags: () => parseEnvFlags,
@@ -54,6 +56,9 @@ __export(cli_exports, {
   parseSetEnvArgs: () => parseSetEnvArgs,
   parseShellArgs: () => parseShellArgs,
   readDotenvFile: () => readDotenvFile,
+  renderBranchAgentMerge: () => renderBranchAgentMerge,
+  renderBranchAgentStart: () => renderBranchAgentStart,
+  renderBranchAgentStatus: () => renderBranchAgentStatus,
   renderConversationNodeResponse: () => renderConversationNodeResponse,
   renderConversationOverviewResponse: () => renderConversationOverviewResponse,
   renderConversationResponse: () => renderConversationResponse,
@@ -149,6 +154,19 @@ const K8S_HELP_TEXT = [
   "Show current and rolling CPU and memory usage for managed-vCluster workload containers.",
   ""
 ].join("\n");
+const AGENT_HELP_TEXT = [
+  "Usage:",
+  '  r5dctl -p <project> agent start --worker <label> --source worktree:<branch> <research|debug|test> "<prompt>"',
+  "  r5dctl agent status <session-id>",
+  '  r5dctl agent prompt --worker <label> <session-id> "<prompt>"',
+  "  r5dctl agent merge --worker <label> <session-id>",
+  "  r5dctl agent stop <session-id>",
+  '  r5dctl agent finish-merge --worker <label> <resolver-session-id> --summary "<summary>"',
+  "",
+  "Create, inspect, resume, stop, and merge independent branch agents.",
+  "The source is the named branch worktree, including its committed and uncommitted files.",
+  ""
+].join("\n");
 const SHARED_HELP_ENTRIES = [
   { section: "auth", usage: "auth status", description: "Show the current authenticated user and credential source." },
   { section: "auth", usage: "auth logout", description: "Revoke the current credential and clear saved auth." },
@@ -272,18 +290,34 @@ const SHARED_HELP_ENTRIES = [
   { section: "processes", usage: "ps stop <run-id>", description: "Gracefully stop an active process with SIGTERM." },
   {
     section: "agents",
-    usage: '-p <project> start-agent <src-branch> <agent-type> "<prompt>"',
-    description: "Start a detached branch agent."
+    usage: '-p <project> agent start --worker <label> --source worktree:<branch> <research|debug|test> "<prompt>"',
+    description: "Create a branch from an explicit worktree source and start an independent agent."
+  },
+  {
+    section: "agents",
+    usage: "agent status <session-id>",
+    description: "Show branch-agent execution, publication, and merge status."
+  },
+  {
+    section: "agents",
+    usage: 'agent prompt --worker <label> <session-id> "<prompt>"',
+    description: "Queue a prompt or resume an idle branch agent on the selected worker."
   },
-  { section: "agents", usage: "agent-status <session-id>", description: "Show detached branch agent status." },
-  { section: "agents", usage: 'send-prompt <session-id> "<prompt>"', description: "Queue or resume a detached branch agent." },
   {
-    section: "merges",
-    usage: "-p <project> merge-changes <target-branch> <sub-agent-branch>",
-    description: "Squash merge an agent branch into a target branch."
+    section: "agents",
+    usage: "agent merge --worker <label> <session-id>",
+    description: "Merge a terminal branch agent into its recorded parent worktree."
+  },
+  {
+    section: "agents",
+    usage: "agent stop <session-id>",
+    description: "Stop a branch agent or merge resolver."
   },
-  { section: "merges", usage: "-p <project> continue-merge <target-branch>", description: "Commit a resolved merge." },
-  { section: "merges", usage: "-p <project> abort-merge <target-branch>", description: "Abort an in-progress merge." }
+  {
+    section: "agents",
+    usage: 'agent finish-merge --worker <label> <resolver-session-id> --summary "<summary>"',
+    description: "Publish and finalize a manually resolved merge."
+  }
 ];
 const HELP_SECTION_ORDER = [
   "auth",
@@ -295,8 +329,7 @@ const HELP_SECTION_ORDER = [
   "kubernetes",
   "processes",
   "shell",
-  "agents",
-  "merges"
+  "agents"
 ];
 const HELP_SECTION_TITLES = {
   auth: "Auth",
@@ -308,8 +341,7 @@ const HELP_SECTION_TITLES = {
   kubernetes: "Kubernetes",
   processes: "Processes",
   shell: "Shell",
-  agents: "Agents",
-  merges: "Merges"
+  agents: "Branch agents"
 };
 function getCliHelpText() {
   const entries = [...CLI_ONLY_HELP_ENTRIES, ...SHARED_HELP_ENTRIES];
@@ -408,7 +440,7 @@ function renderCliOnlyCommandHelp(entry) {
 function renderSharedCommandHelp(pathSegments) {
   const entry = SHARED_HELP_ENTRIES.map((candidate) => ({
     candidate,
-    usageSegments: candidate.usage.split(" ").map((segment) => segment.replace(/^\[/, "").replace(/\]$/, "")).filter((segment) => !segment.startsWith("-") && !segment.startsWith("<") && !segment.startsWith("["))
+    usageSegments: candidate.usage.split(" ").map((segment) => segment.replace(/^\[/, "").replace(/\]$/, "")).filter((segment) => !segment.startsWith("-") && !segment.includes("<") && !segment.startsWith("["))
   })).filter(
     ({ usageSegments }) => usageSegments.length <= pathSegments.length && usageSegments.every((segment, index) => segment === pathSegments[index])
   ).sort((left, right) => right.usageSegments.length - left.usageSegments.length)[0]?.candidate;
@@ -456,6 +488,108 @@ function parseOptionalFlagValue(args, flag, shortFlag) {
 function hasBooleanFlag(args, flag) {
   return args.includes(flag);
 }
+function parseAgentOperands(args, valueFlags, options = {}) {
+  const positionals = [];
+  const values = /* @__PURE__ */ new Map();
+  let parseOptions = true;
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+    if (parseOptions && arg === "--") {
+      parseOptions = false;
+      continue;
+    }
+    const inlineFlag = parseOptions ? [...valueFlags].find((flag) => arg.startsWith(`${flag}=`)) : void 0;
+    if (inlineFlag) {
+      if (values.has(inlineFlag)) throw new Error(`${inlineFlag} may only be provided once`);
+      const value = arg.slice(inlineFlag.length + 1).trim();
+      if (!value) throw new Error(`Missing value for ${inlineFlag}`);
+      values.set(inlineFlag, value);
+      continue;
+    }
+    if (parseOptions && valueFlags.has(arg)) {
+      if (values.has(arg)) throw new Error(`${arg} may only be provided once`);
+      const value = args[index + 1];
+      if (!value || value === "--" || valueFlags.has(value)) throw new Error(`Missing value for ${arg}`);
+      values.set(arg, value.trim());
+      index += 1;
+      continue;
+    }
+    if (parseOptions && arg.startsWith("-") && positionals.length < (options.allowFlagLikeValuesAfter ?? Number.POSITIVE_INFINITY)) {
+      throw new Error(`Unknown agent flag: ${arg}`);
+    }
+    positionals.push(arg);
+  }
+  return { positionals, values };
+}
+function requireAgentWorker(values) {
+  return requireValue(values.get("--worker")?.trim(), "--worker <label> is required");
+}
+function requireAgentSource(values) {
+  const raw = requireValue(values.get("--source")?.trim(), "--source worktree:<branch> is required for `agent start`");
+  const separator = raw.indexOf(":");
+  const type = raw.slice(0, separator);
+  const branchName = raw.slice(separator + 1).trim();
+  if (type !== "worktree" || separator < 1 || !branchName) {
+    throw new Error("Invalid --source. Expected worktree:<branch>");
+  }
+  return { type, branchName };
+}
+function rejectAgentGlobalScopes(options, allowProject) {
+  if (!allowProject && options.project) throw new Error("--project/-p is only supported for `agent start`");
+  if (options.branch) throw new Error("--branch/-b is not supported for `agent`; pass --source explicitly");
+  if (options.session) throw new Error("--session/-s is not supported for `agent`; pass the session id explicitly");
+}
+function parseBranchAgentCommand(options, args) {
+  const subcommand = requireValue(args[0], "Missing agent command");
+  const commandArgs = args.slice(1);
+  if (subcommand === "start") {
+    rejectAgentGlobalScopes(options, true);
+    const project = requireValue(options.project, "--project/-p is required for `agent start`");
+    const parsed = parseAgentOperands(commandArgs, /* @__PURE__ */ new Set(["--worker", "--source"]), { allowFlagLikeValuesAfter: 1 });
+    const agentType = requireValue(parsed.positionals[0], "Agent type is required for `agent start`");
+    if (!AGENT_TYPES.has(agentType)) {
+      throw new Error("Invalid agent type. Expected one of: research, debug, test");
+    }
+    const prompt = parsed.positionals.slice(1).join(" ").trim();
+    if (!prompt) throw new Error("Agent prompt is required for `agent start`");
+    return {
+      kind: "start",
+      project,
+      worker: requireAgentWorker(parsed.values),
+      source: requireAgentSource(parsed.values),
+      agentType,
+      prompt
+    };
+  }
+  rejectAgentGlobalScopes(options, false);
+  if (subcommand === "status" || subcommand === "stop") {
+    const parsed = parseAgentOperands(commandArgs, /* @__PURE__ */ new Set());
+    const sessionId = requireValue(parsed.positionals[0], `Session id is required for \`agent ${subcommand}\``);
+    if (parsed.positionals.length > 1) throw new Error(`Unexpected agent ${subcommand} argument: ${parsed.positionals[1]}`);
+    return { kind: subcommand, sessionId };
+  }
+  if (subcommand === "prompt") {
+    const parsed = parseAgentOperands(commandArgs, /* @__PURE__ */ new Set(["--worker"]), { allowFlagLikeValuesAfter: 1 });
+    const sessionId = requireValue(parsed.positionals[0], "Session id is required for `agent prompt`");
+    const prompt = parsed.positionals.slice(1).join(" ").trim();
+    if (!prompt) throw new Error("Prompt is required for `agent prompt`");
+    return { kind: "prompt", worker: requireAgentWorker(parsed.values), sessionId, prompt };
+  }
+  if (subcommand === "merge") {
+    const parsed = parseAgentOperands(commandArgs, /* @__PURE__ */ new Set(["--worker"]));
+    const sessionId = requireValue(parsed.positionals[0], "Session id is required for `agent merge`");
+    if (parsed.positionals.length > 1) throw new Error(`Unexpected agent merge argument: ${parsed.positionals[1]}`);
+    return { kind: "merge", worker: requireAgentWorker(parsed.values), sessionId };
+  }
+  if (subcommand === "finish-merge") {
+    const parsed = parseAgentOperands(commandArgs, /* @__PURE__ */ new Set(["--worker", "--summary"]));
+    const resolverSessionId = requireValue(parsed.positionals[0], "Resolver session id is required for `agent finish-merge`");
+    if (parsed.positionals.length > 1) throw new Error(`Unexpected agent finish-merge argument: ${parsed.positionals[1]}`);
+    const summary = requireValue(parsed.values.get("--summary")?.trim(), "--summary <text> is required for `agent finish-merge`");
+    return { kind: "finish-merge", worker: requireAgentWorker(parsed.values), resolverSessionId, summary };
+  }
+  throw new Error(`Unknown agent command: ${subcommand}`);
+}
 function assertAuthLoginArgs(args) {
   const valueFlags = /* @__PURE__ */ new Set(["--device-name", "--worker-label"]);
   const booleanFlags = /* @__PURE__ */ new Set(["--no-open", "--no-qr"]);
@@ -1228,7 +1362,11 @@ function renderWorkspaceStatus(status) {
   const lines = [
     `Workspace HEAD: ${status.head ?? "(not initialized)"}`,
     `Latest sync: ${status.latestSync ? `${status.latestSync.outcome} on ${status.latestSync.workerLabel}` : "(none)"}`,
-    `Remediation: ${status.incident ? `${status.incident.status} (${status.incident.id}) on ${status.incident.originWorkerLabel}` : "none"}`
+    `Remediation: ${status.incident ? `${status.incident.kind} ${status.incident.status} (${status.incident.id}) on ${status.incident.originWorkerLabel}` : "none"}`,
+    `Materialization: ${status.materialization ? `${status.materialization.state}; ${status.materialization.materializedHead ?? "(none)"} -> ${status.materialization.desiredHead ?? "(none)"}; lag ${status.materialization.lagMs}ms` : "not initialized"}`,
+    ...status.workers.map(
+      (worker) => `Worker ${worker.workerLabel}: ${worker.ready ? "ready" : "bootstrapping"}; publication ${worker.publicationState}; head ${worker.localHead ?? "(none)"}; desired ${worker.desiredCanonicalHead ?? "(none)"}; generations ${worker.publishedGeneration}/${worker.dirtyGeneration}; pending checkouts ${worker.pendingCheckouts.length}; CAS retries ${worker.casRetries}; fan-out lag ${worker.fanoutLagMs ?? "unknown"}ms`
+    )
   ];
   return `${lines.join("\n")}
 `;
@@ -1597,43 +1735,164 @@ async function setProjectEnvs(client, projectRef, args) {
   }
   return result;
 }
-function renderAgentStart(agent) {
-  return [
-    `Agent: ${agent.sessionId}`,
-    `Status: ${agent.status}`,
-    `Branch: ${agent.branchName}`,
-    `Base: ${agent.baseBranch} @ ${agent.baseCommit}`
-  ].join("\n") + "\n";
-}
-function renderAgentStatus(agent) {
-  const lines = [`Agent: ${agent.sessionId}`, `Status: ${agent.status}`, `Branch: ${agent.branchName}`, `Head: ${agent.headCommit}`];
-  if (agent.baseBranch && agent.baseCommit) {
-    lines.push(`Base: ${agent.baseBranch} @ ${agent.baseCommit}`);
-  }
-  if (agent.error) {
-    lines.push(`Error: ${agent.error}`);
-  }
-  if (agent.diffSummary) {
-    lines.push("", agent.diffSummary);
+function responseString(response, key) {
+  const value = response[key];
+  return typeof value === "string" && value.length > 0 ? value : void 0;
+}
+function responseSource(response) {
+  const source = response.source;
+  if (!source || source.type !== "worktree" || !source.branchName) return void 0;
+  return `${source.type}:${source.branchName}`;
+}
+function formatStatusValue(value) {
+  if (typeof value === "string" && value.length > 0) return value;
+  if (typeof value === "object" && value !== null) {
+    const status = value.status;
+    if (typeof status === "string" && status.length > 0) return status;
+    return JSON.stringify(value);
+  }
+  return value === void 0 || value === null ? void 0 : String(value);
+}
+function asResponseRecord(value) {
+  return typeof value === "object" && value !== null ? value : void 0;
+}
+function appendMergeDetails(lines, response) {
+  const merge = asResponseRecord(response.merge);
+  if (!merge) return;
+  const mergeStatus = formatStatusValue(merge.status);
+  lines.push("", `Merge: ${mergeStatus ?? "pending"}`);
+  for (const [label, key] of [
+    ["Attempt", "attemptId"],
+    ["Source", "sourceBranch"],
+    ["Target", "targetBranch"],
+    ["Commit", "commitHash"],
+    ["Resolver agent", "resolverSessionId"],
+    ["Resolver branch", "resolverBranch"],
+    ["Resolver worktree", "folderPath"]
+  ]) {
+    const value = responseString(merge, key);
+    if (value) lines.push(`${label}: ${value}`);
+  }
+  const conflictedFiles = Array.isArray(merge.conflictedFiles) ? merge.conflictedFiles.filter((file) => typeof file === "string") : [];
+  if (conflictedFiles.length > 0) {
+    lines.push("", "Conflicts:", ...conflictedFiles.map((file) => `- ${file}`));
+  }
+  const message = responseString(merge, "message");
+  if (message) lines.push("", message);
+  const failureReason = responseString(merge, "failureReason");
+  if (failureReason) lines.push(`Failure: ${failureReason}`);
+  const resolverSessionId = responseString(merge, "resolverSessionId");
+  const worker = responseString(merge, "worker") ?? responseString(response, "worker");
+  if (resolverSessionId && worker) {
+    lines.push(
+      "",
+      "Resolver takeover:",
+      `  r5dctl agent stop ${resolverSessionId}`,
+      `  r5dctl agent finish-merge --worker ${worker} ${resolverSessionId} --summary "<summary>"`
+    );
   }
-  if (agent.summary) {
-    lines.push("", agent.summary);
+}
+function renderBranchAgentStart(agent) {
+  const lines = [
+    `Agent: ${responseString(agent, "sessionId") ?? "(unknown)"}`,
+    `Status: ${formatStatusValue(agent.status) ?? "queued"}`,
+    `Branch: ${responseString(agent, "branchName") ?? "(provisioning)"}`,
+    `Source: ${responseSource(agent) ?? "(unknown)"}`,
+    `Workspace head: ${responseString(agent, "workspaceHead") ?? "(pending)"}`,
+    `Baseline: ${responseString(agent, "baselineCommit") ?? "(pending)"}`,
+    `Worker: ${responseString(agent, "worker") ?? "(unassigned)"}`
+  ];
+  const sessionUrl = responseString(agent, "sessionUrl");
+  if (sessionUrl) lines.push(`Session: ${sessionUrl}`);
+  const sessionId = responseString(agent, "sessionId");
+  if (sessionId) lines.push("", `Next: r5dctl agent status ${sessionId}`);
+  return `${lines.join("\n")}
+`;
+}
+function renderBranchAgentStatus(agent) {
+  const status = formatStatusValue(agent.status) ?? "unknown";
+  const lines = [`Agent: ${responseString(agent, "sessionId") ?? "(unknown)"}`, `Status: ${status}`];
+  const runStatus = formatStatusValue(agent.runStatus);
+  if (runStatus) lines.push(`Run: ${runStatus}`);
+  const promptDisposition = responseString(agent, "promptDisposition");
+  if (promptDisposition) lines.push(`Prompt: ${promptDisposition}`);
+  const branch = responseString(agent, "branchName");
+  if (branch) lines.push(`Branch: ${branch}`);
+  const source = responseSource(agent);
+  if (source) lines.push(`Source: ${source}`);
+  for (const [label, key] of [
+    ["Workspace head", "workspaceHead"],
+    ["Baseline", "baselineCommit"],
+    ["Head", "headCommit"],
+    ["Worker", "worker"],
+    ["Session", "sessionUrl"]
+  ]) {
+    const value = responseString(agent, key);
+    if (value) lines.push(`${label}: ${value}`);
+  }
+  const error = responseString(agent, "error");
+  if (error) lines.push(`Error: ${error}`);
+  const headCommitError = responseString(agent, "headCommitError");
+  if (headCommitError) lines.push(`Head error: ${headCommitError}`);
+  const diffSummary = responseString(agent, "diffSummary");
+  if (diffSummary) lines.push("", diffSummary);
+  const summary = responseString(agent, "summary");
+  if (summary) lines.push("", summary);
+  appendMergeDetails(lines, agent);
+  const sessionId = responseString(agent, "sessionId");
+  if (sessionId && !asResponseRecord(agent.merge)) {
+    if (["provisioning", "queued", "running"].includes(status)) {
+      lines.push("", "Next:", `  r5dctl agent status ${sessionId}`, `  r5dctl agent stop ${sessionId}`);
+    } else if (["completed", "failed", "stopped"].includes(status)) {
+      const worker = responseString(agent, "worker") ?? "<worker>";
+      lines.push("", "Next:", `  r5dctl agent merge --worker ${worker} ${sessionId}`);
+    }
   }
   return `${lines.join("\n")}
 `;
 }
-function renderMergeResult(result) {
-  if (result.status === "merged") {
-    return `Merged ${result.sourceBranch} into ${result.targetBranch}: ${result.commitHash}
-${result.message}
+function renderBranchAgentMerge(result) {
+  if (asResponseRecord(result.merge)) return renderBranchAgentStatus(result);
+  const wrapped = {
+    sessionId: result.sessionId,
+    status: result.status,
+    worker: result.worker,
+    merge: result
+  };
+  const lines = [];
+  appendMergeDetails(lines, wrapped);
+  return `${lines.slice(lines[0] === "" ? 1 : 0).join("\n")}
 `;
+}
+async function dispatchBranchAgentCommand(client, command) {
+  if (command.kind === "start") {
+    const data2 = await client.projects.agents.start(command.project, {
+      source: command.source,
+      agentType: command.agentType,
+      prompt: command.prompt,
+      worker: command.worker,
+      requestId: (0, import_node_crypto.randomUUID)()
+    });
+    return { data: data2, human: renderBranchAgentStart(data2) };
   }
-  const files = result.conflictedFiles.length > 0 ? `
-Conflicts:
-${result.conflictedFiles.map((file) => `- ${file}`).join("\n")}
-` : "\n";
-  return `Merge has conflicts from ${result.sourceBranch} into ${result.targetBranch}.${files}${result.message}
-`;
+  if (command.kind === "status") {
+    const data2 = await client.agents.status(command.sessionId);
+    return { data: data2, human: renderBranchAgentStatus(data2) };
+  }
+  if (command.kind === "prompt") {
+    const data2 = await client.agents.sendPrompt(command.sessionId, { prompt: command.prompt, worker: command.worker });
+    return { data: data2, human: renderBranchAgentStatus(data2) };
+  }
+  if (command.kind === "merge") {
+    const data2 = await client.agents.merge(command.sessionId, { worker: command.worker });
+    return { data: data2, human: renderBranchAgentMerge(data2) };
+  }
+  if (command.kind === "stop") {
+    const data2 = await client.agents.stop(command.sessionId);
+    return { data: data2, human: renderBranchAgentStatus(data2) };
+  }
+  const data = await client.agents.finishMerge(command.resolverSessionId, { worker: command.worker, summary: command.summary });
+  return { data, human: renderBranchAgentMerge(data) };
 }
 function parseProjectUpdateArgs(args) {
   const input = {};
@@ -1933,65 +2192,6 @@ Sessions: ${result.sessions.length}
     write(session, renderSessionDescription(session));
     return;
   }
-  if (first === "start-agent") {
-    const projectRef = requireValue(args[1], "Missing project reference");
-    const sourceBranch = requireValue(args[2], "Missing source branch");
-    const agentType = requireValue(args[3], "Missing agent type");
-    if (!AGENT_TYPES.has(agentType)) {
-      throw new Error("Invalid agent type. Expected one of: research, debug, test");
-    }
-    const prompt = args.slice(4).join(" ").trim();
-    if (!prompt) {
-      throw new Error("Agent prompt is required");
-    }
-    const agent = await client.projects.agents.start(projectRef, {
-      sourceBranch,
-      agentType,
-      prompt
-    });
-    write(agent, renderAgentStart(agent));
-    return;
-  }
-  if (first === "agent-status") {
-    const agent = await client.agents.status(requireValue(args[1], "Missing session id"));
-    write(agent, renderAgentStatus(agent));
-    return;
-  }
-  if (first === "send-prompt") {
-    const sessionId = requireValue(args[1], "Missing session id");
-    const prompt = args.slice(2).join(" ").trim();
-    if (!prompt) {
-      throw new Error("Prompt is required");
-    }
-    const agent = await client.agents.sendPrompt(sessionId, { prompt });
-    write(agent, renderAgentStatus(agent));
-    return;
-  }
-  if (first === "merge-changes") {
-    const result = await client.projects.mergeChanges(requireValue(args[1], "Missing project reference"), {
-      targetBranch: requireValue(args[2], "Missing target branch"),
-      sourceBranch: requireValue(args[3], "Missing source branch")
-    });
-    write(result, renderMergeResult(result));
-    return;
-  }
-  if (first === "continue-merge") {
-    const result = await client.projects.continueMerge(requireValue(args[1], "Missing project reference"), {
-      targetBranch: requireValue(args[2], "Missing target branch")
-    });
-    write(result, `Merge committed: ${result.commitHash}
-${result.message}
-`);
-    return;
-  }
-  if (first === "abort-merge") {
-    const result = await client.projects.abortMerge(requireValue(args[1], "Missing project reference"), {
-      targetBranch: requireValue(args[2], "Missing target branch")
-    });
-    write(result, `${result.message}
-`);
-    return;
-  }
   if (first === "sessions" && second === "describe" || first === "describe" && second === "session") {
     const session = await client.sessions.describe(requireValue(args[2], "Missing session id"));
     write(session, renderSessionDescription(session));
@@ -2087,6 +2287,12 @@ function resolveCommandExecution(options, rest) {
       text: K8S_HELP_TEXT
     };
   }
+  if (command === "agent" && commandArgs.length === 0) {
+    return {
+      kind: "cli-help",
+      text: AGENT_HELP_TEXT
+    };
+  }
   if (trailingHelp) {
     const cliOnlyHelp = findCliOnlyCommandHelp(normalizedRest);
     if (cliOnlyHelp) {
@@ -2491,91 +2697,8 @@ function resolveCommandExecution(options, rest) {
       pluginArgs: ["prompt", sessionId, parsed.mode, parsed.model, parsed.message]
     };
   }
-  if (command === "start-agent") {
-    if (!options.project) {
-      throw new Error("--project/-p is required for `start-agent`");
-    }
-    const sourceBranch = commandArgs[0] ?? options.branch;
-    if (!sourceBranch) {
-      throw new Error("Source branch is required for `start-agent`");
-    }
-    const agentType = requireValue(commandArgs[1], "Agent type is required for `start-agent`");
-    if (!AGENT_TYPES.has(agentType)) {
-      throw new Error("Invalid agent type. Expected one of: research, debug, test");
-    }
-    const prompt = commandArgs.slice(2).join(" ").trim();
-    if (!prompt) {
-      throw new Error("Agent prompt is required");
-    }
-    return {
-      kind: "plugin",
-      pluginArgs: ["start-agent", options.project, sourceBranch, agentType, prompt]
-    };
-  }
-  if (command === "agent-status") {
-    const sessionId = commandArgs[0] ?? options.session;
-    if (!sessionId) {
-      throw new Error("Session id is required for `agent-status`");
-    }
-    return {
-      kind: "plugin",
-      pluginArgs: ["agent-status", sessionId]
-    };
-  }
-  if (command === "send-prompt") {
-    const sessionId = options.session ?? commandArgs[0];
-    if (!sessionId) {
-      throw new Error("Session id is required for `send-prompt`");
-    }
-    const promptArgs = options.session ? commandArgs : commandArgs.slice(1);
-    const prompt = promptArgs.join(" ").trim();
-    if (!prompt) {
-      throw new Error("Prompt is required for `send-prompt`");
-    }
-    return {
-      kind: "plugin",
-      pluginArgs: ["send-prompt", sessionId, prompt]
-    };
-  }
-  if (command === "merge-changes") {
-    if (!options.project) {
-      throw new Error("--project/-p is required for `merge-changes`");
-    }
-    const targetBranch = commandArgs[0] ?? options.branch;
-    if (!targetBranch) {
-      throw new Error("Target branch is required for `merge-changes`");
-    }
-    const sourceBranch = requireValue(commandArgs[1], "Sub-agent branch is required for `merge-changes`");
-    return {
-      kind: "plugin",
-      pluginArgs: ["merge-changes", options.project, targetBranch, sourceBranch]
-    };
-  }
-  if (command === "continue-merge") {
-    if (!options.project) {
-      throw new Error("--project/-p is required for `continue-merge`");
-    }
-    const targetBranch = commandArgs[0] ?? options.branch;
-    if (!targetBranch) {
-      throw new Error("Target branch is required for `continue-merge`");
-    }
-    return {
-      kind: "plugin",
-      pluginArgs: ["continue-merge", options.project, targetBranch]
-    };
-  }
-  if (command === "abort-merge") {
-    if (!options.project) {
-      throw new Error("--project/-p is required for `abort-merge`");
-    }
-    const targetBranch = commandArgs[0] ?? options.branch;
-    if (!targetBranch) {
-      throw new Error("Target branch is required for `abort-merge`");
-    }
-    return {
-      kind: "plugin",
-      pluginArgs: ["abort-merge", options.project, targetBranch]
-    };
+  if (command === "agent") {
+    return { kind: "agent", command: parseBranchAgentCommand(options, commandArgs) };
   }
   if (command === "answer-questions") {
     const sessionId = options.session;
@@ -2625,6 +2748,11 @@ async function runCommand(argv) {
     process.stdout.write(execution.text);
     return 0;
   }
+  if (execution.kind === "agent") {
+    const result = await dispatchBranchAgentCommand(client, execution.command);
+    writeDataOutput(options.json, result.data, result.human);
+    return 0;
+  }
   if (execution.kind === "shell") {
     const project = await client.projects.describe(options.project);
     return await (0, import_shell.runR5dctlShell)({
@@ -2674,6 +2802,7 @@ async function main(argv = process.argv.slice(2)) {
 0 && (module.exports = {
   advanceTransientDevicePollBackoff,
   collectK8sUsage,
+  dispatchBranchAgentCommand,
   formatK8sCpu,
   formatK8sMemory,
   formatProcessAge,
@@ -2685,6 +2814,7 @@ async function main(argv = process.argv.slice(2)) {
   handleAuthLogin,
   main,
   parseAnswerFlags,
+  parseBranchAgentCommand,
   parseConversationRenderArgs,
   parseConversationWorkDetailArgs,
   parseEnvFlags,
@@ -2698,6 +2828,9 @@ async function main(argv = process.argv.slice(2)) {
   parseSetEnvArgs,
   parseShellArgs,
   readDotenvFile,
+  renderBranchAgentMerge,
+  renderBranchAgentStart,
+  renderBranchAgentStatus,
   renderConversationNodeResponse,
   renderConversationOverviewResponse,
   renderConversationResponse,