@ricsam/r5dctl 0.0.133 → 0.0.135

package/README.md

@@ -158,13 +158,15 @@ r5dctl ps stop <run-id>
 
 `session start` creates an ordinary agent-mode chat on an explicitly selected existing worktree, or creates a named linked worktree from an explicit `worktree:<branch>` source. A new worktree is cut from the source branch's current commit; `--working-tree carry` (the default, `git switch -c` semantics) also copies the source checkout's uncommitted changes into it, while `--working-tree clean` checks out that commit only. The new session's first message states which mode applies, and the start output prints `Source` and `Working tree` lines. A clean request fails with a clear error when the selected worker predates the option, because such a worker would silently carry instead. It requires project, worker, model, and prompt and never infers them from the current shell. Start returns a durable `provisioning` handle immediately; workspace synchronization, linked-worktree creation, and prompt enqueue continue in the background and are visible through `session status`. Idempotent request retries return the same handle. Prompts return after durable enqueue. Task specialization belongs in the prompt; there are no predefined debug, explore, research, or test agents.
 
-`session prompt` works on any project session you can access, including one created in the web UI. `--delivery` decides how the prompt reaches a session whose agent is busy: `steer` (the default) lands inside the current turn right after the agent's next tool result, `queue` waits until the agent finishes the whole turn, and `force` aborts the agent's current round of tool calls and continues from the prompt instead. An idle session starts a new generation whatever the delivery, and a steer queued while the session was idle with an unfinished turn is still heard by the generation that resumes it. The response's `Prompt:` line reports `started`, `steered`, `queued`, or `forced`. `session stop` returns as soon as the agent run is stopped; the stopped worktree's workspace Git synchronization finishes asynchronously behind the response.
+`session prompt` works on any project session you can access, including one created in the web UI. `--delivery` decides how the prompt reaches a session whose agent is busy: `steer` (the default) lands inside the current turn right after the agent's next tool result, `queue` waits until the agent finishes the whole turn, and `force` aborts the agent's current round of tool calls and continues from the prompt instead. An idle conversation can start a new generation, but an unfinished turn may still require an explicit user continuation, an interactive answer, worker recovery, or confirmation of interrupted tool replay. A peer prompt never grants that authority. Prompt and answer responses include `messageDelivery: { messageId, queueId, status, blocker }`; `status` distinguishes `blocked` from ordinary `queued`, `steered`, `starting`, `started`, or `forced` delivery. The original message ID and current queue key let callers identify the saved input without sending it again. A blocked response does not start a generation, even when the command exits successfully. Continuation blockers retain the accepted input; `superseded_message` instead identifies a discarded obsolete notice, and `message_already_processed` identifies input already recorded in the conversation.
+
+For `pending_tool_replay`, inspect the named tools and current files before deciding whether their actions can safely be repeated. To continue without replaying the interrupted round, an authorized user can use **Force now** on an existing queued message in the session UI. Dispatch the earliest urgent queued message first so later urgent messages retain their order. Force changes the active conversation branch; it does not undo filesystem effects. Do not send another force prompt to replace an already queued continuation. `session stop` returns as soon as the agent run is stopped; the stopped worktree's workspace Git synchronization finishes asynchronously behind the response.
 
 Use the optional `--sender "Authentication review"` flag to display a title above the usual message bubble. Agent shells expose `R5D_SESSION_NAME`, refreshed at each command start from the session name (or its ID until named), so agents can pass `--sender "$R5D_SESSION_NAME"`. The sender is a caller-supplied label; omitting the flag sends no title and leaves the message body unchanged.
 
 For messages to an active session, explicitly use `--delivery steer` for coordination such as merge notices, requests to pause or avoid files, blockers, corrections, and handoff or resume notices. Use `--delivery force` when its current tool round must be interrupted. Reserve `--delivery queue` for work intentionally deferred until the entire current turn ends; even an FYI needs steering when it affects current work. These rules apply equally to peers, parents, and children.
 
