@ricsam/r5dctl 0.0.103 → 0.0.104

package/README.md

@@ -55,6 +55,10 @@ r5dctl delete project <namespace/name|id>
 
 r5dctl -p <project> get branches
 r5dctl -p <project> describe branch <branch>
+r5dctl -p <project> create branch <branch> --source worktree:<branch> [--working-tree carry|clean] [--worker <label>]
+r5dctl -p <project> describe branch-operation <operation-id>
+r5dctl -p <project> delete branch <branch>              # preview the sessions that would be deleted, exit 1
+r5dctl -p <project> delete branch <branch> --confirm    # delete the branch and its sessions through the platform
 r5dctl -p <project> get envs
 r5dctl -p <project> get envs --show-values
 r5dctl -p <project> get env API_KEY
@@ -119,6 +123,12 @@ repository. Trust applies to that workflow path on every Git ref and grants
 cluster-admin, so protect workflow changes and do not invoke it for untrusted
 pull requests.
 
+`create branch` creates a linked worktree branch through the platform from an existing branch's checkout, with the same `--source worktree:<branch>` and `--working-tree carry|clean` semantics as `session start --new-worktree` (carry is the default) and no session prompt. `--worker <label>` selects the connected worker that cuts the checkout; omitted, the platform chooses one, and an r5d worker shell's temporary credential is always bound to its own worker. The command returns as soon as the operation is accepted and prints its id; `describe branch-operation <operation-id>` reports `provisioning`, `ready`, or `failed` with the worker and any error. Neither prints a commit hash: read the branch with git in its checkout once it is ready.
+
+`delete branch` removes a branch and every session on it through the platform, which is the only supported way to remove a linked worktree: the platform owns those checkouts, so never run `git worktree remove`, `git worktree prune`, or `git branch -D` inside a project checkout. Without `--confirm` it prints the branch and its sessions and exits non-zero without deleting anything. The primary branch `main` is refused, as is a branch with a running agent or active process (stop them first). On a server that predates the route, the command explains that the server does not support `delete branch` yet instead of reporting a missing branch.
+
+`get branches` lists every branch the project knows about, including managed branches without sessions. A worker whose workspace sync found a configured branch's checkout directory missing, or present but not a linked worktree of the project, skips that branch and reports it; the listing then shows `checkout=missing on <worker>` or `checkout=not_a_worktree on <worker>`, and `workspace status` prints a `Missing checkouts on <worker>` line. Recover either by deleting the branch with `delete branch <branch> --confirm` or by reconnecting that worker, which recreates the checkout without snapshotting the project's other checkouts.
+
 `session start` creates an ordinary agent-mode chat on an explicitly selected existing worktree, or creates a named linked worktree from an explicit `worktree:<branch>` source. A new worktree is cut from the source branch's current commit; `--working-tree carry` (the default, `git switch -c` semantics) also copies the source checkout's uncommitted changes into it, while `--working-tree clean` checks out that commit only. The new session's first message states which mode applies, and the start output prints `Source` and `Working tree` lines. A clean request fails with a clear error when the selected worker predates the option, because such a worker would silently carry instead. It requires project, worker, model, and prompt and never infers them from the current shell. Start returns a durable `provisioning` handle immediately; workspace synchronization, linked-worktree creation, and prompt enqueue continue in the background and are visible through `session status`. Idempotent request retries return the same handle. Prompts return after durable enqueue. Task specialization belongs in the prompt; there are no predefined debug, explore, research, or test agents. `session stop` returns as soon as the agent run is stopped; the stopped worktree's workspace Git synchronization finishes asynchronously behind the response.
 
 `session status` reports the run lifecycle and the launch-time `Source` and `Working tree` facts only. It deliberately prints no commit hash for the worktree, not even the launch baseline: a hash would be stale by the time a caller acts on it, because commits can land between the read and the action. Find the base and the branch's commits with git in the worker checkout instead, for example `git merge-base <your-branch> <branch>`, `git log --oneline <your-branch>..<branch>`, and `git status` in the branch folder, as the `Branch state` line reminds you. While a new worktree is still provisioning, a `Provisioning` line reports where its creation stands in the worker's operation queue and since when (`Provisioning: queued behind 3 worker operations since 2026-09-03T11:41:30Z`); a worker that predates operation receipts leaves that line out.

package/dist/cjs/cli.cjs

