@ricsam/r5dctl 0.0.23 → 0.0.24

package/README.md

@@ -51,7 +51,7 @@ r5dctl -p <project> get branches
 r5dctl -p <project> describe branch <branch>
 r5dctl -p <project> -b <branch> get envs
 r5dctl -p <project> -b <branch> set envs --from-env-file ~/.env --only-missing
-r5dctl -p <project> -b <branch> set envs -e backend/API_KEY=value --description "API credential"
+r5dctl -p <project> -b <branch> set envs -e API_KEY=value --description "API credential"
 r5dctl -p <project> get sessions --branch <branch>
 r5dctl -p <project> create session -b <branch> --name "Spec session"
 r5dctl describe session <session-id>
@@ -65,15 +65,22 @@ r5dctl -s <session-id> conversation --system           # include system prompt m
 r5dctl -s <session-id> conversation --raw --tools --system  # exact raw agent request transcript
 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> apply-required-envs -e backend/KEY=value -e frontend/KEY=value
+r5dctl -s <session-id> apply-required-envs -e KEY=value
 
 r5dctl -p <project> -b <branch> shell
 r5dctl -p <project> -b <branch> shell -c "bun test"
+
+r5dctl ps list
+r5dctl -p <project> -b <branch> ps list --worker <label>
+r5dctl -s <session-id> ps list --json
+r5dctl ps stop <run-id>
 ```
 
 `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.
 
