@ricsam/r5dctl 0.0.72 → 0.0.74

package/README.md

@@ -93,6 +93,8 @@ r5dctl session stop <session-id>
 r5dctl -p <project> merge fix/tests
 r5dctl -p <project> merge --worker <label> --create-conflict-worktree fix/tests
 r5dctl -p <project> merge --worker <label> --launch-conflict-resolution-agent fix/tests
+r5dctl -p <project> merge --worker <label> --launch-conflict-resolution-agent --no-wait fix/tests
+r5dctl -p <project> merge status <attempt-id>
 r5dctl -p <project> merge finish --worker <label> conflicts/fix-tests --summary "Resolved the conflicts"
 
 r5dctl -p <project> -b <branch> shell
@@ -107,14 +109,28 @@ r5dctl k8s usage
 r5dctl k8s usage --namespace default --workload api --container server
 r5dctl k8s usage --window 7d
 r5dctl k8s usage --workload default/api --window 7d --json
+r5dctl vcluster trusted-workflow add --repo owner/repository --workflow .github/workflows/deploy.yml
+r5dctl vcluster trusted-workflow list
+r5dctl vcluster trusted-workflow remove <workflow-id>
 ```
 
+Trusted workflows authenticate Kubernetes through the dedicated
+`ricsam/r5d-cluster-auth` GitHub Action. They do not run or authenticate
+`r5dctl` inside GitHub Actions, and no R5D secret needs to be stored in the
+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.
+
 `session start` creates an ordinary agent-mode chat on an explicitly selected existing worktree, or creates a named worktree from an explicit `worktree:<branch>` source. It requires project, worker, model, and prompt and never infers them from the current shell. Starts and prompts return after durable enqueue while execution continues asynchronously. 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 publication finishes asynchronously behind the response, and `merge` republishes at its own boundary before reading the worktree.
 
 Add `-f`/`--follow`/`--watch` to `session start` to attach after enqueue, or to `conversation` to print the current transcript and follow new output. Assistant text is written to stdout and lifecycle/tool progress to stderr; `--tools` includes tool calls and results. With global `--json`, follow mode emits one JSON event per line. Ctrl-C only detaches and never stops the session. The CLI reconnects transiently interrupted event streams and resynchronizes committed conversation revisions without repeating assistant text.
 
 `merge` merges a managed source worktree into its recorded parent. By default conflicts are reported without creating more work. `--create-conflict-worktree` prepares a manual conflict worktree, while `--launch-conflict-resolution-agent` starts the dedicated merge-conflict resolver; those strategies are mutually exclusive. A worker-bound shell credential supplies its own worker automatically; otherwise pass `--worker`. Finish a reviewed manual resolution with `merge finish`.
 
+Merging is lockless and optimistic: nothing blocks agents from continuing to work on the involved branches. Every merge pins the branch tips it previewed and publishes through an atomic compare-and-swap, and a concurrent publication simply retries. When a resolver agent finishes after the target advanced, the platform automatically continues the merge — publishing directly if the refreshed merge is conflict-free, or launching a fresh resolver attempt (whose prompt references the superseded session's resolution) — repeating until one resolution publishes. Superseded attempts surface the follow-up attempt id in `merge status`. Only manual conflict worktrees stop at `stale`: re-run `merge` to start a fresh resolution.
+
+The server answers merge requests as soon as the result is durably recorded; the slow per-member workspace propagation always completes asynchronously behind the response. For a clean merge that means the merged commit is already published when the command returns. For a conflict strategy the server responds with the merge attempt in a `provisioning` state and prepares the conflict worktree (and starts the resolver agent) in the background; the CLI polls the attempt until the worktree is ready — and, for the agent strategy, until the resolver agent is running — before printing the final result. Pass `--no-wait` to skip the wait and get the attempt id immediately, and use `merge status <attempt-id>` at any time to re-check a provisioning, failed, or completed attempt (a provisioning failure surfaces there as a `failed` attempt with its reason). Ctrl-C during the wait only detaches the CLI; provisioning continues server-side.
+
 `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

