@ricsam/r5dctl 0.0.122 → 0.0.124

package/README.md

@@ -155,7 +155,9 @@ Add `-f`/`--follow`/`--watch` to `session start` to poll the provisioning handle
 
 `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.
+`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. The `LANE` column names the worker command lane each run holds (`general`, `utility`, or `control`) or waits for (`queued:general`), from the worker's latest capacity report; `-` means the worker did not report the run. `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.
+
+A managed worker runs two general shells at a time; a third waits up to 60 seconds and then fails with "command capacity is busy". Coordination does not compete for those slots: when an agent shell runs one plain `r5dctl` coordination command (`ps list`, `ps stop`, `workspace status`, `session status|stop|prompt|claim|claims|process-log`, `describe …`, `get …`, `sessions recent`, the `conversation` read forms, `create|update|delete session`, `answer-questions`, `answer-env-request`) with plain or simply quoted arguments, the platform runs it in a reserved control lane: two small slots, no shell, a 120-second limit. Shell operators, pipes, redirections, `$` expansions, environment assignments, wrappers, paths to r5dctl, `--`, `--follow`, and credential or endpoint flags make it an ordinary shell command again. `workspace status` prints each worker's lane totals, holders, and queue.
 
 `k8s usage` shows current and rolling CPU and memory usage for every workload container in your managed vCluster. The default window is `24h`; pass `--window 7d` for seven days. Filter with `--namespace`, `--workload`, or `--container`; a workload may be identified by name, `namespace/name`, or Kubernetes UID. Human-readable output shows current totals across sampled replicas and the selected window's maximum. Global `--json` includes min/max summaries, the complete five-minute history envelope, per-pod series, coverage, and freshness metadata.
 

package/dist/cjs/cli.cjs

