@ricsam/r5dctl 0.0.66 → 0.0.67

package/README.md

@@ -75,6 +75,9 @@ r5dctl conversation inspect-node <session-id> <node-id>  # raw persisted node pl
 r5dctl conversation inspect-work <session-id> <work-id> # compact call list for one omitted turn
 r5dctl conversation inspect-work <session-id> <work-id> --summary
 r5dctl conversation inspect-work <session-id> <work-id> --full
+r5dctl conversation move-head <session-id> <node-id>     # rewind or replay the transcript; files stay put
+r5dctl conversation fork <session-id> <node-id>          # copy the branch up to a node into a new session
+r5dctl conversation fork <session-id> <node-id> --name "Retry with tests"
 r5dctl session prompt --worker <label> --mode plan --model max <session-id> "..."
 r5dctl -s <session-id> answer-questions --worker <label> --mode plan --model max -a1 "Recipe Collection" -a2 "Both Manual & AI"
 r5dctl -s <session-id> answer-env-request --worker <label> --mode agent --model max -e KEY=value --context "Generate the remaining salts"
@@ -133,6 +136,8 @@ When available, conversation rendering uses the newest complete persisted model-
 
 `conversation inspect-node` reads one exact persisted conversation node as formatted JSON. Its header includes the previous node, every direct next node, the next node on the active branch, whether the selected node is active, and the containing `work_...` ID when one is available. This allows callers that start with only a copied chat node ID to traverse nearby nodes or zoom out with `conversation inspect-work`.
 
+`conversation move-head` and `conversation fork` change the transcript and nothing else. Neither one checks out, resets, or publishes anything: worker workspaces and the canonical repository keep the state the agent left them in. `move-head` points the session at any recorded node, so it rewinds past work, replays forward again, or switches to a sibling branch; every node stays stored, which makes the move reversible. The next prompt continues from the new head, and when that head already has children the new message becomes a sibling branch. `fork` instead copies the branch ending at the chosen node into a new session on the same project branch, named after its source, leaving the original session running untouched. Both refuse hidden maintenance sessions, and `move-head` refuses while a turn is running — stop the session first.
+
 Project mode is derived from the persisted `backwardsCompatible` project setting:
 
 - `greenfield`: agent can make breaking/reset-style changes

package/dist/cjs/cli.cjs