-Delivery is not acknowledgment. If a merge or shared-checkout change depends on another session pausing edits, send the pause request separately, wait for its explicit reply, and recheck the working tree before proceeding. `Prompt: queued` cannot establish that coordination, and even `steered` or `forced` does not prove the agent has read or acted on the request. Reply to coordination requests and send resume notices with `--delivery steer`.
+Delivery is not acknowledgment. If a merge or shared-checkout change depends on another session pausing edits, send the pause request separately, wait for its explicit reply, and recheck the working tree before proceeding. `Delivery: queued` or `blocked` cannot establish that coordination, and even `steered` or `forced` does not prove the agent has read or acted on the request. Reply to coordination requests and send resume notices with `--delivery steer`.
 
 `get sessions` lists a project's sessions, newest first, and appends each session's live state (`running`, `stopping`, `paused`, `provisioning`, `queued`, or `idle`) and how long ago its conversation last advanced (`running, last active 12s ago`). Several sessions can work in the same branch checkout at once (task chips, shared-mode sub-agents, sessions the user starts), so run it with `--branch` before relying on a working tree or reviewing what changed in it. A server that predates the fields prints the id, branch, and name only.
 

package/dist/cjs/cli.cjs

@@ -189,7 +189,8 @@ const SESSION_RUN_HELP_TEXT = [
   "",
   "Create, inspect, resume, and stop ordinary agent sessions.",
   "prompt reaches a busy session by --delivery: steer (default) lands after the agent's next tool result,",
-  "queue waits for the current turn to finish, force replaces the agent's current tool round. An idle session starts a new generation either way.",
+  "queue waits for the current turn to finish; force replaces the current tool round. Idle unfinished sessions may still require a user continuation.",
+  "Blocked delivery does not start a generation: inspect its reason and original message/queue ID. Use the session UI for Resume or queued Force now.",
   "Send only messages that need action: grants, releases, blockers, corrections, pause/resume, questions, and completion reports;",
   "batch progress and waiting reports into the update the recipient asked for. Every steer wakes a waiting recipient for a full turn.",
   "Use force only when the current tool round must be interrupted; queue is only for a follow-up task deliberately deferred until the turn ends.",
@@ -347,7 +348,7 @@ const SHARED_HELP_ENTRIES = [
   {
     section: "sessions",
     usage: 'session prompt --worker <label> --mode <mode> --model <tier> [--delivery queue|steer|force] [--sender <name>] <session-id> "<prompt>"',
-    description: "Prompt a session: steer into the current turn after the next tool result (default), queue a deliberately deferred follow-up behind the turn, or force in place of the current tool round; an idle session starts a new generation. Send only messages that need action; the recipient sees the sender's verified session id, and --sender only adds a display title."
+    description: "Prompt a session: steer after the next tool result (default), queue a deferred follow-up, or force in place of the current tool round. An idle unfinished session may require explicit continuation or confirmation of interrupted tools. Blocked delivery reports the saved message/queue ID and reason; inspect the existing queue in the session UI instead of sending duplicates. The recipient sees the verified sender session id; --sender only adds a display title."
   },
   {
     section: "sessions",
@@ -523,10 +524,14 @@ function renderCliOnlyCommandHelp(entry) {
 `;
 }
 function renderSharedCommandHelp(pathSegments) {
-  const entry = SHARED_HELP_ENTRIES.map((candidate) => ({
-    candidate,
-    usageSegments: candidate.usage.split(" ").map((segment) => segment.replace(/^\[/, "").replace(/\]$/, "")).filter((segment) => !segment.startsWith("-") && !segment.includes("<") && !segment.startsWith("["))
-  })).filter(
+  const entry = SHARED_HELP_ENTRIES.map((candidate) => {
+    const usageSegments = [];
+    for (const segment of candidate.usage.split(/\s+/)) {
+      if (/^[a-z][a-z-]*$/.test(segment)) usageSegments.push(segment);
+      else if (usageSegments.length > 0) break;
+    }
+    return { candidate, usageSegments };
+  }).filter(
     ({ usageSegments }) => usageSegments.length <= pathSegments.length && usageSegments.every((segment, index) => segment === pathSegments[index])
   ).sort((left, right) => right.usageSegments.length - left.usageSegments.length)[0]?.candidate;
   if (!entry) {
@@ -2331,6 +2336,49 @@ function formatChildSessionsLine(session) {
   if (!Number.isInteger(total) || !Number.isInteger(active) || total <= 0 || active < 0) return void 0;
   return `Child sessions: ${active} active of ${total}`;
 }
+function formatMessageDelivery(delivery) {
+  const blockedDescription = delivery.blocker?.reason === "superseded_message" ? "superseded; not accepted" : "accepted; not started";
+  const lines = [
+    `Message: ${delivery.messageId}`,
+    ...delivery.queueId ? [`Queue item: ${delivery.queueId}`] : [],
+    `Delivery: ${delivery.status === "blocked" ? `blocked (${blockedDescription})` : delivery.status}`
+  ];
+  if (delivery.status === "recorded") lines.push("This message is already recorded; this retry did not request another generation.");
+  const blocker = delivery.blocker;
+  if (!blocker) return lines;
+  switch (blocker.reason) {
+    case "pending_tool_replay":
+      lines.push(`Blocked by: interrupted tools require replay confirmation (${blocker.pendingToolNames.join(", ")}).`);
+      break;
+    case "manual_stop":
+      lines.push("Blocked by: explicit Stop. An authorized user must resume the session in the UI.");
+      break;
+    case "worker_recovery":
+      lines.push("Blocked by: worker recovery. Wait for recovery, then resume the session explicitly.");
+      break;
+    case "interactive_input":
+      lines.push(
+        `Blocked by: pending ${[blocker.questionIds.length ? `questions (${blocker.questionIds.join(", ")})` : "", blocker.environmentRequest ? "environment request" : ""].filter(Boolean).join(" and ") || "interactive input"}. Answer it in the session UI.`
+      );
+      break;
+    case "explicit_continuation_required":
+      lines.push("Blocked by: this unfinished turn needs an explicit user continuation; a peer message cannot start it.");
+      break;
+    case "workspace_remediation":
+      lines.push("Blocked by: workspace remediation. The saved input waits for that recovery.");
+      break;
+    case "superseded_message":
+      lines.push("The source outcome changed; this superseded notice cannot start a generation.");
+      break;
+  }
+  if (delivery.queueId && ["pending_tool_replay", "explicit_continuation_required"].includes(blocker.reason)) {
+    lines.push(
+      "To replace the interrupted round without replaying it, use Force now on the earliest urgent queued message in the session UI. Later urgent messages retain their order.",
+      "Inspect current files before retrying interrupted edits. Use the existing queue item; do not send the prompt again."
+    );
+  }
+  return lines;
+}
 function renderSessionRunStatus(session) {
   const status = formatStatusValue(session.status) ?? "unknown";
   const lines = [`Session: ${responseString(session, "sessionId") ?? "(unknown)"}`, `Status: ${status}`];
@@ -2338,8 +2386,7 @@ function renderSessionRunStatus(session) {
   if (runStatus) lines.push(`Run: ${runStatus}`);
   const provisioningQueue = formatProvisioningQueueLine(session);
   if (provisioningQueue) lines.push(provisioningQueue);
-  const promptDisposition = responseString(session, "promptDisposition");
-  if (promptDisposition) lines.push(`Prompt: ${promptDisposition}`);
+  if (session.messageDelivery) lines.push(...formatMessageDelivery(session.messageDelivery));
   const branch = responseString(session, "branchName");
   if (branch) lines.push(`Worktree: ${branch}`);
   pushWorktreeOriginLines(lines, session);

package/dist/cjs/package.json

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

package/dist/mjs/cli.mjs

@@ -79,7 +79,8 @@ const SESSION_RUN_HELP_TEXT = [
   "",
   "Create, inspect, resume, and stop ordinary agent sessions.",
   "prompt reaches a busy session by --delivery: steer (default) lands after the agent's next tool result,",
-  "queue waits for the current turn to finish, force replaces the agent's current tool round. An idle session starts a new generation either way.",
+  "queue waits for the current turn to finish; force replaces the current tool round. Idle unfinished sessions may still require a user continuation.",
+  "Blocked delivery does not start a generation: inspect its reason and original message/queue ID. Use the session UI for Resume or queued Force now.",
   "Send only messages that need action: grants, releases, blockers, corrections, pause/resume, questions, and completion reports;",
   "batch progress and waiting reports into the update the recipient asked for. Every steer wakes a waiting recipient for a full turn.",
   "Use force only when the current tool round must be interrupted; queue is only for a follow-up task deliberately deferred until the turn ends.",
@@ -237,7 +238,7 @@ const SHARED_HELP_ENTRIES = [
   {
     section: "sessions",
     usage: 'session prompt --worker <label> --mode <mode> --model <tier> [--delivery queue|steer|force] [--sender <name>] <session-id> "<prompt>"',
-    description: "Prompt a session: steer into the current turn after the next tool result (default), queue a deliberately deferred follow-up behind the turn, or force in place of the current tool round; an idle session starts a new generation. Send only messages that need action; the recipient sees the sender's verified session id, and --sender only adds a display title."
+    description: "Prompt a session: steer after the next tool result (default), queue a deferred follow-up, or force in place of the current tool round. An idle unfinished session may require explicit continuation or confirmation of interrupted tools. Blocked delivery reports the saved message/queue ID and reason; inspect the existing queue in the session UI instead of sending duplicates. The recipient sees the verified sender session id; --sender only adds a display title."
   },
   {
     section: "sessions",
@@ -413,10 +414,14 @@ function renderCliOnlyCommandHelp(entry) {
 `;
 }
 function renderSharedCommandHelp(pathSegments) {
-  const entry = SHARED_HELP_ENTRIES.map((candidate) => ({
-    candidate,
-    usageSegments: candidate.usage.split(" ").map((segment) => segment.replace(/^\[/, "").replace(/\]$/, "")).filter((segment) => !segment.startsWith("-") && !segment.includes("<") && !segment.startsWith("["))
-  })).filter(
+  const entry = SHARED_HELP_ENTRIES.map((candidate) => {
+    const usageSegments = [];
+    for (const segment of candidate.usage.split(/\s+/)) {
+      if (/^[a-z][a-z-]*$/.test(segment)) usageSegments.push(segment);
+      else if (usageSegments.length > 0) break;
+    }
+    return { candidate, usageSegments };
+  }).filter(
     ({ usageSegments }) => usageSegments.length <= pathSegments.length && usageSegments.every((segment, index) => segment === pathSegments[index])
   ).sort((left, right) => right.usageSegments.length - left.usageSegments.length)[0]?.candidate;
   if (!entry) {
@@ -2221,6 +2226,49 @@ function formatChildSessionsLine(session) {
   if (!Number.isInteger(total) || !Number.isInteger(active) || total <= 0 || active < 0) return void 0;
   return `Child sessions: ${active} active of ${total}`;
 }
+function formatMessageDelivery(delivery) {
+  const blockedDescription = delivery.blocker?.reason === "superseded_message" ? "superseded; not accepted" : "accepted; not started";
+  const lines = [
+    `Message: ${delivery.messageId}`,
+    ...delivery.queueId ? [`Queue item: ${delivery.queueId}`] : [],
+    `Delivery: ${delivery.status === "blocked" ? `blocked (${blockedDescription})` : delivery.status}`
+  ];
+  if (delivery.status === "recorded") lines.push("This message is already recorded; this retry did not request another generation.");
+  const blocker = delivery.blocker;
+  if (!blocker) return lines;
+  switch (blocker.reason) {
+    case "pending_tool_replay":
+      lines.push(`Blocked by: interrupted tools require replay confirmation (${blocker.pendingToolNames.join(", ")}).`);
+      break;
+    case "manual_stop":
+      lines.push("Blocked by: explicit Stop. An authorized user must resume the session in the UI.");
+      break;
+    case "worker_recovery":
+      lines.push("Blocked by: worker recovery. Wait for recovery, then resume the session explicitly.");
+      break;
+    case "interactive_input":
+      lines.push(
+        `Blocked by: pending ${[blocker.questionIds.length ? `questions (${blocker.questionIds.join(", ")})` : "", blocker.environmentRequest ? "environment request" : ""].filter(Boolean).join(" and ") || "interactive input"}. Answer it in the session UI.`
+      );
+      break;
+    case "explicit_continuation_required":
+      lines.push("Blocked by: this unfinished turn needs an explicit user continuation; a peer message cannot start it.");
+      break;
+    case "workspace_remediation":
+      lines.push("Blocked by: workspace remediation. The saved input waits for that recovery.");
+      break;
+    case "superseded_message":
+      lines.push("The source outcome changed; this superseded notice cannot start a generation.");
+      break;
+  }
+  if (delivery.queueId && ["pending_tool_replay", "explicit_continuation_required"].includes(blocker.reason)) {
+    lines.push(
+      "To replace the interrupted round without replaying it, use Force now on the earliest urgent queued message in the session UI. Later urgent messages retain their order.",
+      "Inspect current files before retrying interrupted edits. Use the existing queue item; do not send the prompt again."
+    );
+  }
+  return lines;
+}
 function renderSessionRunStatus(session) {
   const status = formatStatusValue(session.status) ?? "unknown";
   const lines = [`Session: ${responseString(session, "sessionId") ?? "(unknown)"}`, `Status: ${status}`];
@@ -2228,8 +2276,7 @@ function renderSessionRunStatus(session) {
   if (runStatus) lines.push(`Run: ${runStatus}`);
   const provisioningQueue = formatProvisioningQueueLine(session);
   if (provisioningQueue) lines.push(provisioningQueue);
-  const promptDisposition = responseString(session, "promptDisposition");
-  if (promptDisposition) lines.push(`Prompt: ${promptDisposition}`);
+  if (session.messageDelivery) lines.push(...formatMessageDelivery(session.messageDelivery));
   const branch = responseString(session, "branchName");
   if (branch) lines.push(`Worktree: ${branch}`);
   pushWorktreeOriginLines(lines, session);

package/dist/mjs/package.json

@@ -1,5 +1,5 @@
 {
   "name": "@ricsam/r5dctl",
-  "version": "0.0.133",
+  "version": "0.0.135",
   "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 R5dctlProcessInspection, type R5dctlProcessListInput, type R5dctlProcessLog, type R5dctlProcessRun, type R5dctlWorkerCapacityReport, type R5dctlBranch, type R5dctlBranchDeletionStatus, type R5dctlBranchDescription, type R5dctlBranchOperation, type R5dctlSessionSummary, type R5dctlCheckoutPathResponse, type R5dctlSessionClaim, type R5dctlSessionClaimListResponse, type R5dctlSessionClaimScope, 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 R5dctlProcessInspection, type R5dctlProcessListInput, type R5dctlProcessLog, type R5dctlProcessRun, type R5dctlWorkerCapacityReport, type R5dctlBranch, type R5dctlBranchDeletionStatus, type R5dctlBranchDescription, type R5dctlBranchOperation, type R5dctlSessionSummary, type R5dctlCheckoutPathResponse, type R5dctlSessionClaim, type R5dctlSessionClaimListResponse, type R5dctlSessionClaimScope, type R5dctlSessionEvent, type R5dctlSessionStartInput, type R5dctlWorkspaceStatus, type R5dctlWorkspaceSyncResult, type R5dctlWorkingTreeMode, type R5dctlWorktreeSource, type R5dctlPromptDelivery, type R5dctlMessageDelivery, type R5dctlSessionMode, type ChatMode, type ModelTier } from "@ricsam/r5d-api";
 import { type AccountCommand } from "./account";
 export type GlobalOptions = {
     baseUrl?: string;
@@ -359,7 +359,7 @@ export type R5dctlCommandResponse = {
     /** Legacy fields older servers still send; never rendered because a reported hash goes stale. */
     headCommit?: string | null;
     headCommitError?: string;
-    promptDisposition?: string;
+    messageDelivery?: R5dctlMessageDelivery;
     error?: string;
     summary?: string;
     diffSummary?: string;

package/package.json

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