@@ -43,6 +43,7 @@ __export(cli_exports, {
   formatK8sCpu: () => formatK8sCpu,
   formatK8sMemory: () => formatK8sMemory,
   formatProcessAge: () => formatProcessAge,
+  formatProcessLane: () => formatProcessLane,
   getCliHelpText: () => getCliHelpText,
   getK8sUsageState: () => getK8sUsageState,
   getProjectEnvValue: () => getProjectEnvValue,
@@ -100,6 +101,7 @@ __export(cli_exports, {
   renderSessionList: () => renderSessionList,
   renderSessionRunStart: () => renderSessionRunStart,
   renderSessionRunStatus: () => renderSessionRunStatus,
+  renderWorkerCapacity: () => renderWorkerCapacity,
   renderWorkspaceStatus: () => renderWorkspaceStatus,
   renderWorkspaceSync: () => renderWorkspaceSync,
   resolveCommandExecution: () => resolveCommandExecution,
@@ -1890,6 +1892,23 @@ function renderRecentSessionList(sessions) {
   return `${sessions.map((session) => `${session.id}  ${session.projectPath}/${session.branchName}  ${session.name ?? "(unnamed)"}`).join("\n")}
 `;
 }
+function renderWorkerCapacity(workerLabel, capacity) {
+  if (!capacity) return [`Command capacity on ${workerLabel}: not reported yet`];
+  if (!capacity.bounded) return [`Command capacity on ${workerLabel}: unbounded (no managed launcher)`];
+  const describeLane = (lane) => {
+    const report = capacity.lanes[lane];
+    const slots = report.slots === null ? "?" : String(report.slots);
+    const holders = report.active.map((entry) => `${entry.id}${entry.sessionId ? ` (session ${entry.sessionId})` : ""}`);
+    const queued = report.queued.map((entry) => `${entry.id}${entry.sessionId ? ` (session ${entry.sessionId})` : ""}`);
+    return `  ${lane}: ${report.active.length}/${slots} busy${holders.length ? `, held by ${holders.join(", ")}` : ""}${queued.length ? `; queued: ${queued.join(", ")}` : ""}`;
+  };
+  return [
+    `Command capacity on ${workerLabel} (reported ${capacity.reportedAt}):`,
+    describeLane("general"),
+    describeLane("utility"),
+    `${describeLane("control")}${capacity.controlRuntimeMs !== null ? ` (plain r5dctl coordination, ${Math.round(capacity.controlRuntimeMs / 1e3)}s limit)` : ""}`
+  ];
+}
 function renderWorkspaceStatus(status) {
   const lines = [
     `Workspace HEAD: ${status.head ?? "(not initialized)"}`,
@@ -1897,7 +1916,8 @@ function renderWorkspaceStatus(status) {
     `Remediation: ${status.incident ? `${status.incident.kind} ${status.incident.status} (${status.incident.id}) on ${status.incident.originWorkerLabel}` : "none"}`,
     ...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 ?? [])
+      ...renderMissingCheckouts(worker.workerLabel, worker.missingCheckouts ?? []),
+      ...renderWorkerCapacity(worker.workerLabel, worker.capacity)
     ])
   ];
   if (status.latestSync?.missingCheckouts?.length && !status.workers.some((worker) => worker.missingCheckouts?.length)) {
@@ -2131,10 +2151,11 @@ function renderProcessList(processes, nowMs = Date.now()) {
   if (processes.length === 0) {
     return "No active processes.\n";
   }
-  const headers = ["RUN ID", "STATUS", "AGE", "WORKER", "TARGET", "SCOPE", "SESSION", "COMMAND"];
+  const headers = ["RUN ID", "STATUS", "LANE", "AGE", "WORKER", "TARGET", "SCOPE", "SESSION", "COMMAND"];
   const rows = processes.map((process2) => [
     process2.runId,
     process2.status,
+    formatProcessLane(process2),
     formatProcessAge(process2.startedAt, nowMs),
     process2.workerLabel,
     process2.projectPath,
@@ -2148,6 +2169,10 @@ function renderProcessList(processes, nowMs = Date.now()) {
   return `${[formatRow(headers), separator, ...rows.map(formatRow)].join("\n")}
 `;
 }
+function formatProcessLane(process2) {
+  if (process2.admission) return process2.admission.phase === "queued" ? `queued:${process2.admission.lane}` : process2.admission.lane;
+  return process2.commandClass ?? "-";
+}
 function renderProcessHistory(processes, nowMs = Date.now()) {
   return processes.length === 0 ? "No process history.\n" : renderProcessList(processes, nowMs);
 }
@@ -2185,6 +2210,7 @@ function renderProcessInspection(process2) {
     `Worker: ${process2.workerLabel} (${process2.platform ?? "unknown"}/${process2.arch ?? "unknown"})`,
     `Target: ${process2.projectPath} ${process2.target.type === "project" ? process2.target.branchName : process2.target.rootProfile}`,
     `Session: ${process2.sessionId}`,
+    `Lane: ${formatProcessLane(process2)}${process2.admission ? ` since ${process2.admission.since}` : ""}`,
     `Command: ${process2.command}`,
     `Argv: ${JSON.stringify(process2.argv)}`,
     `CWD: ${process2.cwd ?? "(execution root)"}`,
@@ -4046,6 +4072,7 @@ async function main(argv = process.argv.slice(2)) {
   formatK8sCpu,
   formatK8sMemory,
   formatProcessAge,
+  formatProcessLane,
   getCliHelpText,
   getK8sUsageState,
   getProjectEnvValue,
@@ -4103,6 +4130,7 @@ async function main(argv = process.argv.slice(2)) {
   renderSessionList,
   renderSessionRunStart,
   renderSessionRunStatus,
+  renderWorkerCapacity,
   renderWorkspaceStatus,
   renderWorkspaceSync,
   resolveCommandExecution,

package/dist/cjs/package.json

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

package/dist/mjs/cli.mjs

@@ -1781,6 +1781,23 @@ function renderRecentSessionList(sessions) {
   return `${sessions.map((session) => `${session.id}  ${session.projectPath}/${session.branchName}  ${session.name ?? "(unnamed)"}`).join("\n")}
 `;
 }
+function renderWorkerCapacity(workerLabel, capacity) {
+  if (!capacity) return [`Command capacity on ${workerLabel}: not reported yet`];
+  if (!capacity.bounded) return [`Command capacity on ${workerLabel}: unbounded (no managed launcher)`];
+  const describeLane = (lane) => {
+    const report = capacity.lanes[lane];
+    const slots = report.slots === null ? "?" : String(report.slots);
+    const holders = report.active.map((entry) => `${entry.id}${entry.sessionId ? ` (session ${entry.sessionId})` : ""}`);
+    const queued = report.queued.map((entry) => `${entry.id}${entry.sessionId ? ` (session ${entry.sessionId})` : ""}`);
+    return `  ${lane}: ${report.active.length}/${slots} busy${holders.length ? `, held by ${holders.join(", ")}` : ""}${queued.length ? `; queued: ${queued.join(", ")}` : ""}`;
+  };
+  return [
+    `Command capacity on ${workerLabel} (reported ${capacity.reportedAt}):`,
+    describeLane("general"),
+    describeLane("utility"),
+    `${describeLane("control")}${capacity.controlRuntimeMs !== null ? ` (plain r5dctl coordination, ${Math.round(capacity.controlRuntimeMs / 1e3)}s limit)` : ""}`
+  ];
+}
 function renderWorkspaceStatus(status) {
   const lines = [
     `Workspace HEAD: ${status.head ?? "(not initialized)"}`,
@@ -1788,7 +1805,8 @@ function renderWorkspaceStatus(status) {
     `Remediation: ${status.incident ? `${status.incident.kind} ${status.incident.status} (${status.incident.id}) on ${status.incident.originWorkerLabel}` : "none"}`,
     ...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 ?? [])
+      ...renderMissingCheckouts(worker.workerLabel, worker.missingCheckouts ?? []),
+      ...renderWorkerCapacity(worker.workerLabel, worker.capacity)
     ])
   ];
   if (status.latestSync?.missingCheckouts?.length && !status.workers.some((worker) => worker.missingCheckouts?.length)) {
@@ -2022,10 +2040,11 @@ function renderProcessList(processes, nowMs = Date.now()) {
   if (processes.length === 0) {
     return "No active processes.\n";
   }
-  const headers = ["RUN ID", "STATUS", "AGE", "WORKER", "TARGET", "SCOPE", "SESSION", "COMMAND"];
+  const headers = ["RUN ID", "STATUS", "LANE", "AGE", "WORKER", "TARGET", "SCOPE", "SESSION", "COMMAND"];
   const rows = processes.map((process2) => [
     process2.runId,
     process2.status,
+    formatProcessLane(process2),
     formatProcessAge(process2.startedAt, nowMs),
     process2.workerLabel,
     process2.projectPath,
@@ -2039,6 +2058,10 @@ function renderProcessList(processes, nowMs = Date.now()) {
   return `${[formatRow(headers), separator, ...rows.map(formatRow)].join("\n")}
 `;
 }
+function formatProcessLane(process2) {
+  if (process2.admission) return process2.admission.phase === "queued" ? `queued:${process2.admission.lane}` : process2.admission.lane;
+  return process2.commandClass ?? "-";
+}
 function renderProcessHistory(processes, nowMs = Date.now()) {
   return processes.length === 0 ? "No process history.\n" : renderProcessList(processes, nowMs);
 }
@@ -2076,6 +2099,7 @@ function renderProcessInspection(process2) {
     `Worker: ${process2.workerLabel} (${process2.platform ?? "unknown"}/${process2.arch ?? "unknown"})`,
     `Target: ${process2.projectPath} ${process2.target.type === "project" ? process2.target.branchName : process2.target.rootProfile}`,
     `Session: ${process2.sessionId}`,
+    `Lane: ${formatProcessLane(process2)}${process2.admission ? ` since ${process2.admission.since}` : ""}`,
     `Command: ${process2.command}`,
     `Argv: ${JSON.stringify(process2.argv)}`,
     `CWD: ${process2.cwd ?? "(execution root)"}`,
@@ -3936,6 +3960,7 @@ export {
   formatK8sCpu,
   formatK8sMemory,
   formatProcessAge,
+  formatProcessLane,
   getCliHelpText,
   getK8sUsageState,
   getProjectEnvValue,
@@ -3993,6 +4018,7 @@ export {
   renderSessionList,
   renderSessionRunStart,
   renderSessionRunStatus,
+  renderWorkerCapacity,
   renderWorkspaceStatus,
   renderWorkspaceSync,
   resolveCommandExecution,

package/dist/mjs/package.json

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

package/dist/types/cli.d.ts

@@ -1,4 +1,4 @@
-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 R5dctlBranchDeletionStatus, type R5dctlBranchDescription, type R5dctlBranchOperation, type R5dctlSessionSummary, type R5dctlSessionClaim, type R5dctlSessionClaimListResponse, type R5dctlSessionEvent, type R5dctlSessionStartInput, type R5dctlWorkspaceStatus, type R5dctlWorkspaceSyncResult, type R5dctlWorkingTreeMode, type R5dctlWorktreeSource, type R5dctlPromptDelivery, 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 R5dctlWorkerCapacityReport, type R5dctlBranch, type R5dctlBranchDeletionStatus, type R5dctlBranchDescription, type R5dctlBranchOperation, type R5dctlSessionSummary, type R5dctlSessionClaim, type R5dctlSessionClaimListResponse, type R5dctlSessionEvent, type R5dctlSessionStartInput, type R5dctlWorkspaceStatus, type R5dctlWorkspaceSyncResult, type R5dctlWorkingTreeMode, type R5dctlWorktreeSource, type R5dctlPromptDelivery, type R5dctlSessionMode, type ChatMode, type ModelTier } from "@ricsam/r5d-api";
 export type GlobalOptions = {
     baseUrl?: string;
     json: boolean;
@@ -278,6 +278,8 @@ export declare function advanceTransientDevicePollBackoff(intervalMs: number, tr
 };
 export declare function handleAuthLogin(client: R5dctlClient, options: GlobalOptions, commandArgs: string[], config: R5dctlConfig): Promise<void>;
 export declare function renderSessionList(sessions: R5dctlSessionSummary[], nowMs?: number): string;
+/** One line per worker naming every lane's holders and queue, so an agent can see whom to ask to free capacity. */
+export declare function renderWorkerCapacity(workerLabel: string, capacity: R5dctlWorkerCapacityReport | null | undefined): string[];
 export declare function renderWorkspaceStatus(status: R5dctlWorkspaceStatus): string;
 export declare function renderBranchList(branches: R5dctlBranch[]): string;
 export declare function renderWorkspaceSync(result: R5dctlWorkspaceSyncResult): string;
@@ -318,6 +320,8 @@ export declare function getK8sUsageState(entry: K8sUsageReport["entries"][number
 export declare function renderK8sUsageReport(report: K8sUsageReport): string;
 export declare function formatProcessAge(startedAt: string, nowMs?: number): string;
 export declare function renderProcessList(processes: R5dctlProcessRun[], nowMs?: number): string;
+/** `general`, `control`, `queued:general`, or `-` when the worker reported nothing for this run. */
+export declare function formatProcessLane(process: Pick<R5dctlProcessRun, "admission" | "commandClass">): string;
 export declare function renderProcessHistory(processes: R5dctlProcessRun[], nowMs?: number): string;
 /** Streams go to stdout under `==> name <==` headers; the selection summary is returned separately for stderr. */
 export declare function renderProcessLog(log: R5dctlProcessLog): {

package/package.json

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