@@ -46,6 +46,7 @@ __export(cli_exports, {
   parseAnswerEnvRequestCommandArgs: () => parseAnswerEnvRequestCommandArgs,
   parseAnswerFlags: () => parseAnswerFlags,
   parseAnswerQuestionsCommandArgs: () => parseAnswerQuestionsCommandArgs,
+  parseConversationForkArgs: () => parseConversationForkArgs,
   parseConversationRenderArgs: () => parseConversationRenderArgs,
   parseConversationWorkDetailArgs: () => parseConversationWorkDetailArgs,
   parseEnvFlags: () => parseEnvFlags,
@@ -61,6 +62,8 @@ __export(cli_exports, {
   parseSetEnvArgs: () => parseSetEnvArgs,
   parseShellArgs: () => parseShellArgs,
   readDotenvFile: () => readDotenvFile,
+  renderConversationForkResponse: () => renderConversationForkResponse,
+  renderConversationHeadResponse: () => renderConversationHeadResponse,
   renderConversationNodeResponse: () => renderConversationNodeResponse,
   renderConversationOverviewResponse: () => renderConversationOverviewResponse,
   renderConversationResponse: () => renderConversationResponse,
@@ -261,6 +264,16 @@ const SHARED_HELP_ENTRIES = [
     usage: "conversation inspect-work <session-id> <work-id> [--compact|--summary|--full]",
     description: "Inspect one turn's omitted tool work at the selected detail."
   },
+  {
+    section: "sessions",
+    usage: "conversation move-head <session-id> <node-id>",
+    description: "Rewind or replay the conversation to a node. Only the transcript moves; no files change."
+  },
+  {
+    section: "sessions",
+    usage: "conversation fork <session-id> <node-id> [--name <name>]",
+    description: "Copy the branch ending at a node into a new session, leaving the source untouched."
+  },
   {
     section: "sessions",
     usage: '-p <project> session start --worker <label> (--worktree <branch>|--new-worktree <branch> --source worktree:<branch>) --model <tier> [-f|--follow|--watch] [--tools] "<prompt>"',
@@ -2425,6 +2438,21 @@ function parseConversationWorkDetailArgs(args) {
   }
   return detail;
 }
+function parseConversationForkArgs(args) {
+  let name;
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+    if (arg !== "--name") {
+      throw new Error(`Unknown conversation fork argument: ${arg}`);
+    }
+    if (name !== void 0) {
+      throw new Error("Use --name only once");
+    }
+    index += 1;
+    name = requireValue(args[index], "Missing value for --name");
+  }
+  return name;
+}
 function renderConversationOverviewResponse(read) {
   return read.overviewText.endsWith("\n") ? read.overviewText : `${read.overviewText}
 `;
@@ -2451,6 +2479,15 @@ function renderConversationWorkResponse(read) {
   return read.workText.endsWith("\n") ? read.workText : `${read.workText}
 `;
 }
+function renderConversationHeadResponse(read) {
+  return `Conversation head moved to ${read.head} (revision ${read.revision}). Files on disk are unchanged.
+`;
+}
+function renderConversationForkResponse(read) {
+  const name = read.session.name ? ` (${read.session.name})` : "";
+  return `Forked ${read.copiedNodeCount} node(s) up to ${read.forkedFromNodeId} into session ${read.session.id}${name}.
+`;
+}
 async function executeR5dctlCommand(client, json, args) {
   const write = (data, human) => writeDataOutput(json, data, human);
   const [first, second, third] = args;
@@ -2645,6 +2682,24 @@ Sessions: ${result.sessions.length}
     write(read, renderConversationNodeResponse(read));
     return;
   }
+  if (first === "conversation" && second === "move-head") {
+    if (args.length > 4) {
+      throw new Error(`Unexpected conversation move-head argument: ${args[4]}`);
+    }
+    const sessionId = requireValue(args[2], "Missing session id");
+    const nodeId2 = requireValue(args[3], "Missing node id");
+    const read = await client.sessions.moveConversationHead(sessionId, nodeId2);
+    write(read, renderConversationHeadResponse(read));
+    return;
+  }
+  if (first === "conversation" && second === "fork") {
+    const sessionId = requireValue(args[2], "Missing session id");
+    const nodeId2 = requireValue(args[3], "Missing node id");
+    const name = parseConversationForkArgs(args.slice(4));
+    const read = await client.sessions.forkConversation(sessionId, nodeId2, name === void 0 ? {} : { name });
+    write(read, renderConversationForkResponse(read));
+    return;
+  }
   if (first === "conversation" && second === "inspect-work") {
     const sessionId = requireValue(args[2], "Missing session id");
     const workId = requireValue(args[3], "Missing work id");
@@ -3055,34 +3110,26 @@ function resolveCommandExecution(options, rest) {
         pluginArgs: ["conversation", "overview", sessionId2, ...remainingArgs]
       };
     }
-    if (subcommand === "inspect-work") {
-      const sessionId2 = options.session ?? commandArgs[1];
-      if (!sessionId2) {
-        throw new Error("Session id is required for `conversation inspect-work`");
-      }
-      const workId = options.session ? commandArgs[1] : commandArgs[2];
-      if (!workId) {
-        throw new Error("Work id is required for `conversation inspect-work`");
-      }
-      const remainingArgs = options.session ? commandArgs.slice(2) : commandArgs.slice(3);
-      return {
-        kind: "plugin",
-        pluginArgs: ["conversation", "inspect-work", sessionId2, workId, ...remainingArgs]
-      };
-    }
-    if (subcommand === "inspect-node") {
+    const targetedSubcommands = [
+      { subcommand: "inspect-work", secondIdLabel: "Work id" },
+      { subcommand: "inspect-node", secondIdLabel: "Node id" },
+      { subcommand: "move-head", secondIdLabel: "Node id" },
+      { subcommand: "fork", secondIdLabel: "Node id" }
+    ];
+    const targeted = targetedSubcommands.find((candidate) => candidate.subcommand === subcommand);
+    if (targeted) {
       const sessionId2 = options.session ?? commandArgs[1];
       if (!sessionId2) {
-        throw new Error("Session id is required for `conversation inspect-node`");
+        throw new Error(`Session id is required for \`conversation ${targeted.subcommand}\``);
       }
-      const nodeId2 = options.session ? commandArgs[1] : commandArgs[2];
-      if (!nodeId2) {
-        throw new Error("Node id is required for `conversation inspect-node`");
+      const secondId = options.session ? commandArgs[1] : commandArgs[2];
+      if (!secondId) {
+        throw new Error(`${targeted.secondIdLabel} is required for \`conversation ${targeted.subcommand}\``);
       }
       const remainingArgs = options.session ? commandArgs.slice(2) : commandArgs.slice(3);
       return {
         kind: "plugin",
-        pluginArgs: ["conversation", "inspect-node", sessionId2, nodeId2, ...remainingArgs]
+        pluginArgs: ["conversation", targeted.subcommand, sessionId2, secondId, ...remainingArgs]
       };
     }
     const sessionId = options.session;
@@ -3269,6 +3316,7 @@ async function main(argv = process.argv.slice(2)) {
   parseAnswerEnvRequestCommandArgs,
   parseAnswerFlags,
   parseAnswerQuestionsCommandArgs,
+  parseConversationForkArgs,
   parseConversationRenderArgs,
   parseConversationWorkDetailArgs,
   parseEnvFlags,
@@ -3284,6 +3332,8 @@ async function main(argv = process.argv.slice(2)) {
   parseSetEnvArgs,
   parseShellArgs,
   readDotenvFile,
+  renderConversationForkResponse,
+  renderConversationHeadResponse,
   renderConversationNodeResponse,
   renderConversationOverviewResponse,
   renderConversationResponse,

package/dist/cjs/package.json

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

package/dist/mjs/cli.mjs

@@ -180,6 +180,16 @@ const SHARED_HELP_ENTRIES = [
     usage: "conversation inspect-work <session-id> <work-id> [--compact|--summary|--full]",
     description: "Inspect one turn's omitted tool work at the selected detail."
   },
+  {
+    section: "sessions",
+    usage: "conversation move-head <session-id> <node-id>",
+    description: "Rewind or replay the conversation to a node. Only the transcript moves; no files change."
+  },
+  {
+    section: "sessions",
+    usage: "conversation fork <session-id> <node-id> [--name <name>]",
+    description: "Copy the branch ending at a node into a new session, leaving the source untouched."
+  },
   {
     section: "sessions",
     usage: '-p <project> session start --worker <label> (--worktree <branch>|--new-worktree <branch> --source worktree:<branch>) --model <tier> [-f|--follow|--watch] [--tools] "<prompt>"',
@@ -2344,6 +2354,21 @@ function parseConversationWorkDetailArgs(args) {
   }
   return detail;
 }
+function parseConversationForkArgs(args) {
+  let name;
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+    if (arg !== "--name") {
+      throw new Error(`Unknown conversation fork argument: ${arg}`);
+    }
+    if (name !== void 0) {
+      throw new Error("Use --name only once");
+    }
+    index += 1;
+    name = requireValue(args[index], "Missing value for --name");
+  }
+  return name;
+}
 function renderConversationOverviewResponse(read) {
   return read.overviewText.endsWith("\n") ? read.overviewText : `${read.overviewText}
 `;
@@ -2370,6 +2395,15 @@ function renderConversationWorkResponse(read) {
   return read.workText.endsWith("\n") ? read.workText : `${read.workText}
 `;
 }
+function renderConversationHeadResponse(read) {
+  return `Conversation head moved to ${read.head} (revision ${read.revision}). Files on disk are unchanged.
+`;
+}
+function renderConversationForkResponse(read) {
+  const name = read.session.name ? ` (${read.session.name})` : "";
+  return `Forked ${read.copiedNodeCount} node(s) up to ${read.forkedFromNodeId} into session ${read.session.id}${name}.
+`;
+}
 async function executeR5dctlCommand(client, json, args) {
   const write = (data, human) => writeDataOutput(json, data, human);
   const [first, second, third] = args;
@@ -2564,6 +2598,24 @@ Sessions: ${result.sessions.length}
     write(read, renderConversationNodeResponse(read));
     return;
   }
+  if (first === "conversation" && second === "move-head") {
+    if (args.length > 4) {
+      throw new Error(`Unexpected conversation move-head argument: ${args[4]}`);
+    }
+    const sessionId = requireValue(args[2], "Missing session id");
+    const nodeId2 = requireValue(args[3], "Missing node id");
+    const read = await client.sessions.moveConversationHead(sessionId, nodeId2);
+    write(read, renderConversationHeadResponse(read));
+    return;
+  }
+  if (first === "conversation" && second === "fork") {
+    const sessionId = requireValue(args[2], "Missing session id");
+    const nodeId2 = requireValue(args[3], "Missing node id");
+    const name = parseConversationForkArgs(args.slice(4));
+    const read = await client.sessions.forkConversation(sessionId, nodeId2, name === void 0 ? {} : { name });
+    write(read, renderConversationForkResponse(read));
+    return;
+  }
   if (first === "conversation" && second === "inspect-work") {
     const sessionId = requireValue(args[2], "Missing session id");
     const workId = requireValue(args[3], "Missing work id");
@@ -2974,34 +3026,26 @@ function resolveCommandExecution(options, rest) {
         pluginArgs: ["conversation", "overview", sessionId2, ...remainingArgs]
       };
     }
-    if (subcommand === "inspect-work") {
-      const sessionId2 = options.session ?? commandArgs[1];
-      if (!sessionId2) {
-        throw new Error("Session id is required for `conversation inspect-work`");
-      }
-      const workId = options.session ? commandArgs[1] : commandArgs[2];
-      if (!workId) {
-        throw new Error("Work id is required for `conversation inspect-work`");
-      }
-      const remainingArgs = options.session ? commandArgs.slice(2) : commandArgs.slice(3);
-      return {
-        kind: "plugin",
-        pluginArgs: ["conversation", "inspect-work", sessionId2, workId, ...remainingArgs]
-      };
-    }
-    if (subcommand === "inspect-node") {
+    const targetedSubcommands = [
+      { subcommand: "inspect-work", secondIdLabel: "Work id" },
+      { subcommand: "inspect-node", secondIdLabel: "Node id" },
+      { subcommand: "move-head", secondIdLabel: "Node id" },
+      { subcommand: "fork", secondIdLabel: "Node id" }
+    ];
+    const targeted = targetedSubcommands.find((candidate) => candidate.subcommand === subcommand);
+    if (targeted) {
       const sessionId2 = options.session ?? commandArgs[1];
       if (!sessionId2) {
-        throw new Error("Session id is required for `conversation inspect-node`");
+        throw new Error(`Session id is required for \`conversation ${targeted.subcommand}\``);
       }
-      const nodeId2 = options.session ? commandArgs[1] : commandArgs[2];
-      if (!nodeId2) {
-        throw new Error("Node id is required for `conversation inspect-node`");
+      const secondId = options.session ? commandArgs[1] : commandArgs[2];
+      if (!secondId) {
+        throw new Error(`${targeted.secondIdLabel} is required for \`conversation ${targeted.subcommand}\``);
       }
       const remainingArgs = options.session ? commandArgs.slice(2) : commandArgs.slice(3);
       return {
         kind: "plugin",
-        pluginArgs: ["conversation", "inspect-node", sessionId2, nodeId2, ...remainingArgs]
+        pluginArgs: ["conversation", targeted.subcommand, sessionId2, secondId, ...remainingArgs]
       };
     }
     const sessionId = options.session;
@@ -3187,6 +3231,7 @@ export {
   parseAnswerEnvRequestCommandArgs,
   parseAnswerFlags,
   parseAnswerQuestionsCommandArgs,
+  parseConversationForkArgs,
   parseConversationRenderArgs,
   parseConversationWorkDetailArgs,
   parseEnvFlags,
@@ -3202,6 +3247,8 @@ export {
   parseSetEnvArgs,
   parseShellArgs,
   readDotenvFile,
+  renderConversationForkResponse,
+  renderConversationHeadResponse,
   renderConversationNodeResponse,
   renderConversationOverviewResponse,
   renderConversationResponse,

package/dist/mjs/package.json

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

package/dist/types/cli.d.ts

@@ -1,4 +1,4 @@
-import { R5dctlClient, 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 R5dctlProcessRun, type R5dctlSessionEvent, type R5dctlSessionStartInput, type R5dctlWorkspaceStatus, type R5dctlWorkspaceSyncResult, type R5dctlWorktreeSource, type R5dctlMergeConflictMode, type R5dctlSessionMode, type ChatMode, type ModelTier } from "@ricsam/r5d-api";
+import { R5dctlClient, type R5dctlConversationForkResponse, type R5dctlConversationHeadResponse, type R5dctlConversationRenderOptions, type R5dctlConversationResponse, type R5dctlConversationNodeResponse, type R5dctlConversationOverviewResponse, type R5dctlConversationWorkDetail, type R5dctlConversationWorkResponse, type R5dctlEnvData, type R5dctlK8sResourceHistory, type R5dctlK8sUsage, type R5dctlK8sWorkload, type R5dctlProcessInspection, type R5dctlProcessListInput, type R5dctlProcessRun, type R5dctlSessionEvent, type R5dctlSessionStartInput, type R5dctlWorkspaceStatus, type R5dctlWorkspaceSyncResult, type R5dctlWorktreeSource, type R5dctlMergeConflictMode, type R5dctlSessionMode, type ChatMode, type ModelTier } from "@ricsam/r5d-api";
 export type GlobalOptions = {
     baseUrl?: string;
     json: boolean;
@@ -299,9 +299,12 @@ export type R5dctlFollowOptions = {
 };
 export declare function followR5dctlSession(client: R5dctlFollowClient, sessionId: string, options: R5dctlFollowOptions): Promise<number>;
 export declare function parseConversationWorkDetailArgs(args: string[]): R5dctlConversationWorkDetail;
+export declare function parseConversationForkArgs(args: string[]): string | undefined;
 export declare function renderConversationOverviewResponse(read: R5dctlConversationOverviewResponse): string;
 export declare function renderConversationNodeResponse(read: R5dctlConversationNodeResponse): string;
 export declare function renderConversationWorkResponse(read: R5dctlConversationWorkResponse): string;
+export declare function renderConversationHeadResponse(read: R5dctlConversationHeadResponse): string;
+export declare function renderConversationForkResponse(read: R5dctlConversationForkResponse): string;
 export declare function resolveCommandExecution(options: GlobalOptions, rest: string[]): CommandExecutionPlan;
 export declare function runR5dctlCli(argv: string[]): Promise<number>;
 export declare function main(argv?: string[]): Promise<void>;

package/package.json

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