@@ -29,7 +29,10 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var cli_exports = {};
 __export(cli_exports, {
   advanceTransientDevicePollBackoff: () => advanceTransientDevicePollBackoff,
+  branchDeletionConfirmationMessage: () => branchDeletionConfirmationMessage,
   collectK8sUsage: () => collectK8sUsage,
+  createBranchThroughPlatform: () => createBranchThroughPlatform,
+  deleteBranchThroughPlatform: () => deleteBranchThroughPlatform,
   dispatchSessionRunCommand: () => dispatchSessionRunCommand,
   followR5dctlSession: () => followR5dctlSession,
   formatK8sCpu: () => formatK8sCpu,
@@ -41,10 +44,13 @@ __export(cli_exports, {
   getR5dctlVersion: () => getR5dctlVersion,
   getTransientDevicePollDelay: () => getTransientDevicePollDelay,
   handleAuthLogin: () => handleAuthLogin,
+  isUnsupportedServerRoute: () => isUnsupportedServerRoute,
   main: () => main,
   parseAnswerEnvRequestCommandArgs: () => parseAnswerEnvRequestCommandArgs,
   parseAnswerFlags: () => parseAnswerFlags,
   parseAnswerQuestionsCommandArgs: () => parseAnswerQuestionsCommandArgs,
+  parseBranchCreateArgs: () => parseBranchCreateArgs,
+  parseBranchDeleteArgs: () => parseBranchDeleteArgs,
   parseConversationForkArgs: () => parseConversationForkArgs,
   parseConversationInspectWorkArgs: () => parseConversationInspectWorkArgs,
   parseConversationOverviewArgs: () => parseConversationOverviewArgs,
@@ -62,6 +68,10 @@ __export(cli_exports, {
   parseSetEnvArgs: () => parseSetEnvArgs,
   parseShellArgs: () => parseShellArgs,
   readDotenvFile: () => readDotenvFile,
+  renderBranchDeletion: () => renderBranchDeletion,
+  renderBranchDeletionPreview: () => renderBranchDeletionPreview,
+  renderBranchList: () => renderBranchList,
+  renderBranchOperation: () => renderBranchOperation,
   renderConversationForkResponse: () => renderConversationForkResponse,
   renderConversationHeadResponse: () => renderConversationHeadResponse,
   renderConversationNodeResponse: () => renderConversationNodeResponse,
@@ -199,6 +209,21 @@ const SHARED_HELP_ENTRIES = [
   { section: "projects", usage: "delete project <namespace/name|id>", description: "Delete a project." },
   { section: "branches", usage: "-p <project> get branches", description: "List branches for a project." },
   { section: "branches", usage: "-p <project> describe branch <branch>", description: "Show branch URLs and sessions." },
+  {
+    section: "branches",
+    usage: "-p <project> create branch <branch> --source worktree:<branch> [--working-tree <carry|clean>] [--worker <label>]",
+    description: "Create a linked worktree branch from an existing branch's checkout and print the operation id to poll."
+  },
+  {
+    section: "branches",
+    usage: "-p <project> describe branch-operation <operation-id>",
+    description: "Show whether a branch creation is provisioning, ready, or failed."
+  },
+  {
+    section: "branches",
+    usage: "-p <project> delete branch <branch> [--confirm]",
+    description: "Delete a branch and its sessions through the platform; without --confirm, only preview what would be deleted."
+  },
   {
     section: "envs",
     usage: "-p <project> get envs [--show-values]",
@@ -545,8 +570,8 @@ function parseCommandOperands(args, valueFlags, booleanFlags = /* @__PURE__ */ n
 function requireWorker(values) {
   return requireValue(values.get("--worker")?.trim(), "--worker <label> is required");
 }
-function parseWorktreeSource(rawValue) {
-  const raw = requireValue(rawValue?.trim(), "--source worktree:<branch> is required with --new-worktree");
+function parseWorktreeSource(rawValue, requiredMessage = "--source worktree:<branch> is required with --new-worktree") {
+  const raw = requireValue(rawValue?.trim(), requiredMessage);
   const separator = raw.indexOf(":");
   const type = raw.slice(0, separator);
   const branchName = raw.slice(separator + 1).trim();
@@ -573,6 +598,103 @@ function requireSessionMode(value) {
   }
   return mode;
 }
+function parseBranchCreateArgs(args) {
+  const parsed = parseCommandOperands(args, /* @__PURE__ */ new Set(["--source", "--working-tree", "--worker"]), /* @__PURE__ */ new Map(), "create branch", 1);
+  if (parsed.positionals.length > 0) throw new Error(`Unexpected create branch argument: ${parsed.positionals[0]}`);
+  const worker = parsed.values.get("--worker")?.trim();
+  if (parsed.values.has("--worker") && !worker) throw new Error("Missing value for --worker");
+  return {
+    source: parseWorktreeSource(parsed.values.get("--source"), "--source worktree:<branch> is required for `create branch`"),
+    workingTree: parseWorkingTreeMode(parsed.values.get("--working-tree")),
+    ...worker ? { worker } : {}
+  };
+}
+function parseBranchDeleteArgs(args) {
+  let confirmed = false;
+  for (const arg of args) {
+    if (arg === "--confirm") {
+      confirmed = true;
+      continue;
+    }
+    throw new Error(arg.startsWith("-") ? `Unknown delete branch flag: ${arg}` : `Unexpected delete branch argument: ${arg}`);
+  }
+  return { confirmed };
+}
+const PRIMARY_BRANCH_NAME = "main";
+function isUnsupportedServerRoute(error) {
+  return error instanceof import_r5d_api.R5dctlApiError && error.status === 404 && extractApiErrorMessage(error) === "Not Found";
+}
+async function requireServerRouteSupport(command, request) {
+  try {
+    return await request();
+  } catch (error) {
+    if (isUnsupportedServerRoute(error)) {
+      throw new Error(`This r5d server does not support \`${command}\` yet. Update the server, or manage the branch from the web sidebar.`);
+    }
+    throw error;
+  }
+}
+async function createBranchThroughPlatform(client, projectRef, input) {
+  return await requireServerRouteSupport(
+    "create branch",
+    () => client.projects.branches.create(projectRef, {
+      requestId: (0, import_node_crypto.randomUUID)(),
+      branchName: input.branchName,
+      source: input.source,
+      workingTree: input.workingTree,
+      ...input.worker ? { worker: input.worker } : {}
+    })
+  );
+}
+async function deleteBranchThroughPlatform(client, projectRef, branchName, options) {
+  if (branchName === PRIMARY_BRANCH_NAME) throw new Error(`The primary branch ${branchName} cannot be deleted`);
+  const branch = await client.projects.branches.describe(projectRef, branchName);
+  if (!options.confirmed) return { kind: "preview", branch };
+  const result = await requireServerRouteSupport("delete branch", () => client.projects.branches.delete(projectRef, branchName));
+  return { kind: "deleted", result };
+}
+function renderBranchDeletionPreview(branch) {
+  const count = branch.sessions.length;
+  const lines = [
+    `Project: ${branch.project.path}`,
+    `Branch: ${branch.branchName}`,
+    `Sessions: ${count}`,
+    ...branch.sessions.map((session) => `  ${session.id}  ${session.name ?? "(unnamed)"}`),
+    `Deleting this branch removes its checkout from every connected worker and deletes the ${count} session(s) above.`
+  ];
+  return `${lines.join("\n")}
+`;
+}
+function branchDeletionConfirmationMessage(branch) {
+  return `Nothing was deleted. Re-run with --confirm to delete branch ${branch.branchName} and its ${branch.sessions.length} session(s).`;
+}
+function renderBranchDeletion(result) {
+  const lines = [
+    `Deleted branch ${result.branchName} and ${result.deletedSessionIds.length} session(s).`,
+    ...result.deletedSessionIds.map((sessionId) => `  ${sessionId}`)
+  ];
+  return `${lines.join("\n")}
+`;
+}
+function renderBranchOperation(operation, projectRef) {
+  const lines = [
+    `Operation: ${operation.id}`,
+    `Branch: ${operation.branchName}`,
+    `Source: worktree:${operation.source.branchName}`,
+    `Working tree: ${operation.workingTree}`,
+    `Worker: ${operation.worker ?? "(pending)"}`,
+    `Status: ${operation.status}`
+  ];
+  if (operation.error) lines.push(`Error: ${operation.error}`);
+  if (operation.cleanupPending) lines.push("Cleanup: pending");
+  if (operation.status === "provisioning") {
+    lines.push(`Check: r5dctl -p ${projectRef} describe branch-operation ${operation.id}`);
+  } else if (operation.status === "ready") {
+    lines.push(`Branch state: ${formatBranchStateHint(operation.branchName)}`);
+  }
+  return `${lines.join("\n")}
+`;
+}
 function rejectSessionRunGlobalScopes(options, allowProject) {
   if (!allowProject && options.project) throw new Error("--project/-p is only supported for `session start`");
   if (options.branch) throw new Error("--branch/-b is not supported for `session`; select the worktree explicitly");
@@ -1479,10 +1601,34 @@ function renderWorkspaceStatus(status) {
     `Workspace HEAD: ${status.head ?? "(not initialized)"}`,
     `Latest sync: ${status.latestSync ? `${status.latestSync.outcome} on ${status.latestSync.workerLabel}` : "(none)"}`,
     `Remediation: ${status.incident ? `${status.incident.kind} ${status.incident.status} (${status.incident.id}) on ${status.incident.originWorkerLabel}` : "none"}`,
-    ...status.workers.map(
-      (worker) => `Worker ${worker.workerLabel}: ${worker.configured ? "configured" : "configuring"}; head ${worker.localHead ?? "(none)"}; pending checkouts ${worker.pendingCheckouts.length}`
-    )
+    ...status.workers.flatMap((worker) => [
+      `Worker ${worker.workerLabel}: ${worker.configured ? "configured" : "configuring"}; head ${worker.localHead ?? "(none)"}; pending checkouts ${worker.pendingCheckouts.length}`,
+      ...renderMissingCheckouts(worker.workerLabel, worker.missingCheckouts ?? [])
+    ])
   ];
+  if (status.latestSync?.missingCheckouts?.length && !status.workers.some((worker) => worker.missingCheckouts?.length)) {
+    lines.push(...renderMissingCheckouts(status.latestSync.workerLabel, status.latestSync.missingCheckouts));
+  }
+  return `${lines.join("\n")}
+`;
+}
+const CHECKOUT_RECOVERY_HINT = "delete the branch with `r5dctl -p <project> delete branch <branch> --confirm`, or reconnect the worker to recreate the checkout";
+function renderMissingCheckouts(workerLabel, missingCheckouts) {
+  if (missingCheckouts.length === 0) return [];
+  return [
+    `Missing checkouts on ${workerLabel}: ${missingCheckouts.map((checkout) => `${checkout.projectId}/${checkout.branchName} (${checkout.reason})`).join(", ")}`,
+    `  Workspace sync skips these branches; ${CHECKOUT_RECOVERY_HINT}.`
+  ];
+}
+function renderBranchList(branches) {
+  if (branches.length === 0) return "No branches found.\n";
+  const lines = branches.map((branch) => {
+    const checkout = branch.checkoutState ? `  checkout=${branch.checkoutState}${branch.checkoutStateWorkerLabel ? ` on ${branch.checkoutStateWorkerLabel}` : ""}` : "";
+    return `${branch.branchName}  sessions=${branch.sessionCount}${checkout}`;
+  });
+  if (branches.some((branch) => branch.checkoutState)) {
+    lines.push(`Workspace sync skips a branch whose checkout is missing or not a worktree; ${CHECKOUT_RECOVERY_HINT}.`);
+  }
   return `${lines.join("\n")}
 `;
 }
@@ -2660,11 +2806,7 @@ async function executeR5dctlCommand(client, json, args) {
   if (first === "projects" && second === "branches" && third === "list" || first === "get" && second === "branches") {
     const projectRef = requireValue(first === "get" ? args[2] : args[3], "Missing project reference");
     const branches = await client.projects.branches.list(projectRef);
-    write(
-      branches,
-      branches.length === 0 ? "No branches found.\n" : `${branches.map((branch) => `${branch.branchName}  sessions=${branch.sessionCount}`).join("\n")}
-`
-    );
+    write(branches, renderBranchList(branches));
     return;
   }
   if (first === "projects" && second === "branches" && third === "describe" || first === "describe" && second === "branch") {
@@ -2679,6 +2821,40 @@ Sessions: ${result.sessions.length}
 `);
     return;
   }
+  if (first === "projects" && second === "branches" && third === "create" || first === "create" && second === "branch") {
+    const offset = first === "create" ? 2 : 3;
+    const projectRef = requireValue(args[offset], "Missing project reference");
+    const branchName = requireValue(args[offset + 1], "Missing branch name");
+    const operation = await createBranchThroughPlatform(client, projectRef, {
+      branchName,
+      ...parseBranchCreateArgs(args.slice(offset + 2))
+    });
+    write(operation, renderBranchOperation(operation, projectRef));
+    return;
+  }
+  if (first === "projects" && second === "branches" && third === "operation" || first === "describe" && second === "branch-operation") {
+    const offset = first === "describe" ? 2 : 3;
+    const projectRef = requireValue(args[offset], "Missing project reference");
+    const operationId = requireValue(args[offset + 1], "Missing operation id");
+    const operation = await requireServerRouteSupport(
+      "describe branch-operation",
+      () => client.projects.branches.describeOperation(projectRef, operationId)
+    );
+    write(operation, renderBranchOperation(operation, projectRef));
+    return;
+  }
+  if (first === "projects" && second === "branches" && third === "delete" || first === "delete" && second === "branch") {
+    const offset = first === "delete" ? 2 : 3;
+    const projectRef = requireValue(args[offset], "Missing project reference");
+    const branchName = requireValue(args[offset + 1], "Missing branch name");
+    const deletion = await deleteBranchThroughPlatform(client, projectRef, branchName, parseBranchDeleteArgs(args.slice(offset + 2)));
+    if (deletion.kind === "preview") {
+      write({ ...deletion.branch, confirmed: false }, renderBranchDeletionPreview(deletion.branch));
+      throw new Error(branchDeletionConfirmationMessage(deletion.branch));
+    }
+    write(deletion.result, renderBranchDeletion(deletion.result));
+    return;
+  }
   if (first === "get" && second === "envs") {
     const projectRef = requireValue(args[2], "Missing project reference");
     const options = parseGetEnvsArgs(args.slice(3));
@@ -3095,6 +3271,19 @@ function resolveCommandExecution(options, rest) {
         pluginArgs: ["describe", "branch", options.project, branch]
       };
     }
+    if (target === "branch-operation") {
+      if (!options.project) {
+        throw new Error("--project/-p is required for `describe branch-operation`");
+      }
+      const operationId = requireValue(commandArgs[1], "Operation id is required for `describe branch-operation`");
+      if (commandArgs.length > 2) {
+        throw new Error(`Unexpected describe branch-operation argument: ${commandArgs[2]}`);
+      }
+      return {
+        kind: "plugin",
+        pluginArgs: ["describe", "branch-operation", options.project, operationId]
+      };
+    }
     if (target === "session") {
       const sessionId = commandArgs[1] ?? options.session;
       if (!sessionId) {
@@ -3127,6 +3316,23 @@ function resolveCommandExecution(options, rest) {
         pluginArgs: ["create", "session", projectRef, branch, ...flagArgs]
       };
     }
+    if (target === "branch") {
+      if (!options.project) {
+        throw new Error("--project/-p is required for `create branch`");
+      }
+      const rawArgs = commandArgs.slice(1);
+      const positionalBranch = rawArgs[0] && !rawArgs[0].startsWith("-") ? rawArgs[0] : void 0;
+      const branch = positionalBranch ?? options.branch;
+      if (!branch) {
+        throw new Error("Branch name is required for `create branch`");
+      }
+      const flagArgs = positionalBranch ? rawArgs.slice(1) : rawArgs;
+      parseBranchCreateArgs(flagArgs);
+      return {
+        kind: "plugin",
+        pluginArgs: ["create", "branch", options.project, branch, ...flagArgs]
+      };
+    }
     throw new Error("Unknown create command");
   }
   if (command === "update") {
@@ -3177,6 +3383,23 @@ function resolveCommandExecution(options, rest) {
         pluginArgs: ["delete", "session", sessionId]
       };
     }
+    if (target === "branch") {
+      if (!options.project) {
+        throw new Error("--project/-p is required for `delete branch`");
+      }
+      const rawArgs = commandArgs.slice(1);
+      const positionalBranch = rawArgs[0] && !rawArgs[0].startsWith("-") ? rawArgs[0] : void 0;
+      const branch = positionalBranch ?? options.branch;
+      if (!branch) {
+        throw new Error("Branch name is required for `delete branch`");
+      }
+      const flagArgs = positionalBranch ? rawArgs.slice(1) : rawArgs;
+      parseBranchDeleteArgs(flagArgs);
+      return {
+        kind: "plugin",
+        pluginArgs: ["delete", "branch", options.project, branch, ...flagArgs]
+      };
+    }
     throw new Error("Unknown delete command");
   }
   if (command === "conversation") {
@@ -3404,7 +3627,10 @@ async function main(argv = process.argv.slice(2)) {
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   advanceTransientDevicePollBackoff,
+  branchDeletionConfirmationMessage,
   collectK8sUsage,
+  createBranchThroughPlatform,
+  deleteBranchThroughPlatform,
   dispatchSessionRunCommand,
   followR5dctlSession,
   formatK8sCpu,
@@ -3416,10 +3642,13 @@ async function main(argv = process.argv.slice(2)) {
   getR5dctlVersion,
   getTransientDevicePollDelay,
   handleAuthLogin,
+  isUnsupportedServerRoute,
   main,
   parseAnswerEnvRequestCommandArgs,
   parseAnswerFlags,
   parseAnswerQuestionsCommandArgs,
+  parseBranchCreateArgs,
+  parseBranchDeleteArgs,
   parseConversationForkArgs,
   parseConversationInspectWorkArgs,
   parseConversationOverviewArgs,
@@ -3437,6 +3666,10 @@ async function main(argv = process.argv.slice(2)) {
   parseSetEnvArgs,
   parseShellArgs,
   readDotenvFile,
+  renderBranchDeletion,
+  renderBranchDeletionPreview,
+  renderBranchList,
+  renderBranchOperation,
   renderConversationForkResponse,
   renderConversationHeadResponse,
   renderConversationNodeResponse,

package/dist/cjs/package.json

@@ -1,5 +1,5 @@
 {
   "name": "@ricsam/r5dctl",
-  "version": "0.0.103",
+  "version": "0.0.104",
   "type": "commonjs"
 }

package/dist/mjs/cli.mjs

@@ -114,6 +114,21 @@ const SHARED_HELP_ENTRIES = [
   { section: "projects", usage: "delete project <namespace/name|id>", description: "Delete a project." },
   { section: "branches", usage: "-p <project> get branches", description: "List branches for a project." },
   { section: "branches", usage: "-p <project> describe branch <branch>", description: "Show branch URLs and sessions." },
+  {
+    section: "branches",
+    usage: "-p <project> create branch <branch> --source worktree:<branch> [--working-tree <carry|clean>] [--worker <label>]",
+    description: "Create a linked worktree branch from an existing branch's checkout and print the operation id to poll."
+  },
+  {
+    section: "branches",
+    usage: "-p <project> describe branch-operation <operation-id>",
+    description: "Show whether a branch creation is provisioning, ready, or failed."
+  },
+  {
+    section: "branches",
+    usage: "-p <project> delete branch <branch> [--confirm]",
+    description: "Delete a branch and its sessions through the platform; without --confirm, only preview what would be deleted."
+  },
   {
     section: "envs",
     usage: "-p <project> get envs [--show-values]",
@@ -460,8 +475,8 @@ function parseCommandOperands(args, valueFlags, booleanFlags = /* @__PURE__ */ n
 function requireWorker(values) {
   return requireValue(values.get("--worker")?.trim(), "--worker <label> is required");
 }
-function parseWorktreeSource(rawValue) {
-  const raw = requireValue(rawValue?.trim(), "--source worktree:<branch> is required with --new-worktree");
+function parseWorktreeSource(rawValue, requiredMessage = "--source worktree:<branch> is required with --new-worktree") {
+  const raw = requireValue(rawValue?.trim(), requiredMessage);
   const separator = raw.indexOf(":");
   const type = raw.slice(0, separator);
   const branchName = raw.slice(separator + 1).trim();
@@ -488,6 +503,103 @@ function requireSessionMode(value) {
   }
   return mode;
 }
+function parseBranchCreateArgs(args) {
+  const parsed = parseCommandOperands(args, /* @__PURE__ */ new Set(["--source", "--working-tree", "--worker"]), /* @__PURE__ */ new Map(), "create branch", 1);
+  if (parsed.positionals.length > 0) throw new Error(`Unexpected create branch argument: ${parsed.positionals[0]}`);
+  const worker = parsed.values.get("--worker")?.trim();
+  if (parsed.values.has("--worker") && !worker) throw new Error("Missing value for --worker");
+  return {
+    source: parseWorktreeSource(parsed.values.get("--source"), "--source worktree:<branch> is required for `create branch`"),
+    workingTree: parseWorkingTreeMode(parsed.values.get("--working-tree")),
+    ...worker ? { worker } : {}
+  };
+}
+function parseBranchDeleteArgs(args) {
+  let confirmed = false;
+  for (const arg of args) {
+    if (arg === "--confirm") {
+      confirmed = true;
+      continue;
+    }
+    throw new Error(arg.startsWith("-") ? `Unknown delete branch flag: ${arg}` : `Unexpected delete branch argument: ${arg}`);
+  }
+  return { confirmed };
+}
+const PRIMARY_BRANCH_NAME = "main";
+function isUnsupportedServerRoute(error) {
+  return error instanceof R5dctlApiError && error.status === 404 && extractApiErrorMessage(error) === "Not Found";
+}
+async function requireServerRouteSupport(command, request) {
+  try {
+    return await request();
+  } catch (error) {
+    if (isUnsupportedServerRoute(error)) {
+      throw new Error(`This r5d server does not support \`${command}\` yet. Update the server, or manage the branch from the web sidebar.`);
+    }
+    throw error;
+  }
+}
+async function createBranchThroughPlatform(client, projectRef, input) {
+  return await requireServerRouteSupport(
+    "create branch",
+    () => client.projects.branches.create(projectRef, {
+      requestId: randomUUID(),
+      branchName: input.branchName,
+      source: input.source,
+      workingTree: input.workingTree,
+      ...input.worker ? { worker: input.worker } : {}
+    })
+  );
+}
+async function deleteBranchThroughPlatform(client, projectRef, branchName, options) {
+  if (branchName === PRIMARY_BRANCH_NAME) throw new Error(`The primary branch ${branchName} cannot be deleted`);
+  const branch = await client.projects.branches.describe(projectRef, branchName);
+  if (!options.confirmed) return { kind: "preview", branch };
+  const result = await requireServerRouteSupport("delete branch", () => client.projects.branches.delete(projectRef, branchName));
+  return { kind: "deleted", result };
+}
+function renderBranchDeletionPreview(branch) {
+  const count = branch.sessions.length;
+  const lines = [
+    `Project: ${branch.project.path}`,
+    `Branch: ${branch.branchName}`,
+    `Sessions: ${count}`,
+    ...branch.sessions.map((session) => `  ${session.id}  ${session.name ?? "(unnamed)"}`),
+    `Deleting this branch removes its checkout from every connected worker and deletes the ${count} session(s) above.`
+  ];
+  return `${lines.join("\n")}
+`;
+}
+function branchDeletionConfirmationMessage(branch) {
+  return `Nothing was deleted. Re-run with --confirm to delete branch ${branch.branchName} and its ${branch.sessions.length} session(s).`;
+}
+function renderBranchDeletion(result) {
+  const lines = [
+    `Deleted branch ${result.branchName} and ${result.deletedSessionIds.length} session(s).`,
+    ...result.deletedSessionIds.map((sessionId) => `  ${sessionId}`)
+  ];
+  return `${lines.join("\n")}
+`;
+}
+function renderBranchOperation(operation, projectRef) {
+  const lines = [
+    `Operation: ${operation.id}`,
+    `Branch: ${operation.branchName}`,
+    `Source: worktree:${operation.source.branchName}`,
+    `Working tree: ${operation.workingTree}`,
+    `Worker: ${operation.worker ?? "(pending)"}`,
+    `Status: ${operation.status}`
+  ];
+  if (operation.error) lines.push(`Error: ${operation.error}`);
+  if (operation.cleanupPending) lines.push("Cleanup: pending");
+  if (operation.status === "provisioning") {
+    lines.push(`Check: r5dctl -p ${projectRef} describe branch-operation ${operation.id}`);
+  } else if (operation.status === "ready") {
+    lines.push(`Branch state: ${formatBranchStateHint(operation.branchName)}`);
+  }
+  return `${lines.join("\n")}
+`;
+}
 function rejectSessionRunGlobalScopes(options, allowProject) {
   if (!allowProject && options.project) throw new Error("--project/-p is only supported for `session start`");
   if (options.branch) throw new Error("--branch/-b is not supported for `session`; select the worktree explicitly");
@@ -1394,10 +1506,34 @@ function renderWorkspaceStatus(status) {
     `Workspace HEAD: ${status.head ?? "(not initialized)"}`,
     `Latest sync: ${status.latestSync ? `${status.latestSync.outcome} on ${status.latestSync.workerLabel}` : "(none)"}`,
     `Remediation: ${status.incident ? `${status.incident.kind} ${status.incident.status} (${status.incident.id}) on ${status.incident.originWorkerLabel}` : "none"}`,
-    ...status.workers.map(
-      (worker) => `Worker ${worker.workerLabel}: ${worker.configured ? "configured" : "configuring"}; head ${worker.localHead ?? "(none)"}; pending checkouts ${worker.pendingCheckouts.length}`
-    )
+    ...status.workers.flatMap((worker) => [
+      `Worker ${worker.workerLabel}: ${worker.configured ? "configured" : "configuring"}; head ${worker.localHead ?? "(none)"}; pending checkouts ${worker.pendingCheckouts.length}`,
+      ...renderMissingCheckouts(worker.workerLabel, worker.missingCheckouts ?? [])
+    ])
   ];
+  if (status.latestSync?.missingCheckouts?.length && !status.workers.some((worker) => worker.missingCheckouts?.length)) {
+    lines.push(...renderMissingCheckouts(status.latestSync.workerLabel, status.latestSync.missingCheckouts));
+  }
+  return `${lines.join("\n")}
+`;
+}
+const CHECKOUT_RECOVERY_HINT = "delete the branch with `r5dctl -p <project> delete branch <branch> --confirm`, or reconnect the worker to recreate the checkout";
+function renderMissingCheckouts(workerLabel, missingCheckouts) {
+  if (missingCheckouts.length === 0) return [];
+  return [
+    `Missing checkouts on ${workerLabel}: ${missingCheckouts.map((checkout) => `${checkout.projectId}/${checkout.branchName} (${checkout.reason})`).join(", ")}`,
+    `  Workspace sync skips these branches; ${CHECKOUT_RECOVERY_HINT}.`
+  ];
+}
+function renderBranchList(branches) {
+  if (branches.length === 0) return "No branches found.\n";
+  const lines = branches.map((branch) => {
+    const checkout = branch.checkoutState ? `  checkout=${branch.checkoutState}${branch.checkoutStateWorkerLabel ? ` on ${branch.checkoutStateWorkerLabel}` : ""}` : "";
+    return `${branch.branchName}  sessions=${branch.sessionCount}${checkout}`;
+  });
+  if (branches.some((branch) => branch.checkoutState)) {
+    lines.push(`Workspace sync skips a branch whose checkout is missing or not a worktree; ${CHECKOUT_RECOVERY_HINT}.`);
+  }
   return `${lines.join("\n")}
 `;
 }
@@ -2575,11 +2711,7 @@ async function executeR5dctlCommand(client, json, args) {
   if (first === "projects" && second === "branches" && third === "list" || first === "get" && second === "branches") {
     const projectRef = requireValue(first === "get" ? args[2] : args[3], "Missing project reference");
     const branches = await client.projects.branches.list(projectRef);
-    write(
-      branches,
-      branches.length === 0 ? "No branches found.\n" : `${branches.map((branch) => `${branch.branchName}  sessions=${branch.sessionCount}`).join("\n")}
-`
-    );
+    write(branches, renderBranchList(branches));
     return;
   }
   if (first === "projects" && second === "branches" && third === "describe" || first === "describe" && second === "branch") {
@@ -2594,6 +2726,40 @@ Sessions: ${result.sessions.length}
 `);
     return;
   }
+  if (first === "projects" && second === "branches" && third === "create" || first === "create" && second === "branch") {
+    const offset = first === "create" ? 2 : 3;
+    const projectRef = requireValue(args[offset], "Missing project reference");
+    const branchName = requireValue(args[offset + 1], "Missing branch name");
+    const operation = await createBranchThroughPlatform(client, projectRef, {
+      branchName,
+      ...parseBranchCreateArgs(args.slice(offset + 2))
+    });
+    write(operation, renderBranchOperation(operation, projectRef));
+    return;
+  }
+  if (first === "projects" && second === "branches" && third === "operation" || first === "describe" && second === "branch-operation") {
+    const offset = first === "describe" ? 2 : 3;
+    const projectRef = requireValue(args[offset], "Missing project reference");
+    const operationId = requireValue(args[offset + 1], "Missing operation id");
+    const operation = await requireServerRouteSupport(
+      "describe branch-operation",
+      () => client.projects.branches.describeOperation(projectRef, operationId)
+    );
+    write(operation, renderBranchOperation(operation, projectRef));
+    return;
+  }
+  if (first === "projects" && second === "branches" && third === "delete" || first === "delete" && second === "branch") {
+    const offset = first === "delete" ? 2 : 3;
+    const projectRef = requireValue(args[offset], "Missing project reference");
+    const branchName = requireValue(args[offset + 1], "Missing branch name");
+    const deletion = await deleteBranchThroughPlatform(client, projectRef, branchName, parseBranchDeleteArgs(args.slice(offset + 2)));
+    if (deletion.kind === "preview") {
+      write({ ...deletion.branch, confirmed: false }, renderBranchDeletionPreview(deletion.branch));
+      throw new Error(branchDeletionConfirmationMessage(deletion.branch));
+    }
+    write(deletion.result, renderBranchDeletion(deletion.result));
+    return;
+  }
   if (first === "get" && second === "envs") {
     const projectRef = requireValue(args[2], "Missing project reference");
     const options = parseGetEnvsArgs(args.slice(3));
@@ -3010,6 +3176,19 @@ function resolveCommandExecution(options, rest) {
         pluginArgs: ["describe", "branch", options.project, branch]
       };
     }
+    if (target === "branch-operation") {
+      if (!options.project) {
+        throw new Error("--project/-p is required for `describe branch-operation`");
+      }
+      const operationId = requireValue(commandArgs[1], "Operation id is required for `describe branch-operation`");
+      if (commandArgs.length > 2) {
+        throw new Error(`Unexpected describe branch-operation argument: ${commandArgs[2]}`);
+      }
+      return {
+        kind: "plugin",
+        pluginArgs: ["describe", "branch-operation", options.project, operationId]
+      };
+    }
     if (target === "session") {
       const sessionId = commandArgs[1] ?? options.session;
       if (!sessionId) {
@@ -3042,6 +3221,23 @@ function resolveCommandExecution(options, rest) {
         pluginArgs: ["create", "session", projectRef, branch, ...flagArgs]
       };
     }
+    if (target === "branch") {
+      if (!options.project) {
+        throw new Error("--project/-p is required for `create branch`");
+      }
+      const rawArgs = commandArgs.slice(1);
+      const positionalBranch = rawArgs[0] && !rawArgs[0].startsWith("-") ? rawArgs[0] : void 0;
+      const branch = positionalBranch ?? options.branch;
+      if (!branch) {
+        throw new Error("Branch name is required for `create branch`");
+      }
+      const flagArgs = positionalBranch ? rawArgs.slice(1) : rawArgs;
+      parseBranchCreateArgs(flagArgs);
+      return {
+        kind: "plugin",
+        pluginArgs: ["create", "branch", options.project, branch, ...flagArgs]
+      };
+    }
     throw new Error("Unknown create command");
   }
   if (command === "update") {
@@ -3092,6 +3288,23 @@ function resolveCommandExecution(options, rest) {
         pluginArgs: ["delete", "session", sessionId]
       };
     }
+    if (target === "branch") {
+      if (!options.project) {
+        throw new Error("--project/-p is required for `delete branch`");
+      }
+      const rawArgs = commandArgs.slice(1);
+      const positionalBranch = rawArgs[0] && !rawArgs[0].startsWith("-") ? rawArgs[0] : void 0;
+      const branch = positionalBranch ?? options.branch;
+      if (!branch) {
+        throw new Error("Branch name is required for `delete branch`");
+      }
+      const flagArgs = positionalBranch ? rawArgs.slice(1) : rawArgs;
+      parseBranchDeleteArgs(flagArgs);
+      return {
+        kind: "plugin",
+        pluginArgs: ["delete", "branch", options.project, branch, ...flagArgs]
+      };
+    }
     throw new Error("Unknown delete command");
   }
   if (command === "conversation") {
@@ -3318,7 +3531,10 @@ async function main(argv = process.argv.slice(2)) {
 }
 export {
   advanceTransientDevicePollBackoff,
+  branchDeletionConfirmationMessage,
   collectK8sUsage,
+  createBranchThroughPlatform,
+  deleteBranchThroughPlatform,
   dispatchSessionRunCommand,
   followR5dctlSession,
   formatK8sCpu,
@@ -3330,10 +3546,13 @@ export {
   getR5dctlVersion,
   getTransientDevicePollDelay,
   handleAuthLogin,
+  isUnsupportedServerRoute,
   main,
   parseAnswerEnvRequestCommandArgs,
   parseAnswerFlags,
   parseAnswerQuestionsCommandArgs,
+  parseBranchCreateArgs,
+  parseBranchDeleteArgs,
   parseConversationForkArgs,
   parseConversationInspectWorkArgs,
   parseConversationOverviewArgs,
@@ -3351,6 +3570,10 @@ export {
   parseSetEnvArgs,
   parseShellArgs,
   readDotenvFile,
+  renderBranchDeletion,
+  renderBranchDeletionPreview,
+  renderBranchList,
+  renderBranchOperation,
   renderConversationForkResponse,
   renderConversationHeadResponse,
   renderConversationNodeResponse,

package/dist/mjs/package.json

@@ -1,5 +1,5 @@
 {
   "name": "@ricsam/r5dctl",
-  "version": "0.0.103",
+  "version": "0.0.104",
   "type": "module"
 }

package/dist/types/cli.d.ts

@@ -1,4 +1,4 @@
-import { R5dctlClient, type R5dctlConversationForkResponse, type R5dctlConversationHeadResponse, type R5dctlConversationRenderOptions, type R5dctlConversationResponse, type R5dctlConversationNodeResponse, type R5dctlConversationOverviewResponse, type R5dctlConversationWorkDetail, type R5dctlConversationWorkResponse, type R5dctlEnvData, type R5dctlK8sResourceHistory, type R5dctlK8sUsage, type R5dctlK8sWorkload, type R5dctlProcessInspection, type R5dctlProcessListInput, type R5dctlProcessLog, type R5dctlProcessRun, type R5dctlSessionEvent, type R5dctlSessionStartInput, type R5dctlWorkspaceStatus, type R5dctlWorkspaceSyncResult, type R5dctlWorkingTreeMode, type R5dctlWorktreeSource, type R5dctlSessionMode, type ChatMode, type ModelTier } from "@ricsam/r5d-api";
+import { R5dctlApiError, R5dctlClient, type R5dctlConversationForkResponse, type R5dctlConversationHeadResponse, type R5dctlConversationRenderOptions, type R5dctlConversationResponse, type R5dctlConversationNodeResponse, type R5dctlConversationOverviewResponse, type R5dctlConversationWorkDetail, type R5dctlConversationWorkResponse, type R5dctlEnvData, type R5dctlK8sResourceHistory, type R5dctlK8sUsage, type R5dctlK8sWorkload, type R5dctlProcessInspection, type R5dctlProcessListInput, type R5dctlProcessLog, type R5dctlProcessRun, type R5dctlBranch, type R5dctlBranchDeleteResponse, type R5dctlBranchDescription, type R5dctlBranchOperation, type R5dctlSessionEvent, type R5dctlSessionStartInput, type R5dctlWorkspaceStatus, type R5dctlWorkspaceSyncResult, type R5dctlWorkingTreeMode, type R5dctlWorktreeSource, type R5dctlSessionMode, type ChatMode, type ModelTier } from "@ricsam/r5d-api";
 export type GlobalOptions = {
     baseUrl?: string;
     json: boolean;
@@ -79,6 +79,35 @@ export type R5dctlSessionRunCommand = R5dctlSessionStartCommand | {
     kind: "stop";
     sessionId: string;
 };
+export type R5dctlBranchCreateArgs = {
+    source: R5dctlWorktreeSource;
+    workingTree: R5dctlWorkingTreeMode;
+    worker?: string;
+};
+export declare function parseBranchCreateArgs(args: string[]): R5dctlBranchCreateArgs;
+export declare function parseBranchDeleteArgs(args: string[]): {
+    confirmed: boolean;
+};
+/** An older server strips unknown routes and answers with this generic 404; a route's own not-found carries a specific message. */
+export declare function isUnsupportedServerRoute(error: unknown): error is R5dctlApiError;
+export declare function createBranchThroughPlatform(client: R5dctlClient, projectRef: string, input: {
+    branchName: string;
+} & R5dctlBranchCreateArgs): Promise<R5dctlBranchOperation>;
+export type R5dctlBranchDeletionOutcome = {
+    kind: "preview";
+    branch: R5dctlBranchDescription;
+} | {
+    kind: "deleted";
+    result: R5dctlBranchDeleteResponse;
+};
+export declare function deleteBranchThroughPlatform(client: R5dctlClient, projectRef: string, branchName: string, options: {
+    confirmed: boolean;
+}): Promise<R5dctlBranchDeletionOutcome>;
+export declare function renderBranchDeletionPreview(branch: R5dctlBranchDescription): string;
+export declare function branchDeletionConfirmationMessage(branch: R5dctlBranchDescription): string;
+export declare function renderBranchDeletion(result: R5dctlBranchDeleteResponse): string;
+/** Operation facts only: no commit hash, because a hash is stale as soon as the branch commits. */
+export declare function renderBranchOperation(operation: R5dctlBranchOperation, projectRef: string): string;
 export declare function parseSessionRunCommand(options: Pick<GlobalOptions, "project" | "branch" | "session">, args: string[]): R5dctlSessionRunCommand;
 export type R5dctlSessionProcessLogArgs = {
     runId: string;
@@ -146,6 +175,7 @@ export declare function advanceTransientDevicePollBackoff(intervalMs: number, tr
 };
 export declare function handleAuthLogin(client: R5dctlClient, options: GlobalOptions, commandArgs: string[], config: R5dctlConfig): Promise<void>;
 export declare function renderWorkspaceStatus(status: R5dctlWorkspaceStatus): string;
+export declare function renderBranchList(branches: R5dctlBranch[]): string;
 export declare function renderWorkspaceSync(result: R5dctlWorkspaceSyncResult): string;
 export type K8sUsageSummary = {
     cpuMinNanoCores: number | null;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ricsam/r5dctl",
-  "version": "0.0.103",
+  "version": "0.0.104",
   "type": "module",
   "main": "./dist/cjs/cli.cjs",
   "module": "./dist/mjs/cli.mjs",
@@ -26,7 +26,7 @@
     "r5dctl": "dist/cjs/main.cjs"
   },
   "dependencies": {
-    "@ricsam/r5d-api": "^0.0.103",
+    "@ricsam/r5d-api": "^0.0.104",
     "dotenv": "^17",
     "qrcode": "^1.5.4",
     "ws": "^8.18.3"