-`get envs` reports names and whether values are set, but never prints the values. Prefer `--from-env-file` for bulk imports so secret values do not appear in shell arguments or history. Dotenv imports target backend envs by default; use `--target frontend` when needed. Empty dotenv values are skipped unless `--include-empty` is passed, and `--only-missing` preserves values that are already set.
+`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.
+
+`get envs` reports names and whether values are set, but never prints the values. Prefer `--from-env-file` for bulk imports so secret values do not appear in shell arguments or history. Empty dotenv values are skipped unless `--include-empty` is passed, and `--only-missing` preserves values that are already set.
 
 Conversation output is human-readable by default and excludes both the system prompt and tool definitions. `--raw` keeps the transcript layout but renders structured message and tool parts as JSON, `--tools` includes the provider-shaped tool definitions, and `--system` includes system prompt messages. The global `--json` flag remains separate and prints the complete API response envelope.
 

package/dist/cjs/cli.cjs

@@ -28,6 +28,7 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 var cli_exports = {};
 __export(cli_exports, {
+  formatProcessAge: () => formatProcessAge,
   getCliHelpText: () => getCliHelpText,
   getR5dctlVersion: () => getR5dctlVersion,
   main: () => main,
@@ -36,10 +37,12 @@ __export(cli_exports, {
   parseEnvFlags: () => parseEnvFlags,
   parseGlobalArgs: () => parseGlobalArgs,
   parsePromptArgs: () => parsePromptArgs,
+  parsePsListArgs: () => parsePsListArgs,
   parseSetEnvArgs: () => parseSetEnvArgs,
   parseShellArgs: () => parseShellArgs,
   readDotenvFile: () => readDotenvFile,
   renderConversationResponse: () => renderConversationResponse,
+  renderProcessList: () => renderProcessList,
   resolveCommandExecution: () => resolveCommandExecution,
   runR5dctlCli: () => runR5dctlCli,
   summarizeEnvData: () => summarizeEnvData
@@ -102,6 +105,15 @@ const CLI_ONLY_COMMAND_HELP = [
     usage: "-p <project> -b <branch> shell [-c <command>]"
   }
 ];
+const PS_HELP_TEXT = [
+  "Usage:",
+  "  r5dctl ps list [--worker <label>]",
+  "  r5dctl ps stop <run-id>",
+  "",
+  "List or gracefully stop active r5d-managed worker processes.",
+  "Use -p/--project, -b/--branch, or -s/--session to filter ps list.",
+  ""
+].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." },
@@ -125,12 +137,12 @@ const SHARED_HELP_ENTRIES = [
   },
   {
     section: "envs",
-    usage: "-p <project> -b <branch> set envs --from-env-file <path> [--target <backend|frontend>] [--only-missing]",
+    usage: "-p <project> -b <branch> set envs --from-env-file <path> [--only-missing]",
     description: "Securely import branch envs from a dotenv file without putting values in command arguments."
   },
   {
     section: "envs",
-    usage: "-p <project> -b <branch> set envs -e backend/KEY=value [--description <text>] [--only-missing]",
+    usage: "-p <project> -b <branch> set envs -e KEY=value [--description <text>] [--only-missing]",
     description: "Set one or more branch envs directly."
   },
   {
@@ -163,9 +175,15 @@ const SHARED_HELP_ENTRIES = [
   },
   {
     section: "sessions",
-    usage: "-s <session-id> apply-required-envs -e backend/KEY=value -e frontend/KEY=value",
-    description: "Apply required backend or frontend env values."
+    usage: "-s <session-id> apply-required-envs -e KEY=value",
+    description: "Apply required environment variable values."
   },
+  {
+    section: "processes",
+    usage: "ps list [--worker <label>]",
+    description: "List active r5d-managed worker processes; global project, branch, and session filters apply."
+  },
+  { 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>"',
@@ -181,13 +199,24 @@ const SHARED_HELP_ENTRIES = [
   { 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." }
 ];
-const HELP_SECTION_ORDER = ["auth", "projects", "branches", "envs", "sessions", "shell", "agents", "merges"];
+const HELP_SECTION_ORDER = [
+  "auth",
+  "projects",
+  "branches",
+  "envs",
+  "sessions",
+  "processes",
+  "shell",
+  "agents",
+  "merges"
+];
 const HELP_SECTION_TITLES = {
   auth: "Auth",
   projects: "Projects",
   branches: "Branches",
   envs: "Environment variables",
   sessions: "Sessions",
+  processes: "Processes",
   shell: "Shell",
   agents: "Agents",
   merges: "Merges"
@@ -288,7 +317,7 @@ function renderCliOnlyCommandHelp(entry) {
 }
 function renderSharedCommandHelp(pathSegments) {
   const entry = SHARED_HELP_ENTRIES.find((candidate) => {
-    const usageSegments = candidate.usage.split(" ").filter((segment) => !segment.startsWith("-") && !segment.startsWith("<") && !segment.startsWith("["));
+    const usageSegments = candidate.usage.split(" ").map((segment) => segment.replace(/^\[/, "").replace(/\]$/, "")).filter((segment) => !segment.startsWith("-") && !segment.startsWith("<") && !segment.startsWith("["));
     return usageSegments.length <= pathSegments.length && usageSegments.every((segment, index) => segment === pathSegments[index]);
   });
   if (!entry) {
@@ -524,33 +553,24 @@ function parseAnswerFlags(args) {
 function validateEnvAssignment(value) {
   const equalsIndex = value.indexOf("=");
   if (equalsIndex <= 0) {
-    throw new Error(`Invalid env assignment '${value}'. Expected backend/KEY=value or frontend/KEY=value`);
-  }
-  const assignment = value.slice(0, equalsIndex);
-  const slashIndex = assignment.indexOf("/");
-  if (slashIndex <= 0) {
-    throw new Error(`Invalid env assignment '${value}'. Expected backend/KEY=value or frontend/KEY=value`);
+    throw new Error(`Invalid env assignment '${value}'. Expected KEY=value`);
   }
-  const target = assignment.slice(0, slashIndex);
-  const key = assignment.slice(slashIndex + 1);
-  if (target !== "backend" && target !== "frontend" || !/^[A-Za-z_][A-Za-z0-9_]*$/.test(key)) {
-    throw new Error(`Invalid env assignment '${value}'. Expected backend/KEY=value or frontend/KEY=value`);
+  const key = value.slice(0, equalsIndex);
+  if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(key)) {
+    throw new Error(`Invalid env assignment '${value}'. Expected KEY=value`);
   }
 }
 function parseEnvAssignment(value) {
   validateEnvAssignment(value);
   const equalsIndex = value.indexOf("=");
-  const slashIndex = value.indexOf("/");
   return {
-    target: value.slice(0, slashIndex),
-    name: value.slice(slashIndex + 1, equalsIndex),
+    name: value.slice(0, equalsIndex),
     value: value.slice(equalsIndex + 1)
   };
 }
 function parseSetEnvArgs(args) {
   const parsed = {
     assignments: [],
-    target: "backend",
     onlyMissing: false,
     includeEmpty: false
   };
@@ -580,23 +600,6 @@ function parseSetEnvArgs(args) {
       parsed.fromEnvFile = requireValue(inlineFile, "Missing value for --from-env-file");
       continue;
     }
-    if (arg === "--target") {
-      const target = requireValue(args[index + 1], "Missing value for --target");
-      if (target !== "backend" && target !== "frontend") {
-        throw new Error("Invalid --target. Expected backend or frontend");
-      }
-      parsed.target = target;
-      index += 1;
-      continue;
-    }
-    const inlineTarget = parseLongOptionWithEquals(arg, "--target");
-    if (inlineTarget !== void 0) {
-      if (inlineTarget !== "backend" && inlineTarget !== "frontend") {
-        throw new Error("Invalid --target. Expected backend or frontend");
-      }
-      parsed.target = inlineTarget;
-      continue;
-    }
     if (arg === "--description") {
       parsed.description = requireValue(args[index + 1], "Missing value for --description");
       index += 1;
@@ -670,7 +673,7 @@ function parseEnvFlags(args) {
     if (arg.startsWith("-")) {
       throw new Error(`Unknown env flag: ${arg}`);
     }
-    throw new Error(`Unexpected value '${arg}'. Use -e backend/KEY=value.`);
+    throw new Error(`Unexpected value '${arg}'. Use -e KEY=value.`);
   }
   if (envs.length === 0) {
     throw new Error("At least one -e/--env value is required.");
@@ -764,6 +767,40 @@ function parseShellArgs(args) {
   }
   return command === void 0 ? {} : { command };
 }
+function parsePsListArgs(args) {
+  const input = {};
+  const definitions = [
+    { flag: "--project", key: "project" },
+    { flag: "--branch", key: "branch" },
+    { flag: "--session", key: "session" },
+    { flag: "--worker", key: "worker" }
+  ];
+  const assign = (key, value, flag) => {
+    if (input[key] !== void 0) {
+      throw new Error(`Use only one ${flag} value`);
+    }
+    input[key] = requireValue(value, `Missing value for ${flag}`);
+  };
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+    if (!arg) continue;
+    const definition = definitions.find(({ flag }) => arg === flag || arg.startsWith(`${flag}=`));
+    if (!definition) {
+      throw new Error(arg.startsWith("-") ? `Unknown ps list flag: ${arg}` : `Unexpected ps list value: ${arg}`);
+    }
+    if (arg === definition.flag) {
+      assign(definition.key, requireValue(args[index + 1], `Missing value for ${definition.flag}`), definition.flag);
+      index += 1;
+      continue;
+    }
+    assign(
+      definition.key,
+      requireValue(parseLongOptionWithEquals(arg, definition.flag), `Missing value for ${definition.flag}`),
+      definition.flag
+    );
+  }
+  return input;
+}
 async function openInBrowser(url) {
   if (process.platform === "darwin") {
     (0, import_node_child_process.spawn)("open", [url], { stdio: "ignore", detached: true }).unref();
@@ -905,34 +942,66 @@ function renderSessionList(sessions) {
 function renderSessionDescription(session) {
   return [`Session: ${session.id}`, `Project: ${session.projectPath}`, `Branch: ${session.branchName}`].join("\n") + "\n";
 }
+function formatProcessAge(startedAt, nowMs = Date.now()) {
+  const startedAtMs = Date.parse(startedAt);
+  if (!Number.isFinite(startedAtMs)) {
+    return "unknown";
+  }
+  const totalSeconds = Math.max(0, Math.floor((nowMs - startedAtMs) / 1e3));
+  if (totalSeconds < 60) {
+    return `${totalSeconds}s`;
+  }
+  if (totalSeconds < 60 * 60) {
+    const minutes = Math.floor(totalSeconds / 60);
+    const seconds = totalSeconds % 60;
+    return `${minutes}m ${String(seconds).padStart(2, "0")}s`;
+  }
+  if (totalSeconds < 24 * 60 * 60) {
+    const hours2 = Math.floor(totalSeconds / (60 * 60));
+    const minutes = Math.floor(totalSeconds % (60 * 60) / 60);
+    return `${hours2}h ${String(minutes).padStart(2, "0")}m`;
+  }
+  const days = Math.floor(totalSeconds / (24 * 60 * 60));
+  const hours = Math.floor(totalSeconds % (24 * 60 * 60) / (60 * 60));
+  return `${days}d ${hours}h`;
+}
+function renderProcessList(processes, nowMs = Date.now()) {
+  if (processes.length === 0) {
+    return "No active processes.\n";
+  }
+  const headers = ["RUN ID", "STATUS", "AGE", "WORKER", "PROJECT", "BRANCH", "SESSION", "COMMAND"];
+  const rows = processes.map((process2) => [
+    process2.runId,
+    process2.status,
+    formatProcessAge(process2.startedAt, nowMs),
+    process2.workerLabel,
+    process2.projectPath,
+    process2.branchName,
+    process2.sessionId,
+    process2.command
+  ]);
+  const widths = headers.map((header, column) => Math.max(header.length, ...rows.map((row) => row[column]?.length ?? 0)));
+  const formatRow = (row) => row.map((value, column) => column === row.length - 1 ? value : value.padEnd(widths[column] ?? value.length)).join("  ");
+  const separator = widths.map((width) => "-".repeat(width)).join("  ");
+  return `${[formatRow(headers), separator, ...rows.map(formatRow)].join("\n")}
+`;
+}
 function summarizeEnvData(data) {
-  const summary = {};
-  for (const target of ["backend", "frontend"]) {
-    const entries = data[target];
-    if (!entries) continue;
-    summary[target] = Object.fromEntries(
-      Object.entries(entries).sort(([left], [right]) => left.localeCompare(right)).map(([name, env]) => [
-        name,
-        {
-          optional: env.optional ?? false,
-          description: env.description,
-          hasValue: env.value !== null
-        }
-      ])
-    );
-  }
-  return summary;
+  return Object.fromEntries(
+    Object.entries(data).sort(([left], [right]) => left.localeCompare(right)).map(([name, env]) => [
+      name,
+      {
+        optional: env.optional ?? false,
+        description: env.description,
+        hasValue: env.value !== null
+      }
+    ])
+  );
 }
 function renderEnvSummary(data) {
   const lines = [];
-  for (const target of ["backend", "frontend"]) {
-    const entries = Object.entries(data[target] ?? {});
-    if (entries.length === 0) continue;
-    if (lines.length > 0) lines.push("");
-    lines.push(`${target}:`);
-    for (const [name, env] of entries) {
-      lines.push(`  ${name}  ${env.hasValue ? "set" : "missing"}  ${env.optional ? "optional" : "required"}  ${env.description}`);
-    }
+  for (const [name, env] of Object.entries(data)) {
+    lines.push(`${name}  ${env.hasValue ? "set" : "missing"}  ${env.optional ? "optional" : "required"}  ${env.description}`);
   }
   return lines.length > 0 ? `${lines.join("\n")}
 ` : "No environment variables declared.\n";
@@ -944,7 +1013,7 @@ function renderEnvSetResult(result) {
   if (result.skippedExisting.length > 0) lines.push(`Skipped ${result.skippedExisting.length} existing value(s).`);
   if (result.skippedEmpty.length > 0) lines.push(`Skipped ${result.skippedEmpty.length} empty value(s).`);
   if (result.updated.length > 0) {
-    lines.push(...result.updated.map(({ target, name }) => `  ${target}/${name}`));
+    lines.push(...result.updated.map(({ name }) => `  ${name}`));
   }
   return `${lines.join("\n")}
 `;
@@ -957,10 +1026,10 @@ async function setBranchEnvs(client, projectRef, branchName, args) {
     if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(name)) {
       throw new Error(`Invalid environment variable name in dotenv file: ${name}`);
     }
-    return { target: options.target, name, value };
+    return { name, value };
   }) : options.assignments.map(parseEnvAssignment);
   const uniqueAssignments = /* @__PURE__ */ new Map();
-  for (const assignment of assignments) uniqueAssignments.set(`${assignment.target}/${assignment.name}`, assignment);
+  for (const assignment of assignments) uniqueAssignments.set(assignment.name, assignment);
   const update = {};
   const result = {
     success: true,
@@ -973,12 +1042,12 @@ async function setBranchEnvs(client, projectRef, branchName, args) {
   const missingDescriptions = [];
   const importedDescription = options.fromEnvFile ? `Imported from ${import_node_path.default.basename(options.fromEnvFile)}.` : void 0;
   for (const assignment of uniqueAssignments.values()) {
-    const identity = { target: assignment.target, name: assignment.name };
+    const identity = { name: assignment.name };
     if (!options.includeEmpty && assignment.value.length === 0) {
       result.skippedEmpty.push(identity);
       continue;
     }
-    const existing = current[assignment.target]?.[assignment.name];
+    const existing = current[assignment.name];
     if (options.onlyMissing && existing?.value !== null && existing?.value !== void 0) {
       result.skippedExisting.push(identity);
       continue;
@@ -988,9 +1057,8 @@ async function setBranchEnvs(client, projectRef, branchName, args) {
       missingDescriptions.push(identity);
       continue;
     }
-    const targetUpdate = update[assignment.target] ??= {};
     const optional = options.optional ?? existing?.optional;
-    targetUpdate[assignment.name] = {
+    update[assignment.name] = {
       description,
       value: assignment.value,
       ...optional === void 0 ? {} : { optional }
@@ -998,9 +1066,7 @@ async function setBranchEnvs(client, projectRef, branchName, args) {
     result.updated.push(identity);
   }
   if (missingDescriptions.length > 0) {
-    throw new Error(
-      `--description is required when declaring new envs with -e: ${missingDescriptions.map(({ target, name }) => `${target}/${name}`).join(", ")}`
-    );
+    throw new Error(`--description is required when declaring new envs with -e: ${missingDescriptions.map(({ name }) => name).join(", ")}`);
   }
   if (result.updated.length > 0) {
     await client.projects.env.update(project.id, branchName, update);
@@ -1165,6 +1231,17 @@ async function executeR5dctlCommand(client, json, args) {
     write(result, "API key revoked.\n");
     return;
   }
+  if (first === "ps" && second === "list") {
+    const processes = await client.processes.list(parsePsListArgs(args.slice(2)));
+    write(processes, renderProcessList(processes));
+    return;
+  }
+  if (first === "ps" && second === "stop") {
+    const process2 = await client.processes.stop(requireValue(args[2], "Missing process run id"));
+    write(process2, `Stopped process ${process2.runId}: ${process2.command}
+`);
+    return;
+  }
   if (first === "projects" && second === "list" || first === "get" && second === "projects") {
     const projects = await client.projects.list();
     write(projects, renderProjectList(projects));
@@ -1360,6 +1437,12 @@ function resolveCommandExecution(options, rest) {
     throw new Error("Missing command");
   }
   const commandArgs = normalizedRest.slice(1);
+  if (command === "ps" && commandArgs.length === 0) {
+    return {
+      kind: "cli-help",
+      text: PS_HELP_TEXT
+    };
+  }
   if (trailingHelp) {
     const cliOnlyHelp = findCliOnlyCommandHelp(normalizedRest);
     if (cliOnlyHelp) {
@@ -1433,6 +1516,36 @@ function resolveCommandExecution(options, rest) {
     }
     throw new Error("Unknown auth command");
   }
+  if (command === "ps") {
+    const subcommand = commandArgs[0];
+    if (subcommand === "list") {
+      const commandFilters = parsePsListArgs(commandArgs.slice(1));
+      const filters = {
+        ...commandFilters,
+        ...options.project ? { project: options.project } : {},
+        ...options.branch ? { branch: options.branch } : {},
+        ...options.session ? { session: options.session } : {}
+      };
+      const pluginArgs = ["ps", "list"];
+      for (const [flag, value] of [
+        ["--project", filters.project],
+        ["--branch", filters.branch],
+        ["--session", filters.session],
+        ["--worker", filters.worker]
+      ]) {
+        if (value) pluginArgs.push(flag, value);
+      }
+      return { kind: "plugin", pluginArgs };
+    }
+    if (subcommand === "stop") {
+      const runId = requireValue(commandArgs[1], "Missing process run id");
+      if (commandArgs.length > 2) {
+        throw new Error(`Unexpected ps stop value: ${commandArgs[2]}`);
+      }
+      return { kind: "plugin", pluginArgs: ["ps", "stop", runId] };
+    }
+    throw new Error(`Unknown ps command: ${subcommand ?? ""}`.trim());
+  }
   if (command === "get") {
     const target = commandArgs[0];
     if (target === "projects") {
@@ -1819,6 +1932,7 @@ async function main(argv = process.argv.slice(2)) {
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  formatProcessAge,
   getCliHelpText,
   getR5dctlVersion,
   main,
@@ -1827,10 +1941,12 @@ async function main(argv = process.argv.slice(2)) {
   parseEnvFlags,
   parseGlobalArgs,
   parsePromptArgs,
+  parsePsListArgs,
   parseSetEnvArgs,
   parseShellArgs,
   readDotenvFile,
   renderConversationResponse,
+  renderProcessList,
   resolveCommandExecution,
   runR5dctlCli,
   summarizeEnvData

package/dist/cjs/package.json

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

package/dist/mjs/cli.mjs

@@ -58,6 +58,15 @@ const CLI_ONLY_COMMAND_HELP = [
     usage: "-p <project> -b <branch> shell [-c <command>]"
   }
 ];
+const PS_HELP_TEXT = [
+  "Usage:",
+  "  r5dctl ps list [--worker <label>]",
+  "  r5dctl ps stop <run-id>",
+  "",
+  "List or gracefully stop active r5d-managed worker processes.",
+  "Use -p/--project, -b/--branch, or -s/--session to filter ps list.",
+  ""
+].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." },
@@ -81,12 +90,12 @@ const SHARED_HELP_ENTRIES = [
   },
   {
     section: "envs",
-    usage: "-p <project> -b <branch> set envs --from-env-file <path> [--target <backend|frontend>] [--only-missing]",
+    usage: "-p <project> -b <branch> set envs --from-env-file <path> [--only-missing]",
     description: "Securely import branch envs from a dotenv file without putting values in command arguments."
   },
   {
     section: "envs",
-    usage: "-p <project> -b <branch> set envs -e backend/KEY=value [--description <text>] [--only-missing]",
+    usage: "-p <project> -b <branch> set envs -e KEY=value [--description <text>] [--only-missing]",
     description: "Set one or more branch envs directly."
   },
   {
@@ -119,9 +128,15 @@ const SHARED_HELP_ENTRIES = [
   },
   {
     section: "sessions",
-    usage: "-s <session-id> apply-required-envs -e backend/KEY=value -e frontend/KEY=value",
-    description: "Apply required backend or frontend env values."
+    usage: "-s <session-id> apply-required-envs -e KEY=value",
+    description: "Apply required environment variable values."
   },
+  {
+    section: "processes",
+    usage: "ps list [--worker <label>]",
+    description: "List active r5d-managed worker processes; global project, branch, and session filters apply."
+  },
+  { 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>"',
@@ -137,13 +152,24 @@ const SHARED_HELP_ENTRIES = [
   { 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." }
 ];
-const HELP_SECTION_ORDER = ["auth", "projects", "branches", "envs", "sessions", "shell", "agents", "merges"];
+const HELP_SECTION_ORDER = [
+  "auth",
+  "projects",
+  "branches",
+  "envs",
+  "sessions",
+  "processes",
+  "shell",
+  "agents",
+  "merges"
+];
 const HELP_SECTION_TITLES = {
   auth: "Auth",
   projects: "Projects",
   branches: "Branches",
   envs: "Environment variables",
   sessions: "Sessions",
+  processes: "Processes",
   shell: "Shell",
   agents: "Agents",
   merges: "Merges"
@@ -244,7 +270,7 @@ function renderCliOnlyCommandHelp(entry) {
 }
 function renderSharedCommandHelp(pathSegments) {
   const entry = SHARED_HELP_ENTRIES.find((candidate) => {
-    const usageSegments = candidate.usage.split(" ").filter((segment) => !segment.startsWith("-") && !segment.startsWith("<") && !segment.startsWith("["));
+    const usageSegments = candidate.usage.split(" ").map((segment) => segment.replace(/^\[/, "").replace(/\]$/, "")).filter((segment) => !segment.startsWith("-") && !segment.startsWith("<") && !segment.startsWith("["));
     return usageSegments.length <= pathSegments.length && usageSegments.every((segment, index) => segment === pathSegments[index]);
   });
   if (!entry) {
@@ -480,33 +506,24 @@ function parseAnswerFlags(args) {
 function validateEnvAssignment(value) {
   const equalsIndex = value.indexOf("=");
   if (equalsIndex <= 0) {
-    throw new Error(`Invalid env assignment '${value}'. Expected backend/KEY=value or frontend/KEY=value`);
-  }
-  const assignment = value.slice(0, equalsIndex);
-  const slashIndex = assignment.indexOf("/");
-  if (slashIndex <= 0) {
-    throw new Error(`Invalid env assignment '${value}'. Expected backend/KEY=value or frontend/KEY=value`);
+    throw new Error(`Invalid env assignment '${value}'. Expected KEY=value`);
   }
-  const target = assignment.slice(0, slashIndex);
-  const key = assignment.slice(slashIndex + 1);
-  if (target !== "backend" && target !== "frontend" || !/^[A-Za-z_][A-Za-z0-9_]*$/.test(key)) {
-    throw new Error(`Invalid env assignment '${value}'. Expected backend/KEY=value or frontend/KEY=value`);
+  const key = value.slice(0, equalsIndex);
+  if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(key)) {
+    throw new Error(`Invalid env assignment '${value}'. Expected KEY=value`);
   }
 }
 function parseEnvAssignment(value) {
   validateEnvAssignment(value);
   const equalsIndex = value.indexOf("=");
-  const slashIndex = value.indexOf("/");
   return {
-    target: value.slice(0, slashIndex),
-    name: value.slice(slashIndex + 1, equalsIndex),
+    name: value.slice(0, equalsIndex),
     value: value.slice(equalsIndex + 1)
   };
 }
 function parseSetEnvArgs(args) {
   const parsed = {
     assignments: [],
-    target: "backend",
     onlyMissing: false,
     includeEmpty: false
   };
@@ -536,23 +553,6 @@ function parseSetEnvArgs(args) {
       parsed.fromEnvFile = requireValue(inlineFile, "Missing value for --from-env-file");
       continue;
     }
-    if (arg === "--target") {
-      const target = requireValue(args[index + 1], "Missing value for --target");
-      if (target !== "backend" && target !== "frontend") {
-        throw new Error("Invalid --target. Expected backend or frontend");
-      }
-      parsed.target = target;
-      index += 1;
-      continue;
-    }
-    const inlineTarget = parseLongOptionWithEquals(arg, "--target");
-    if (inlineTarget !== void 0) {
-      if (inlineTarget !== "backend" && inlineTarget !== "frontend") {
-        throw new Error("Invalid --target. Expected backend or frontend");
-      }
-      parsed.target = inlineTarget;
-      continue;
-    }
     if (arg === "--description") {
       parsed.description = requireValue(args[index + 1], "Missing value for --description");
       index += 1;
@@ -626,7 +626,7 @@ function parseEnvFlags(args) {
     if (arg.startsWith("-")) {
       throw new Error(`Unknown env flag: ${arg}`);
     }
-    throw new Error(`Unexpected value '${arg}'. Use -e backend/KEY=value.`);
+    throw new Error(`Unexpected value '${arg}'. Use -e KEY=value.`);
   }
   if (envs.length === 0) {
     throw new Error("At least one -e/--env value is required.");
@@ -720,6 +720,40 @@ function parseShellArgs(args) {
   }
   return command === void 0 ? {} : { command };
 }
+function parsePsListArgs(args) {
+  const input = {};
+  const definitions = [
+    { flag: "--project", key: "project" },
+    { flag: "--branch", key: "branch" },
+    { flag: "--session", key: "session" },
+    { flag: "--worker", key: "worker" }
+  ];
+  const assign = (key, value, flag) => {
+    if (input[key] !== void 0) {
+      throw new Error(`Use only one ${flag} value`);
+    }
+    input[key] = requireValue(value, `Missing value for ${flag}`);
+  };
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+    if (!arg) continue;
+    const definition = definitions.find(({ flag }) => arg === flag || arg.startsWith(`${flag}=`));
+    if (!definition) {
+      throw new Error(arg.startsWith("-") ? `Unknown ps list flag: ${arg}` : `Unexpected ps list value: ${arg}`);
+    }
+    if (arg === definition.flag) {
+      assign(definition.key, requireValue(args[index + 1], `Missing value for ${definition.flag}`), definition.flag);
+      index += 1;
+      continue;
+    }
+    assign(
+      definition.key,
+      requireValue(parseLongOptionWithEquals(arg, definition.flag), `Missing value for ${definition.flag}`),
+      definition.flag
+    );
+  }
+  return input;
+}
 async function openInBrowser(url) {
   if (process.platform === "darwin") {
     spawn("open", [url], { stdio: "ignore", detached: true }).unref();
@@ -861,34 +895,66 @@ function renderSessionList(sessions) {
 function renderSessionDescription(session) {
   return [`Session: ${session.id}`, `Project: ${session.projectPath}`, `Branch: ${session.branchName}`].join("\n") + "\n";
 }
+function formatProcessAge(startedAt, nowMs = Date.now()) {
+  const startedAtMs = Date.parse(startedAt);
+  if (!Number.isFinite(startedAtMs)) {
+    return "unknown";
+  }
+  const totalSeconds = Math.max(0, Math.floor((nowMs - startedAtMs) / 1e3));
+  if (totalSeconds < 60) {
+    return `${totalSeconds}s`;
+  }
+  if (totalSeconds < 60 * 60) {
+    const minutes = Math.floor(totalSeconds / 60);
+    const seconds = totalSeconds % 60;
+    return `${minutes}m ${String(seconds).padStart(2, "0")}s`;
+  }
+  if (totalSeconds < 24 * 60 * 60) {
+    const hours2 = Math.floor(totalSeconds / (60 * 60));
+    const minutes = Math.floor(totalSeconds % (60 * 60) / 60);
+    return `${hours2}h ${String(minutes).padStart(2, "0")}m`;
+  }
+  const days = Math.floor(totalSeconds / (24 * 60 * 60));
+  const hours = Math.floor(totalSeconds % (24 * 60 * 60) / (60 * 60));
+  return `${days}d ${hours}h`;
+}
+function renderProcessList(processes, nowMs = Date.now()) {
+  if (processes.length === 0) {
+    return "No active processes.\n";
+  }
+  const headers = ["RUN ID", "STATUS", "AGE", "WORKER", "PROJECT", "BRANCH", "SESSION", "COMMAND"];
+  const rows = processes.map((process2) => [
+    process2.runId,
+    process2.status,
+    formatProcessAge(process2.startedAt, nowMs),
+    process2.workerLabel,
+    process2.projectPath,
+    process2.branchName,
+    process2.sessionId,
+    process2.command
+  ]);
+  const widths = headers.map((header, column) => Math.max(header.length, ...rows.map((row) => row[column]?.length ?? 0)));
+  const formatRow = (row) => row.map((value, column) => column === row.length - 1 ? value : value.padEnd(widths[column] ?? value.length)).join("  ");
+  const separator = widths.map((width) => "-".repeat(width)).join("  ");
+  return `${[formatRow(headers), separator, ...rows.map(formatRow)].join("\n")}
+`;
+}
 function summarizeEnvData(data) {
-  const summary = {};
-  for (const target of ["backend", "frontend"]) {
-    const entries = data[target];
-    if (!entries) continue;
-    summary[target] = Object.fromEntries(
-      Object.entries(entries).sort(([left], [right]) => left.localeCompare(right)).map(([name, env]) => [
-        name,
-        {
-          optional: env.optional ?? false,
-          description: env.description,
-          hasValue: env.value !== null
-        }
-      ])
-    );
-  }
-  return summary;
+  return Object.fromEntries(
+    Object.entries(data).sort(([left], [right]) => left.localeCompare(right)).map(([name, env]) => [
+      name,
+      {
+        optional: env.optional ?? false,
+        description: env.description,
+        hasValue: env.value !== null
+      }
+    ])
+  );
 }
 function renderEnvSummary(data) {
   const lines = [];
-  for (const target of ["backend", "frontend"]) {
-    const entries = Object.entries(data[target] ?? {});
-    if (entries.length === 0) continue;
-    if (lines.length > 0) lines.push("");
-    lines.push(`${target}:`);
-    for (const [name, env] of entries) {
-      lines.push(`  ${name}  ${env.hasValue ? "set" : "missing"}  ${env.optional ? "optional" : "required"}  ${env.description}`);
-    }
+  for (const [name, env] of Object.entries(data)) {
+    lines.push(`${name}  ${env.hasValue ? "set" : "missing"}  ${env.optional ? "optional" : "required"}  ${env.description}`);
   }
   return lines.length > 0 ? `${lines.join("\n")}
 ` : "No environment variables declared.\n";
@@ -900,7 +966,7 @@ function renderEnvSetResult(result) {
   if (result.skippedExisting.length > 0) lines.push(`Skipped ${result.skippedExisting.length} existing value(s).`);
   if (result.skippedEmpty.length > 0) lines.push(`Skipped ${result.skippedEmpty.length} empty value(s).`);
   if (result.updated.length > 0) {
-    lines.push(...result.updated.map(({ target, name }) => `  ${target}/${name}`));
+    lines.push(...result.updated.map(({ name }) => `  ${name}`));
   }
   return `${lines.join("\n")}
 `;
@@ -913,10 +979,10 @@ async function setBranchEnvs(client, projectRef, branchName, args) {
     if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(name)) {
       throw new Error(`Invalid environment variable name in dotenv file: ${name}`);
     }
-    return { target: options.target, name, value };
+    return { name, value };
   }) : options.assignments.map(parseEnvAssignment);
   const uniqueAssignments = /* @__PURE__ */ new Map();
-  for (const assignment of assignments) uniqueAssignments.set(`${assignment.target}/${assignment.name}`, assignment);
+  for (const assignment of assignments) uniqueAssignments.set(assignment.name, assignment);
   const update = {};
   const result = {
     success: true,
@@ -929,12 +995,12 @@ async function setBranchEnvs(client, projectRef, branchName, args) {
   const missingDescriptions = [];
   const importedDescription = options.fromEnvFile ? `Imported from ${path.basename(options.fromEnvFile)}.` : void 0;
   for (const assignment of uniqueAssignments.values()) {
-    const identity = { target: assignment.target, name: assignment.name };
+    const identity = { name: assignment.name };
     if (!options.includeEmpty && assignment.value.length === 0) {
       result.skippedEmpty.push(identity);
       continue;
     }
-    const existing = current[assignment.target]?.[assignment.name];
+    const existing = current[assignment.name];
     if (options.onlyMissing && existing?.value !== null && existing?.value !== void 0) {
       result.skippedExisting.push(identity);
       continue;
@@ -944,9 +1010,8 @@ async function setBranchEnvs(client, projectRef, branchName, args) {
       missingDescriptions.push(identity);
       continue;
     }
-    const targetUpdate = update[assignment.target] ??= {};
     const optional = options.optional ?? existing?.optional;
-    targetUpdate[assignment.name] = {
+    update[assignment.name] = {
       description,
       value: assignment.value,
       ...optional === void 0 ? {} : { optional }
@@ -954,9 +1019,7 @@ async function setBranchEnvs(client, projectRef, branchName, args) {
     result.updated.push(identity);
   }
   if (missingDescriptions.length > 0) {
-    throw new Error(
-      `--description is required when declaring new envs with -e: ${missingDescriptions.map(({ target, name }) => `${target}/${name}`).join(", ")}`
-    );
+    throw new Error(`--description is required when declaring new envs with -e: ${missingDescriptions.map(({ name }) => name).join(", ")}`);
   }
   if (result.updated.length > 0) {
     await client.projects.env.update(project.id, branchName, update);
@@ -1121,6 +1184,17 @@ async function executeR5dctlCommand(client, json, args) {
     write(result, "API key revoked.\n");
     return;
   }
+  if (first === "ps" && second === "list") {
+    const processes = await client.processes.list(parsePsListArgs(args.slice(2)));
+    write(processes, renderProcessList(processes));
+    return;
+  }
+  if (first === "ps" && second === "stop") {
+    const process2 = await client.processes.stop(requireValue(args[2], "Missing process run id"));
+    write(process2, `Stopped process ${process2.runId}: ${process2.command}
+`);
+    return;
+  }
   if (first === "projects" && second === "list" || first === "get" && second === "projects") {
     const projects = await client.projects.list();
     write(projects, renderProjectList(projects));
@@ -1316,6 +1390,12 @@ function resolveCommandExecution(options, rest) {
     throw new Error("Missing command");
   }
   const commandArgs = normalizedRest.slice(1);
+  if (command === "ps" && commandArgs.length === 0) {
+    return {
+      kind: "cli-help",
+      text: PS_HELP_TEXT
+    };
+  }
   if (trailingHelp) {
     const cliOnlyHelp = findCliOnlyCommandHelp(normalizedRest);
     if (cliOnlyHelp) {
@@ -1389,6 +1469,36 @@ function resolveCommandExecution(options, rest) {
     }
     throw new Error("Unknown auth command");
   }
+  if (command === "ps") {
+    const subcommand = commandArgs[0];
+    if (subcommand === "list") {
+      const commandFilters = parsePsListArgs(commandArgs.slice(1));
+      const filters = {
+        ...commandFilters,
+        ...options.project ? { project: options.project } : {},
+        ...options.branch ? { branch: options.branch } : {},
+        ...options.session ? { session: options.session } : {}
+      };
+      const pluginArgs = ["ps", "list"];
+      for (const [flag, value] of [
+        ["--project", filters.project],
+        ["--branch", filters.branch],
+        ["--session", filters.session],
+        ["--worker", filters.worker]
+      ]) {
+        if (value) pluginArgs.push(flag, value);
+      }
+      return { kind: "plugin", pluginArgs };
+    }
+    if (subcommand === "stop") {
+      const runId = requireValue(commandArgs[1], "Missing process run id");
+      if (commandArgs.length > 2) {
+        throw new Error(`Unexpected ps stop value: ${commandArgs[2]}`);
+      }
+      return { kind: "plugin", pluginArgs: ["ps", "stop", runId] };
+    }
+    throw new Error(`Unknown ps command: ${subcommand ?? ""}`.trim());
+  }
   if (command === "get") {
     const target = commandArgs[0];
     if (target === "projects") {
@@ -1774,6 +1884,7 @@ async function main(argv = process.argv.slice(2)) {
   }
 }
 export {
+  formatProcessAge,
   getCliHelpText,
   getR5dctlVersion,
   main,
@@ -1782,10 +1893,12 @@ export {
   parseEnvFlags,
   parseGlobalArgs,
   parsePromptArgs,
+  parsePsListArgs,
   parseSetEnvArgs,
   parseShellArgs,
   readDotenvFile,
   renderConversationResponse,
+  renderProcessList,
   resolveCommandExecution,
   runR5dctlCli,
   summarizeEnvData

package/dist/mjs/package.json

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

package/dist/types/cli.d.ts

@@ -1,4 +1,4 @@
-import { type R5dctlConversationRenderOptions, type R5dctlConversationResponse, type R5dctlEnvData, type R5dctlEnvTarget, type ChatMode, type ModelTier } from "@ricsam/r5d-api";
+import { type R5dctlConversationRenderOptions, type R5dctlConversationResponse, type R5dctlEnvData, type R5dctlProcessListInput, type R5dctlProcessRun, type ChatMode, type ModelTier } from "@ricsam/r5d-api";
 export type GlobalOptions = {
     baseUrl?: string;
     json: boolean;
@@ -44,7 +44,6 @@ export declare function parseAnswerFlags(args: string[]): string[];
 export type SetEnvOptions = {
     assignments: string[];
     fromEnvFile?: string;
-    target: R5dctlEnvTarget;
     description?: string;
     optional?: boolean;
     onlyMissing: boolean;
@@ -61,11 +60,14 @@ export declare function parsePromptArgs(args: string[]): {
 export declare function parseShellArgs(args: string[]): {
     command?: string;
 };
-export type EnvSummaryData = Partial<Record<R5dctlEnvTarget, Record<string, {
+export declare function parsePsListArgs(args: string[]): R5dctlProcessListInput;
+export declare function formatProcessAge(startedAt: string, nowMs?: number): string;
+export declare function renderProcessList(processes: R5dctlProcessRun[], nowMs?: number): string;
+export type EnvSummaryData = Record<string, {
     optional: boolean;
     description: string;
     hasValue: boolean;
-}>>>;
+}>;
 export declare function summarizeEnvData(data: R5dctlEnvData): EnvSummaryData;
 export declare function parseConversationRenderArgs(args: string[]): ConversationRenderOptions;
 export declare function renderConversationResponse(read: R5dctlConversationResponse): string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ricsam/r5dctl",
-  "version": "0.0.23",
+  "version": "0.0.24",
   "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.23",
+    "@ricsam/r5d-api": "^0.0.24",
     "dotenv": "^17",
     "ws": "^8.18.3"
   },