@@ -42,6 +42,7 @@ __export(cli_exports, {
   getR5dctlVersion: () => getR5dctlVersion,
   getTransientDevicePollDelay: () => getTransientDevicePollDelay,
   handleAuthLogin: () => handleAuthLogin,
+  isMergeAttemptSettled: () => isMergeAttemptSettled,
   main: () => main,
   parseAnswerEnvRequestCommandArgs: () => parseAnswerEnvRequestCommandArgs,
   parseAnswerFlags: () => parseAnswerFlags,
@@ -96,16 +97,8 @@ var import_promises = require("node:timers/promises");
 var import_dotenv = require("dotenv");
 var import_r5d_api = require("@ricsam/r5d-api");
 var import_shell = require("./shell.cjs");
-const CHAT_MODES = /* @__PURE__ */ new Set([
-  "ask",
-  "plan",
-  "build",
-  "agent",
-  "security_review",
-  "large_diff_remediation",
-  "merge_conflict_resolution"
-]);
-const R5DCTL_SESSION_MODES = /* @__PURE__ */ new Set(["ask", "plan", "build", "agent"]);
+const CHAT_MODES = /* @__PURE__ */ new Set(["ask", "plan", "agent", "large_diff_remediation", "merge_conflict_resolution"]);
+const R5DCTL_SESSION_MODES = /* @__PURE__ */ new Set(["ask", "plan", "agent"]);
 const MODEL_TIERS = /* @__PURE__ */ new Set(["low", "medium", "high", "max"]);
 const R5DCTL_PACKAGE_NAME = "@ricsam/r5dctl";
 const CLI_GLOBAL_OPTION_HELP = [
@@ -156,6 +149,9 @@ const PS_HELP_TEXT = [
 const K8S_HELP_TEXT = [
   "Usage:",
   "  r5dctl k8s usage [--namespace <name>] [--workload <name|namespace/name|uid>] [--container <name>] [--window <24h|7d>]",
+  "  r5dctl vcluster trusted-workflow add --repo <owner/repository> --workflow <.github/workflows/file.yml>",
+  "  r5dctl vcluster trusted-workflow list",
+  "  r5dctl vcluster trusted-workflow remove <workflow-id>",
   "",
   "Show current and rolling CPU and memory usage for managed-vCluster workload containers.",
   ""
@@ -174,10 +170,12 @@ const SESSION_RUN_HELP_TEXT = [
 ].join("\n");
 const MERGE_HELP_TEXT = [
   "Usage:",
-  "  r5dctl -p <project> merge [--worker <label>] [--create-conflict-worktree|--launch-conflict-resolution-agent] <source-worktree>",
+  "  r5dctl -p <project> merge [--worker <label>] [--create-conflict-worktree|--launch-conflict-resolution-agent] [--no-wait] <source-worktree>",
+  "  r5dctl -p <project> merge status <attempt-id>",
   '  r5dctl -p <project> merge finish --worker <label> [--summary "<summary>"] <conflict-worktree>',
   "",
   "Merge a managed worktree into its recorded parent worktree.",
+  "Conflict worktrees provision in the background; merge waits by default and --no-wait returns the attempt immediately.",
   ""
 ].join("\n");
 const SHARED_HELP_ENTRIES = [
@@ -310,6 +308,17 @@ const SHARED_HELP_ENTRIES = [
     usage: "k8s usage [--namespace <name>] [--workload <name|namespace/name|uid>] [--container <name>] [--window <24h|7d>]",
     description: "Show current and rolling CPU and memory usage for managed-vCluster workload containers."
   },
+  {
+    section: "kubernetes",
+    usage: "vcluster trusted-workflow add --repo <owner/repository> --workflow <.github/workflows/file.yml>",
+    description: "Trust an exact GitHub Actions workflow path to authenticate kubectl against your managed vCluster."
+  },
+  { section: "kubernetes", usage: "vcluster trusted-workflow list", description: "List trusted GitHub Actions workflows." },
+  {
+    section: "kubernetes",
+    usage: "vcluster trusted-workflow remove <workflow-id>",
+    description: "Revoke a trusted GitHub Actions workflow and its outstanding credentials."
+  },
   {
     section: "processes",
     usage: "ps list [--worker <label>]",
@@ -328,9 +337,14 @@ const SHARED_HELP_ENTRIES = [
   { section: "processes", usage: "ps stop <run-id>", description: "Gracefully stop an active process with SIGTERM." },
   {
     section: "merge",
-    usage: "-p <project> merge [--worker <label>] [--create-conflict-worktree|--launch-conflict-resolution-agent] <source-worktree>",
+    usage: "-p <project> merge [--worker <label>] [--create-conflict-worktree|--launch-conflict-resolution-agent] [--no-wait] <source-worktree>",
     description: "Merge a worktree into its recorded parent, with an explicit conflict strategy."
   },
+  {
+    section: "merge",
+    usage: "-p <project> merge status <attempt-id>",
+    description: "Show a merge attempt's provisioning and resolution status."
+  },
   {
     section: "merge",
     usage: '-p <project> merge finish --worker <label> [--summary "<summary>"] <conflict-worktree>',
@@ -567,7 +581,7 @@ function requireModel(value) {
 function requireSessionMode(value) {
   const mode = requireValue(value?.trim(), "--mode <mode> is required");
   if (!R5DCTL_SESSION_MODES.has(mode)) {
-    throw new Error("Invalid --mode. Expected one of: ask, plan, build, agent");
+    throw new Error("Invalid --mode. Expected one of: ask, plan, agent");
   }
   return mode;
 }
@@ -653,12 +667,19 @@ function parseMergeCommand(options, args) {
       ...parsed2.values.get("--summary")?.trim() ? { summary: parsed2.values.get("--summary").trim() } : {}
     };
   }
+  if (args[0] === "status") {
+    const parsed2 = parseCommandOperands(args.slice(1), /* @__PURE__ */ new Set(), /* @__PURE__ */ new Map(), "merge status");
+    const attemptId = requireValue(parsed2.positionals[0], "Attempt id is required for `merge status`");
+    if (parsed2.positionals.length > 1) throw new Error(`Unexpected merge status argument: ${parsed2.positionals[1]}`);
+    return { kind: "status", project, attemptId };
+  }
   const parsed = parseCommandOperands(
     args,
     /* @__PURE__ */ new Set(["--worker"]),
     /* @__PURE__ */ new Map([
       ["--create-conflict-worktree", "--create-conflict-worktree"],
-      ["--launch-conflict-resolution-agent", "--launch-conflict-resolution-agent"]
+      ["--launch-conflict-resolution-agent", "--launch-conflict-resolution-agent"],
+      ["--no-wait", "--no-wait"]
     ]),
     "merge"
   );
@@ -671,7 +692,14 @@ function parseMergeCommand(options, args) {
   }
   const conflictMode = createWorktree ? "worktree" : launchAgent ? "agent" : "none";
   const worker = parsed.values.get("--worker")?.trim();
-  return { kind: "merge", project, sourceWorktree, conflictMode, ...worker ? { worker } : {} };
+  return {
+    kind: "merge",
+    project,
+    sourceWorktree,
+    conflictMode,
+    ...worker ? { worker } : {},
+    ...parsed.booleans.has("--no-wait") ? { noWait: true } : {}
+  };
 }
 function assertAuthLoginArgs(args) {
   const valueFlags = /* @__PURE__ */ new Set(["--device-name", "--worker-label"]);
@@ -1959,17 +1987,22 @@ function renderSessionRunStatus(session) {
 function renderWorktreeMerge(result, input) {
   const lines = [];
   appendMergeDetails(lines, result);
+  const status = responseString(result, "status");
   const conflictWorktree = responseString(result, "conflictWorktree");
   const resolverSessionId = responseString(result, "resolverSessionId");
+  const attemptId = responseString(result, "attemptId");
   const worker = responseString(result, "worker") ?? input.worker;
   if (resolverSessionId) lines.push("", `Resolver session: ${resolverSessionId}`, `  r5dctl session stop ${resolverSessionId}`);
-  if (conflictWorktree && worker && ["conflicts", "conflict_worktree_created", "resolving"].includes(responseString(result, "status") ?? "")) {
+  if (conflictWorktree && worker && ["conflicts", "conflict_worktree_created", "resolving"].includes(status ?? "")) {
     lines.push(
       "",
       "Finish after resolving and reviewing the conflict worktree:",
       `  r5dctl -p ${input.project} merge finish --worker ${worker} ${conflictWorktree} --summary "<summary>"`
     );
   }
+  if (attemptId && (status === "provisioning" || status === "resolving" && result.resolverAgentRunning === false)) {
+    lines.push("", "Check progress:", `  r5dctl -p ${input.project} merge status ${attemptId}`);
+  }
   return `${lines.join("\n")}
 `;
 }
@@ -2009,13 +2042,64 @@ async function dispatchSessionRunCommand(client, command) {
   const data = await client.sessions.stop(command.sessionId);
   return { data, human: renderSessionRunStatus(data) };
 }
-async function dispatchMergeCommand(client, command) {
+const MERGE_POLL_INTERVAL_MS = 2e3;
+const MERGE_POLL_TIMEOUT_MS = 20 * 6e4;
+const MERGE_POLL_MAX_CONSECUTIVE_FAILURES = 5;
+function isMergeAttemptSettled(response) {
+  const status = responseString(response, "status");
+  if (!status) return true;
+  if (status === "resolving") return response.resolverAgentRunning !== false;
+  return status !== "provisioning";
+}
+async function pollMergeAttemptUntilSettled(client, project, attemptId, initial, options) {
+  const intervalMs = options.pollIntervalMs ?? MERGE_POLL_INTERVAL_MS;
+  const timeoutMs = options.pollTimeoutMs ?? MERGE_POLL_TIMEOUT_MS;
+  const sleep2 = options.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+  const onProgress = options.onProgress ?? (() => {
+  });
+  let latest = initial;
+  let worktreeReadyReported = latest.worktreeReady === true;
+  let consecutiveFailures = 0;
+  let waitedMs = 0;
+  while (!isMergeAttemptSettled(latest)) {
+    if (waitedMs >= timeoutMs) {
+      onProgress(`Still waiting after ${Math.round(timeoutMs / 6e4)} minutes; check later with: r5dctl -p ${project} merge status ${attemptId}`);
+      return latest;
+    }
+    await sleep2(intervalMs);
+    waitedMs += intervalMs;
+    try {
+      latest = await client.projects.worktrees.mergeAttempt(project, attemptId);
+      consecutiveFailures = 0;
+    } catch (error) {
+      consecutiveFailures += 1;
+      if (consecutiveFailures >= MERGE_POLL_MAX_CONSECUTIVE_FAILURES) throw error;
+      continue;
+    }
+    if (!worktreeReadyReported && latest.worktreeReady === true) {
+      worktreeReadyReported = true;
+      onProgress("Conflict worktree ready.");
+    }
+  }
+  return latest;
+}
+async function dispatchMergeCommand(client, command, pollOptions = {}) {
   if (command.kind === "merge") {
     const data2 = await client.projects.worktrees.merge(command.project, command.sourceWorktree, {
       conflictMode: command.conflictMode,
       ...command.worker ? { worker: command.worker } : {}
     });
-    return { data: data2, human: renderWorktreeMerge(data2, command) };
+    const attemptId = responseString(data2, "attemptId");
+    if (command.noWait || !attemptId || isMergeAttemptSettled(data2)) {
+      return { data: data2, human: renderWorktreeMerge(data2, command) };
+    }
+    pollOptions.onProgress?.(`Provisioning the conflict worktree (attempt ${attemptId})...`);
+    const settled = await pollMergeAttemptUntilSettled(client, command.project, attemptId, data2, pollOptions);
+    return { data: settled, human: renderWorktreeMerge(settled, command) };
+  }
+  if (command.kind === "status") {
+    const data2 = await client.projects.worktrees.mergeAttempt(command.project, command.attemptId);
+    return { data: data2, human: renderWorktreeMerge(data2, { project: command.project }) };
   }
   const data = await client.projects.worktrees.finishMerge(command.project, command.conflictWorktree, {
     worker: command.worker,
@@ -2572,6 +2656,40 @@ async function executeR5dctlCommand(client, json, args) {
     write(report, renderK8sUsageReport(report));
     return;
   }
+  if (first === "vcluster" && second === "trusted-workflow") {
+    const subcommand = requireValue(args[2], "Missing trusted-workflow command");
+    if (subcommand === "add") {
+      const parsed = parseCommandOperands(args.slice(3), /* @__PURE__ */ new Set(["--repo", "--workflow"]), /* @__PURE__ */ new Map(), "trusted-workflow add");
+      if (parsed.positionals.length > 0) throw new Error(`Unexpected trusted-workflow add value: ${parsed.positionals[0]}`);
+      const workflow = await client.k8s.trustedWorkflows.add({
+        repository: requireValue(parsed.values.get("--repo"), "--repo <owner/repository> is required"),
+        workflowPath: requireValue(parsed.values.get("--workflow"), "--workflow <path> is required")
+      });
+      write(workflow, "Trusted GitHub workflow configured successfully.\n");
+      return;
+    }
+    if (subcommand === "list") {
+      if (args.length > 3) throw new Error(`Unexpected trusted-workflow list value: ${args[3]}`);
+      const workflows = await client.k8s.trustedWorkflows.list();
+      write(
+        workflows,
+        workflows.length === 0 ? "No trusted GitHub workflows.\n" : `${workflows.map(
+          (workflow) => `${workflow.id}  ${workflow.repository}  ${workflow.workflowPath}  ${workflow.revokedAt ? "revoked" : "active"}`
+        ).join("\n")}
+`
+      );
+      return;
+    }
+    if (subcommand === "remove") {
+      const workflowId = requireValue(args[3], "Missing trusted workflow id");
+      if (args.length > 4) throw new Error(`Unexpected trusted-workflow remove value: ${args[4]}`);
+      const result = await client.k8s.trustedWorkflows.revoke(workflowId);
+      if (!result.success) throw new Error("Trusted GitHub workflow was not found or was already revoked");
+      write(result, "Trusted GitHub workflow revoked.\n");
+      return;
+    }
+    throw new Error(`Unknown trusted-workflow command: ${subcommand}`);
+  }
   if (first === "ps" && second === "list") {
     const processes = await client.processes.list(parsePsListArgs(args.slice(2)));
     write(processes, renderProcessList(processes));
@@ -2941,12 +3059,23 @@ function resolveCommandExecution(options, rest) {
   }
   if (command === "k8s") {
     const subcommand = commandArgs[0];
-    if (subcommand !== "usage") throw new Error(`Unknown k8s command: ${subcommand ?? ""}`.trim());
     if (options.project || options.branch || options.session) {
-      throw new Error("Project, branch, and session scopes are not supported for `k8s usage`");
+      throw new Error("Project, branch, and session scopes are not supported for `k8s`");
+    }
+    if (subcommand === "usage") {
+      parseK8sUsageArgs(commandArgs.slice(1));
+      return { kind: "plugin", pluginArgs: ["k8s", "usage", ...commandArgs.slice(1)] };
+    }
+    throw new Error(`Unknown k8s command: ${subcommand ?? ""}`.trim());
+  }
+  if (command === "vcluster") {
+    if (options.project || options.branch || options.session) {
+      throw new Error("Project, branch, and session scopes are not supported for `vcluster`");
+    }
+    if (commandArgs[0] !== "trusted-workflow") {
+      throw new Error(`Unknown vcluster command: ${commandArgs[0] ?? ""}`.trim());
     }
-    parseK8sUsageArgs(commandArgs.slice(1));
-    return { kind: "plugin", pluginArgs: ["k8s", "usage", ...commandArgs.slice(1)] };
+    return { kind: "plugin", pluginArgs: ["vcluster", "trusted-workflow", ...commandArgs.slice(1)] };
   }
   if (command === "get") {
     const target = commandArgs[0];
@@ -3284,7 +3413,18 @@ async function runCommand(argv) {
     });
   }
   if (execution.kind === "merge") {
-    const result = await dispatchMergeCommand(client, execution.command);
+    if (!options.json) {
+      if (execution.command.kind === "merge") {
+        process.stderr.write("Merging (publishing the workspace and computing the merge)...\n");
+      } else if (execution.command.kind === "finish") {
+        process.stderr.write(`Finalizing ${execution.command.conflictWorktree} (publishing the resolver workspace)...
+`);
+      }
+    }
+    const result = await dispatchMergeCommand(client, execution.command, {
+      ...options.json ? {} : { onProgress: (line) => process.stderr.write(`${line}
+`) }
+    });
     writeDataOutput(options.json, result.data, result.human);
     return 0;
   }
@@ -3360,6 +3500,7 @@ async function main(argv = process.argv.slice(2)) {
   getR5dctlVersion,
   getTransientDevicePollDelay,
   handleAuthLogin,
+  isMergeAttemptSettled,
   main,
   parseAnswerEnvRequestCommandArgs,
   parseAnswerFlags,

package/dist/cjs/package.json

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

package/dist/mjs/cli.mjs

@@ -11,16 +11,8 @@ import {
   R5dctlClient
 } from "@ricsam/r5d-api";
 import { runR5dctlShell } from "./shell.mjs";
-const CHAT_MODES = /* @__PURE__ */ new Set([
-  "ask",
-  "plan",
-  "build",
-  "agent",
-  "security_review",
-  "large_diff_remediation",
-  "merge_conflict_resolution"
-]);
-const R5DCTL_SESSION_MODES = /* @__PURE__ */ new Set(["ask", "plan", "build", "agent"]);
+const CHAT_MODES = /* @__PURE__ */ new Set(["ask", "plan", "agent", "large_diff_remediation", "merge_conflict_resolution"]);
+const R5DCTL_SESSION_MODES = /* @__PURE__ */ new Set(["ask", "plan", "agent"]);
 const MODEL_TIERS = /* @__PURE__ */ new Set(["low", "medium", "high", "max"]);
 const R5DCTL_PACKAGE_NAME = "@ricsam/r5dctl";
 const CLI_GLOBAL_OPTION_HELP = [
@@ -71,6 +63,9 @@ const PS_HELP_TEXT = [
 const K8S_HELP_TEXT = [
   "Usage:",
   "  r5dctl k8s usage [--namespace <name>] [--workload <name|namespace/name|uid>] [--container <name>] [--window <24h|7d>]",
+  "  r5dctl vcluster trusted-workflow add --repo <owner/repository> --workflow <.github/workflows/file.yml>",
+  "  r5dctl vcluster trusted-workflow list",
+  "  r5dctl vcluster trusted-workflow remove <workflow-id>",
   "",
   "Show current and rolling CPU and memory usage for managed-vCluster workload containers.",
   ""
@@ -89,10 +84,12 @@ const SESSION_RUN_HELP_TEXT = [
 ].join("\n");
 const MERGE_HELP_TEXT = [
   "Usage:",
-  "  r5dctl -p <project> merge [--worker <label>] [--create-conflict-worktree|--launch-conflict-resolution-agent] <source-worktree>",
+  "  r5dctl -p <project> merge [--worker <label>] [--create-conflict-worktree|--launch-conflict-resolution-agent] [--no-wait] <source-worktree>",
+  "  r5dctl -p <project> merge status <attempt-id>",
   '  r5dctl -p <project> merge finish --worker <label> [--summary "<summary>"] <conflict-worktree>',
   "",
   "Merge a managed worktree into its recorded parent worktree.",
+  "Conflict worktrees provision in the background; merge waits by default and --no-wait returns the attempt immediately.",
   ""
 ].join("\n");
 const SHARED_HELP_ENTRIES = [
@@ -225,6 +222,17 @@ const SHARED_HELP_ENTRIES = [
     usage: "k8s usage [--namespace <name>] [--workload <name|namespace/name|uid>] [--container <name>] [--window <24h|7d>]",
     description: "Show current and rolling CPU and memory usage for managed-vCluster workload containers."
   },
+  {
+    section: "kubernetes",
+    usage: "vcluster trusted-workflow add --repo <owner/repository> --workflow <.github/workflows/file.yml>",
+    description: "Trust an exact GitHub Actions workflow path to authenticate kubectl against your managed vCluster."
+  },
+  { section: "kubernetes", usage: "vcluster trusted-workflow list", description: "List trusted GitHub Actions workflows." },
+  {
+    section: "kubernetes",
+    usage: "vcluster trusted-workflow remove <workflow-id>",
+    description: "Revoke a trusted GitHub Actions workflow and its outstanding credentials."
+  },
   {
     section: "processes",
     usage: "ps list [--worker <label>]",
@@ -243,9 +251,14 @@ const SHARED_HELP_ENTRIES = [
   { section: "processes", usage: "ps stop <run-id>", description: "Gracefully stop an active process with SIGTERM." },
   {
     section: "merge",
-    usage: "-p <project> merge [--worker <label>] [--create-conflict-worktree|--launch-conflict-resolution-agent] <source-worktree>",
+    usage: "-p <project> merge [--worker <label>] [--create-conflict-worktree|--launch-conflict-resolution-agent] [--no-wait] <source-worktree>",
     description: "Merge a worktree into its recorded parent, with an explicit conflict strategy."
   },
+  {
+    section: "merge",
+    usage: "-p <project> merge status <attempt-id>",
+    description: "Show a merge attempt's provisioning and resolution status."
+  },
   {
     section: "merge",
     usage: '-p <project> merge finish --worker <label> [--summary "<summary>"] <conflict-worktree>',
@@ -482,7 +495,7 @@ function requireModel(value) {
 function requireSessionMode(value) {
   const mode = requireValue(value?.trim(), "--mode <mode> is required");
   if (!R5DCTL_SESSION_MODES.has(mode)) {
-    throw new Error("Invalid --mode. Expected one of: ask, plan, build, agent");
+    throw new Error("Invalid --mode. Expected one of: ask, plan, agent");
   }
   return mode;
 }
@@ -568,12 +581,19 @@ function parseMergeCommand(options, args) {
       ...parsed2.values.get("--summary")?.trim() ? { summary: parsed2.values.get("--summary").trim() } : {}
     };
   }
+  if (args[0] === "status") {
+    const parsed2 = parseCommandOperands(args.slice(1), /* @__PURE__ */ new Set(), /* @__PURE__ */ new Map(), "merge status");
+    const attemptId = requireValue(parsed2.positionals[0], "Attempt id is required for `merge status`");
+    if (parsed2.positionals.length > 1) throw new Error(`Unexpected merge status argument: ${parsed2.positionals[1]}`);
+    return { kind: "status", project, attemptId };
+  }
   const parsed = parseCommandOperands(
     args,
     /* @__PURE__ */ new Set(["--worker"]),
     /* @__PURE__ */ new Map([
       ["--create-conflict-worktree", "--create-conflict-worktree"],
-      ["--launch-conflict-resolution-agent", "--launch-conflict-resolution-agent"]
+      ["--launch-conflict-resolution-agent", "--launch-conflict-resolution-agent"],
+      ["--no-wait", "--no-wait"]
     ]),
     "merge"
   );
@@ -586,7 +606,14 @@ function parseMergeCommand(options, args) {
   }
   const conflictMode = createWorktree ? "worktree" : launchAgent ? "agent" : "none";
   const worker = parsed.values.get("--worker")?.trim();
-  return { kind: "merge", project, sourceWorktree, conflictMode, ...worker ? { worker } : {} };
+  return {
+    kind: "merge",
+    project,
+    sourceWorktree,
+    conflictMode,
+    ...worker ? { worker } : {},
+    ...parsed.booleans.has("--no-wait") ? { noWait: true } : {}
+  };
 }
 function assertAuthLoginArgs(args) {
   const valueFlags = /* @__PURE__ */ new Set(["--device-name", "--worker-label"]);
@@ -1874,17 +1901,22 @@ function renderSessionRunStatus(session) {
 function renderWorktreeMerge(result, input) {
   const lines = [];
   appendMergeDetails(lines, result);
+  const status = responseString(result, "status");
   const conflictWorktree = responseString(result, "conflictWorktree");
   const resolverSessionId = responseString(result, "resolverSessionId");
+  const attemptId = responseString(result, "attemptId");
   const worker = responseString(result, "worker") ?? input.worker;
   if (resolverSessionId) lines.push("", `Resolver session: ${resolverSessionId}`, `  r5dctl session stop ${resolverSessionId}`);
-  if (conflictWorktree && worker && ["conflicts", "conflict_worktree_created", "resolving"].includes(responseString(result, "status") ?? "")) {
+  if (conflictWorktree && worker && ["conflicts", "conflict_worktree_created", "resolving"].includes(status ?? "")) {
     lines.push(
       "",
       "Finish after resolving and reviewing the conflict worktree:",
       `  r5dctl -p ${input.project} merge finish --worker ${worker} ${conflictWorktree} --summary "<summary>"`
     );
   }
+  if (attemptId && (status === "provisioning" || status === "resolving" && result.resolverAgentRunning === false)) {
+    lines.push("", "Check progress:", `  r5dctl -p ${input.project} merge status ${attemptId}`);
+  }
   return `${lines.join("\n")}
 `;
 }
@@ -1924,13 +1956,64 @@ async function dispatchSessionRunCommand(client, command) {
   const data = await client.sessions.stop(command.sessionId);
   return { data, human: renderSessionRunStatus(data) };
 }
-async function dispatchMergeCommand(client, command) {
+const MERGE_POLL_INTERVAL_MS = 2e3;
+const MERGE_POLL_TIMEOUT_MS = 20 * 6e4;
+const MERGE_POLL_MAX_CONSECUTIVE_FAILURES = 5;
+function isMergeAttemptSettled(response) {
+  const status = responseString(response, "status");
+  if (!status) return true;
+  if (status === "resolving") return response.resolverAgentRunning !== false;
+  return status !== "provisioning";
+}
+async function pollMergeAttemptUntilSettled(client, project, attemptId, initial, options) {
+  const intervalMs = options.pollIntervalMs ?? MERGE_POLL_INTERVAL_MS;
+  const timeoutMs = options.pollTimeoutMs ?? MERGE_POLL_TIMEOUT_MS;
+  const sleep2 = options.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+  const onProgress = options.onProgress ?? (() => {
+  });
+  let latest = initial;
+  let worktreeReadyReported = latest.worktreeReady === true;
+  let consecutiveFailures = 0;
+  let waitedMs = 0;
+  while (!isMergeAttemptSettled(latest)) {
+    if (waitedMs >= timeoutMs) {
+      onProgress(`Still waiting after ${Math.round(timeoutMs / 6e4)} minutes; check later with: r5dctl -p ${project} merge status ${attemptId}`);
+      return latest;
+    }
+    await sleep2(intervalMs);
+    waitedMs += intervalMs;
+    try {
+      latest = await client.projects.worktrees.mergeAttempt(project, attemptId);
+      consecutiveFailures = 0;
+    } catch (error) {
+      consecutiveFailures += 1;
+      if (consecutiveFailures >= MERGE_POLL_MAX_CONSECUTIVE_FAILURES) throw error;
+      continue;
+    }
+    if (!worktreeReadyReported && latest.worktreeReady === true) {
+      worktreeReadyReported = true;
+      onProgress("Conflict worktree ready.");
+    }
+  }
+  return latest;
+}
+async function dispatchMergeCommand(client, command, pollOptions = {}) {
   if (command.kind === "merge") {
     const data2 = await client.projects.worktrees.merge(command.project, command.sourceWorktree, {
       conflictMode: command.conflictMode,
       ...command.worker ? { worker: command.worker } : {}
     });
-    return { data: data2, human: renderWorktreeMerge(data2, command) };
+    const attemptId = responseString(data2, "attemptId");
+    if (command.noWait || !attemptId || isMergeAttemptSettled(data2)) {
+      return { data: data2, human: renderWorktreeMerge(data2, command) };
+    }
+    pollOptions.onProgress?.(`Provisioning the conflict worktree (attempt ${attemptId})...`);
+    const settled = await pollMergeAttemptUntilSettled(client, command.project, attemptId, data2, pollOptions);
+    return { data: settled, human: renderWorktreeMerge(settled, command) };
+  }
+  if (command.kind === "status") {
+    const data2 = await client.projects.worktrees.mergeAttempt(command.project, command.attemptId);
+    return { data: data2, human: renderWorktreeMerge(data2, { project: command.project }) };
   }
   const data = await client.projects.worktrees.finishMerge(command.project, command.conflictWorktree, {
     worker: command.worker,
@@ -2487,6 +2570,40 @@ async function executeR5dctlCommand(client, json, args) {
     write(report, renderK8sUsageReport(report));
     return;
   }
+  if (first === "vcluster" && second === "trusted-workflow") {
+    const subcommand = requireValue(args[2], "Missing trusted-workflow command");
+    if (subcommand === "add") {
+      const parsed = parseCommandOperands(args.slice(3), /* @__PURE__ */ new Set(["--repo", "--workflow"]), /* @__PURE__ */ new Map(), "trusted-workflow add");
+      if (parsed.positionals.length > 0) throw new Error(`Unexpected trusted-workflow add value: ${parsed.positionals[0]}`);
+      const workflow = await client.k8s.trustedWorkflows.add({
+        repository: requireValue(parsed.values.get("--repo"), "--repo <owner/repository> is required"),
+        workflowPath: requireValue(parsed.values.get("--workflow"), "--workflow <path> is required")
+      });
+      write(workflow, "Trusted GitHub workflow configured successfully.\n");
+      return;
+    }
+    if (subcommand === "list") {
+      if (args.length > 3) throw new Error(`Unexpected trusted-workflow list value: ${args[3]}`);
+      const workflows = await client.k8s.trustedWorkflows.list();
+      write(
+        workflows,
+        workflows.length === 0 ? "No trusted GitHub workflows.\n" : `${workflows.map(
+          (workflow) => `${workflow.id}  ${workflow.repository}  ${workflow.workflowPath}  ${workflow.revokedAt ? "revoked" : "active"}`
+        ).join("\n")}
+`
+      );
+      return;
+    }
+    if (subcommand === "remove") {
+      const workflowId = requireValue(args[3], "Missing trusted workflow id");
+      if (args.length > 4) throw new Error(`Unexpected trusted-workflow remove value: ${args[4]}`);
+      const result = await client.k8s.trustedWorkflows.revoke(workflowId);
+      if (!result.success) throw new Error("Trusted GitHub workflow was not found or was already revoked");
+      write(result, "Trusted GitHub workflow revoked.\n");
+      return;
+    }
+    throw new Error(`Unknown trusted-workflow command: ${subcommand}`);
+  }
   if (first === "ps" && second === "list") {
     const processes = await client.processes.list(parsePsListArgs(args.slice(2)));
     write(processes, renderProcessList(processes));
@@ -2856,12 +2973,23 @@ function resolveCommandExecution(options, rest) {
   }
   if (command === "k8s") {
     const subcommand = commandArgs[0];
-    if (subcommand !== "usage") throw new Error(`Unknown k8s command: ${subcommand ?? ""}`.trim());
     if (options.project || options.branch || options.session) {
-      throw new Error("Project, branch, and session scopes are not supported for `k8s usage`");
+      throw new Error("Project, branch, and session scopes are not supported for `k8s`");
+    }
+    if (subcommand === "usage") {
+      parseK8sUsageArgs(commandArgs.slice(1));
+      return { kind: "plugin", pluginArgs: ["k8s", "usage", ...commandArgs.slice(1)] };
+    }
+    throw new Error(`Unknown k8s command: ${subcommand ?? ""}`.trim());
+  }
+  if (command === "vcluster") {
+    if (options.project || options.branch || options.session) {
+      throw new Error("Project, branch, and session scopes are not supported for `vcluster`");
+    }
+    if (commandArgs[0] !== "trusted-workflow") {
+      throw new Error(`Unknown vcluster command: ${commandArgs[0] ?? ""}`.trim());
     }
-    parseK8sUsageArgs(commandArgs.slice(1));
-    return { kind: "plugin", pluginArgs: ["k8s", "usage", ...commandArgs.slice(1)] };
+    return { kind: "plugin", pluginArgs: ["vcluster", "trusted-workflow", ...commandArgs.slice(1)] };
   }
   if (command === "get") {
     const target = commandArgs[0];
@@ -3199,7 +3327,18 @@ async function runCommand(argv) {
     });
   }
   if (execution.kind === "merge") {
-    const result = await dispatchMergeCommand(client, execution.command);
+    if (!options.json) {
+      if (execution.command.kind === "merge") {
+        process.stderr.write("Merging (publishing the workspace and computing the merge)...\n");
+      } else if (execution.command.kind === "finish") {
+        process.stderr.write(`Finalizing ${execution.command.conflictWorktree} (publishing the resolver workspace)...
+`);
+      }
+    }
+    const result = await dispatchMergeCommand(client, execution.command, {
+      ...options.json ? {} : { onProgress: (line) => process.stderr.write(`${line}
+`) }
+    });
     writeDataOutput(options.json, result.data, result.human);
     return 0;
   }
@@ -3274,6 +3413,7 @@ export {
   getR5dctlVersion,
   getTransientDevicePollDelay,
   handleAuthLogin,
+  isMergeAttemptSettled,
   main,
   parseAnswerEnvRequestCommandArgs,
   parseAnswerFlags,

package/dist/mjs/package.json

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

package/dist/types/cli.d.ts

@@ -85,6 +85,11 @@ export type R5dctlMergeCommand = {
     sourceWorktree: string;
     worker?: string;
     conflictMode: R5dctlMergeConflictMode;
+    noWait?: boolean;
+} | {
+    kind: "status";
+    project: string;
+    attemptId: string;
 } | {
     kind: "finish";
     project: string;
@@ -229,6 +234,8 @@ export type R5dctlCommandResponse = {
     conflictedFiles?: string[];
     failureReason?: string;
     message?: string;
+    worktreeReady?: boolean;
+    resolverAgentRunning?: boolean;
 };
 export type R5dctlSessionRunClient = {
     projects: {
@@ -259,6 +266,7 @@ export type R5dctlMergeClient = {
                 worker: string;
                 summary?: string;
             }) => Promise<R5dctlCommandResponse>;
+            mergeAttempt: (projectRef: string, attemptId: string) => Promise<R5dctlCommandResponse>;
         };
     };
 };
@@ -273,7 +281,21 @@ export type R5dctlCommandDispatchResult = {
     human: string;
 };
 export declare function dispatchSessionRunCommand(client: R5dctlSessionRunClient, command: R5dctlSessionRunCommand): Promise<R5dctlCommandDispatchResult>;
-export declare function dispatchMergeCommand(client: R5dctlMergeClient, command: R5dctlMergeCommand): Promise<R5dctlCommandDispatchResult>;
+export type R5dctlMergePollOptions = {
+    onProgress?: (line: string) => void;
+    pollIntervalMs?: number;
+    pollTimeoutMs?: number;
+    sleep?: (ms: number) => Promise<void>;
+};
+/**
+ * Whether a merge attempt response is settled for the CLI: terminal, waiting
+ * on the user (a ready manual conflict worktree), or actively resolving with
+ * its agent running. Anything else is still provisioning or starting. A
+ * "resolving" response without the resolverAgentRunning field comes from a
+ * server that starts the agent in-request, so it counts as settled.
+ */
+export declare function isMergeAttemptSettled(response: R5dctlCommandResponse): boolean;
+export declare function dispatchMergeCommand(client: R5dctlMergeClient, command: R5dctlMergeCommand, pollOptions?: R5dctlMergePollOptions): Promise<R5dctlCommandDispatchResult>;
 export declare function parseConversationRenderArgs(args: string[]): ConversationRenderOptions;
 export declare function renderConversationResponse(read: R5dctlConversationResponse): string;
 type R5dctlFollowClient = {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ricsam/r5dctl",
-  "version": "0.0.72",
+  "version": "0.0.74",
   "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.72",
+    "@ricsam/r5d-api": "^0.0.74",
     "dotenv": "^17",
     "qrcode": "^1.5.4",
     "ws": "^8.18.3"