@ricsam/r5dctl 0.0.100 → 0.0.103

package/README.md

@@ -88,9 +88,12 @@ r5dctl -s <session-id> answer-env-request --worker <label> --mode agent --model
 
 r5dctl -p <project> session start --worker <label> --worktree main --model max "Explore the failure"
 r5dctl -p <project> session start --worker <label> --new-worktree fix/tests --source worktree:main --model max -f "Fix the failing tests"
+r5dctl -p <project> session start --worker <label> --new-worktree fix/tests --source worktree:main --working-tree clean --model max "Fix the failing tests from main's committed state"
 r5dctl session status <session-id>
 r5dctl session prompt --worker <label> --mode agent --model max <session-id> "Also check the migration"
 r5dctl session stop <session-id>
+r5dctl session process-log <run-id> --tail 200
+r5dctl session process-log <run-id> --grep "error|failed"
 
 r5dctl -p <project> -b <branch> shell
 r5dctl -p <project> -b <branch> shell -c "bun test"
@@ -116,7 +119,11 @@ repository. Trust applies to that workflow path on every Git ref and grants
 cluster-admin, so protect workflow changes and do not invoke it for untrusted
 pull requests.
 
-`session start` creates an ordinary agent-mode chat on an explicitly selected existing worktree, or creates a named linked worktree from an explicit `worktree:<branch>` source. 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 stop` returns as soon as the agent run is stopped; the stopped worktree's workspace Git synchronization finishes asynchronously behind the response.
+`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 stop` returns as soon as the agent run is stopped; the stopped worktree's workspace Git synchronization finishes asynchronously behind the response.
+
+`session status` reports the run lifecycle and the launch-time `Source` and `Working tree` facts only. It deliberately prints no commit hash for the worktree, not even the launch baseline: a hash would be stale by the time a caller acts on it, because commits can land between the read and the action. Find the base and the branch's commits with git in the worker checkout instead, for example `git merge-base <your-branch> <branch>`, `git log --oneline <your-branch>..<branch>`, and `git status` in the branch folder, as the `Branch state` line reminds you. While a new worktree is still provisioning, a `Provisioning` line reports where its creation stands in the worker's operation queue and since when (`Provisioning: queued behind 3 worker operations since 2026-09-03T11:41:30Z`); a worker that predates operation receipts leaves that line out.
+
+`session process-log` prints a shell run's stored stdout and stderr from the server, where r5d keeps every run's full output; the `logPath` in tool results names that server-side store, not a file on the worker. Without flags it prints the whole log, `--tail <n>` keeps the last n lines, and `--grep <pattern>` keeps the lines matching a JavaScript regular expression (combine both for the last n matches). Each stream is capped at 512 KB per call and printed under a `==> stdout <==` or `==> stderr <==` header; a one-line summary with byte totals, the selection, and any truncation goes to stderr so stdout stays clean for `grep`, `head`, and `tail`. Inside an r5d worker shell the temporary credential can only read runs on that shell's worker.
 
 Add `-f`/`--follow`/`--watch` to `session start` to poll the provisioning handle and attach after enqueue, or to `conversation` to print the current transcript and follow new output. Assistant text is written to stdout and lifecycle/tool progress to stderr; `--tools` includes tool calls and results. With global `--json`, follow mode emits one JSON event per line. Ctrl-C only detaches and never stops the session. The CLI reconnects transiently interrupted event streams and resynchronizes committed conversation revisions without repeating assistant text.
 

package/dist/cjs/cli.cjs

@@ -57,6 +57,7 @@ __export(cli_exports, {
   parsePromptArgs: () => parsePromptArgs,
   parsePsHistoryArgs: () => parsePsHistoryArgs,
   parsePsListArgs: () => parsePsListArgs,
+  parseSessionProcessLogArgs: () => parseSessionProcessLogArgs,
   parseSessionRunCommand: () => parseSessionRunCommand,
   parseSetEnvArgs: () => parseSetEnvArgs,
   parseShellArgs: () => parseShellArgs,
@@ -73,6 +74,7 @@ __export(cli_exports, {
   renderProcessHistory: () => renderProcessHistory,
   renderProcessInspection: () => renderProcessInspection,
   renderProcessList: () => renderProcessList,
+  renderProcessLog: () => renderProcessLog,
   renderSessionRunStart: () => renderSessionRunStart,
   renderSessionRunStatus: () => renderSessionRunStatus,
   renderWorkspaceStatus: () => renderWorkspaceStatus,
@@ -155,14 +157,19 @@ const K8S_HELP_TEXT = [
 ].join("\n");
 const SESSION_RUN_HELP_TEXT = [
   "Usage:",
-  '  r5dctl -p <project> session start --worker <label> --worktree <branch> --model <tier> [-f|--follow|--watch] [--tools] "<prompt>"',
-  '  r5dctl -p <project> session start --worker <label> --new-worktree <branch> --source worktree:<branch> --model <tier> [-f|--follow|--watch] [--tools] "<prompt>"',
+  '  r5dctl -p <project> session start --worker <label> --worktree <branch> --model <tier> [-f|--follow|--watch] [--tools] [--parent-session <session-id>] "<prompt>"',
+  '  r5dctl -p <project> session start --worker <label> --new-worktree <branch> --source worktree:<branch> [--working-tree carry|clean] --model <tier> [-f|--follow|--watch] [--tools] [--parent-session <session-id>] "<prompt>"',
   "  r5dctl session status <session-id>",
   '  r5dctl session prompt --worker <label> --mode <mode> --model <tier> <session-id> "<prompt>"',
   "  r5dctl session stop <session-id>",
+  "  r5dctl session process-log <run-id> [--tail <n>] [--grep <pattern>]",
   "",
   "Create, inspect, resume, and stop ordinary agent sessions.",
+  "A new worktree starts with the source checkout's uncommitted changes (--working-tree carry, the default);",
+  "--working-tree clean checks out the source branch's current commit only. Start and status print the mode, never a commit hash.",
   "Use -f/--follow/--watch to attach after a start; Ctrl-C detaches without stopping the session.",
+  "process-log prints a shell run's stored stdout/stderr from the server: the whole log, its last n lines,",
+  "or the lines matching a JavaScript regular expression. The log is not a file on the worker.",
   ""
 ].join("\n");
 const SHARED_HELP_ENTRIES = [
@@ -262,8 +269,8 @@ const SHARED_HELP_ENTRIES = [
   },
   {
     section: "sessions",
-    usage: '-p <project> session start --worker <label> (--worktree <branch>|--new-worktree <branch> --source worktree:<branch>) --model <tier> [-f|--follow|--watch] [--tools] "<prompt>"',
-    description: "Start an ordinary agent session on an explicit existing or new worktree."
+    usage: '-p <project> session start --worker <label> (--worktree <branch>|--new-worktree <branch> --source worktree:<branch> [--working-tree carry|clean]) --model <tier> [-f|--follow|--watch] [--tools] [--parent-session <session-id>] "<prompt>"',
+    description: "Start an ordinary agent session on an explicit existing or new worktree. A new worktree carries the source checkout's uncommitted changes unless --working-tree clean is passed. --parent-session links it like start_subagent: the parent is notified when the run finishes."
   },
   {
     section: "sessions",
@@ -280,6 +287,11 @@ const SHARED_HELP_ENTRIES = [
     usage: "session stop <session-id>",
     description: "Stop an active session generation."
   },
+  {
+    section: "sessions",
+    usage: "session process-log <run-id> [--tail <n>] [--grep <pattern>]",
+    description: "Print a shell run's stored stdout/stderr from the server: the whole log, its last lines, or lines matching a regular expression."
+  },
   {
     section: "sessions",
     usage: '-s <session-id> answer-questions --worker <label> --mode <mode> --model <tier> -a1 "<answer>" ...',
@@ -543,6 +555,12 @@ function parseWorktreeSource(rawValue) {
   }
   return { type, branchName };
 }
+function parseWorkingTreeMode(rawValue) {
+  if (rawValue === void 0) return "carry";
+  const mode = rawValue.trim();
+  if (mode !== "carry" && mode !== "clean") throw new Error("Invalid --working-tree. Expected carry or clean");
+  return mode;
+}
 function requireModel(value) {
   const model = requireValue(value?.trim(), "--model <tier> is required");
   if (!MODEL_TIERS.has(model)) throw new Error("Invalid --model. Expected one of: low, medium, high, max");
@@ -568,7 +586,7 @@ function parseSessionRunCommand(options, args) {
     const project = requireValue(options.project, "--project/-p is required for `session start`");
     const parsed = parseCommandOperands(
       commandArgs,
-      /* @__PURE__ */ new Set(["--worker", "--worktree", "--new-worktree", "--source", "--model"]),
+      /* @__PURE__ */ new Set(["--worker", "--worktree", "--new-worktree", "--source", "--working-tree", "--model", "--parent-session"]),
       /* @__PURE__ */ new Map([
         ["-f", "--follow"],
         ["--follow", "--follow"],
@@ -587,6 +605,9 @@ function parseSessionRunCommand(options, args) {
     }
     const sourceValue = parsed.values.get("--source");
     if (worktree && sourceValue) throw new Error("--source is only supported with --new-worktree");
+    const workingTreeValue = parsed.values.get("--working-tree");
+    if (worktree && workingTreeValue !== void 0) throw new Error("--working-tree is only supported with --new-worktree");
+    const parentSessionId = parsed.values.get("--parent-session")?.trim();
     return {
       kind: "start",
       project,
@@ -595,7 +616,8 @@ function parseSessionRunCommand(options, args) {
       prompt,
       follow: parsed.booleans.has("--follow"),
       includeTools: parsed.booleans.has("--tools"),
-      ...worktree ? { worktree } : { newWorktree, source: parseWorktreeSource(sourceValue) }
+      ...parentSessionId ? { parentSessionId } : {},
+      ...worktree ? { worktree } : { newWorktree, source: parseWorktreeSource(sourceValue), workingTree: parseWorkingTreeMode(workingTreeValue) }
     };
   }
   rejectSessionRunGlobalScopes(options, false);
@@ -621,6 +643,16 @@ function parseSessionRunCommand(options, args) {
   }
   throw new Error(`Unknown session command: ${subcommand}`);
 }
+function parseSessionProcessLogArgs(args) {
+  const parsed = parseCommandOperands(args, /* @__PURE__ */ new Set(["--tail", "--grep"]), /* @__PURE__ */ new Map(), "session process-log");
+  const runId = requireValue(parsed.positionals[0], "Process run id is required for `session process-log`");
+  if (parsed.positionals.length > 1) throw new Error(`Unexpected session process-log argument: ${parsed.positionals[1]}`);
+  const tailValue = parsed.values.get("--tail");
+  const tail = tailValue === void 0 ? void 0 : Number(tailValue);
+  if (tail !== void 0 && (!Number.isInteger(tail) || tail < 1)) throw new Error("--tail must be a positive integer");
+  const grep = parsed.values.get("--grep");
+  return { runId, ...tail !== void 0 ? { tail } : {}, ...grep !== void 0 ? { grep } : {} };
+}
 function assertAuthLoginArgs(args) {
   const valueFlags = /* @__PURE__ */ new Set(["--device-name", "--worker-label"]);
   const booleanFlags = /* @__PURE__ */ new Set(["--no-open", "--no-qr"]);
@@ -1678,6 +1710,32 @@ function renderProcessList(processes, nowMs = Date.now()) {
 function renderProcessHistory(processes, nowMs = Date.now()) {
   return processes.length === 0 ? "No process history.\n" : renderProcessList(processes, nowMs);
 }
+function renderProcessLog(log) {
+  const sections = [];
+  for (const [name, stream] of [
+    ["stdout", log.stdout],
+    ["stderr", log.stderr]
+  ]) {
+    if (stream.text.length === 0) continue;
+    sections.push(`==> ${name} <==
+${stream.text.endsWith("\n") ? stream.text : `${stream.text}
+`}`);
+  }
+  const selection = [
+    ...log.grep !== void 0 ? [`lines matching /${log.grep}/`] : [],
+    ...log.tailLines !== void 0 ? [`last ${log.tailLines} lines`] : []
+  ];
+  const cut = [log.stdout.truncated ? "stdout" : void 0, log.stderr.truncated ? "stderr" : void 0].filter(Boolean);
+  const summary = [
+    `Run ${log.runId} (${log.status}${log.exitCode !== void 0 ? `, exit ${log.exitCode}` : ""}): `,
+    `stdout ${log.stdout.totalBytes} bytes, stderr ${log.stderr.totalBytes} bytes`,
+    selection.length > 0 ? `; showing ${selection.join(", ")}` : "",
+    cut.length > 0 ? `; ${cut.join(" and ")} cut to ${log.maxBytesPerStream} bytes, narrow with --tail or --grep` : "",
+    sections.length === 0 ? "; no output to show" : ""
+  ].join("");
+  return { text: sections.join(""), summary: `${summary}
+` };
+}
 function renderProcessInspection(process2) {
   return [
     `Run: ${process2.runId}`,
@@ -1831,13 +1889,22 @@ function formatStatusValue(value) {
   }
   return value === void 0 || value === null ? void 0 : String(value);
 }
+function pushWorktreeOriginLines(lines, session) {
+  const source = responseString(session, "sourceBranch");
+  const mode = responseString(session, "workingTree");
+  if (!source || !mode) return;
+  lines.push(`Source: ${source}`);
+  const detail = mode === "carry" ? `carried ${source}'s uncommitted changes at launch` : mode === "clean" ? `clean checkout of ${source}'s commit at launch` : void 0;
+  lines.push(`Working tree: ${mode}${detail ? ` (${detail})` : ""}`);
+}
 function renderSessionRunStart(session) {
   const lines = [
     `Session: ${responseString(session, "sessionId") ?? "(unknown)"}`,
     `Status: ${formatStatusValue(session.status) ?? "queued"}`,
-    `Worktree: ${responseString(session, "branchName") ?? "(provisioning)"}`,
-    `Worker: ${responseString(session, "worker") ?? "(unassigned)"}`
+    `Worktree: ${responseString(session, "branchName") ?? "(provisioning)"}`
   ];
+  pushWorktreeOriginLines(lines, session);
+  lines.push(`Worker: ${responseString(session, "worker") ?? "(unassigned)"}`);
   const sessionUrl = responseString(session, "sessionUrl");
   if (sessionUrl) lines.push(`URL: ${sessionUrl}`);
   const sessionId = responseString(session, "sessionId");
@@ -1845,29 +1912,50 @@ function renderSessionRunStart(session) {
   return `${lines.join("\n")}
 `;
 }
+function formatBranchStateHint(branch) {
+  const target = branch ?? "<branch>";
+  const commands = [
+    `git merge-base <your-branch> ${target}`,
+    `git log --oneline <your-branch>..${target}`,
+    "git status in the branch folder"
+  ];
+  return `inspect the worktree with git (${commands.join("; ")})`;
+}
+function formatQueuedAt(value) {
+  const time = Date.parse(value);
+  return Number.isNaN(time) ? value : new Date(time).toISOString().replace(/\.\d{3}Z$/, "Z");
+}
+function formatProvisioningQueueLine(session) {
+  const position = session.provisioningQueuePosition;
+  const queuedAt = responseString(session, "provisioningQueuedAt");
+  if (typeof position !== "number" || !Number.isInteger(position) || position < 0 || !queuedAt) return void 0;
+  const since = formatQueuedAt(queuedAt);
+  if (position === 0) return `Provisioning: worker started the branch operation at ${since}`;
+  return `Provisioning: queued behind ${position} worker operation${position === 1 ? "" : "s"} since ${since}`;
+}
 function renderSessionRunStatus(session) {
   const status = formatStatusValue(session.status) ?? "unknown";
   const lines = [`Session: ${responseString(session, "sessionId") ?? "(unknown)"}`, `Status: ${status}`];
   const runStatus = formatStatusValue(session.runStatus);
   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}`);
   const branch = responseString(session, "branchName");
   if (branch) lines.push(`Worktree: ${branch}`);
+  pushWorktreeOriginLines(lines, session);
   for (const [label, key] of [
-    ["Workspace head", "workspaceHead"],
-    ["Baseline", "baselineCommit"],
-    ["Head", "headCommit"],
     ["Worker", "worker"],
+    ["Parent session", "parentSessionId"],
     ["Session", "sessionUrl"]
   ]) {
     const value = responseString(session, key);
     if (value) lines.push(`${label}: ${value}`);
   }
+  lines.push(`Branch state: ${formatBranchStateHint(branch)}`);
   const error = responseString(session, "error");
   if (error) lines.push(`Error: ${error}`);
-  const headCommitError = responseString(session, "headCommitError");
-  if (headCommitError) lines.push(`Head error: ${headCommitError}`);
   const diffSummary = responseString(session, "diffSummary");
   if (diffSummary) lines.push("", diffSummary);
   const summary = responseString(session, "summary");
@@ -1885,13 +1973,14 @@ async function dispatchSessionRunCommand(client, command) {
       prompt: command.prompt,
       worker: command.worker,
       model: command.model,
-      requestId: (0, import_node_crypto.randomUUID)()
+      requestId: (0, import_node_crypto.randomUUID)(),
+      ...command.parentSessionId ? { parentSessionId: command.parentSessionId } : {}
     };
     let input;
     if (command.worktree !== void 0) {
       input = { ...commonInput, worktree: command.worktree };
     } else if (command.newWorktree !== void 0 && command.source !== void 0) {
-      input = { ...commonInput, newWorktree: command.newWorktree, source: command.source };
+      input = { ...commonInput, newWorktree: command.newWorktree, source: command.source, workingTree: command.workingTree };
     } else {
       throw new Error("Session start requires an existing or new worktree");
     }
@@ -2531,6 +2620,17 @@ async function executeR5dctlCommand(client, json, args) {
 `);
     return;
   }
+  if (first === "session" && second === "process-log") {
+    const selection = parseSessionProcessLogArgs(args.slice(2));
+    const log = await client.processes.log(selection.runId, {
+      ...selection.tail !== void 0 ? { tail: selection.tail } : {},
+      ...selection.grep !== void 0 ? { grep: selection.grep } : {}
+    });
+    const rendered = renderProcessLog(log);
+    write(log, rendered.text);
+    if (!json) process.stderr.write(rendered.summary);
+    return;
+  }
   if (first === "sessions" && second === "recent") {
     const sessions = await client.sessions.recent(parseRecentSessionArgs(args.slice(2)));
     write(sessions, renderRecentSessionList(sessions));
@@ -3138,6 +3238,20 @@ function resolveCommandExecution(options, rest) {
     };
   }
   if (command === "session") {
+    if (commandArgs[0] === "process-log") {
+      rejectSessionRunGlobalScopes(options, false);
+      const selection = parseSessionProcessLogArgs(commandArgs.slice(1));
+      return {
+        kind: "plugin",
+        pluginArgs: [
+          "session",
+          "process-log",
+          selection.runId,
+          ...selection.tail !== void 0 ? [`--tail=${selection.tail}`] : [],
+          ...selection.grep !== void 0 ? [`--grep=${selection.grep}`] : []
+        ]
+      };
+    }
     return { kind: "session-run", command: parseSessionRunCommand(options, commandArgs) };
   }
   if (command === "answer-questions") {
@@ -3318,6 +3432,7 @@ async function main(argv = process.argv.slice(2)) {
   parsePromptArgs,
   parsePsHistoryArgs,
   parsePsListArgs,
+  parseSessionProcessLogArgs,
   parseSessionRunCommand,
   parseSetEnvArgs,
   parseShellArgs,
@@ -3334,6 +3449,7 @@ async function main(argv = process.argv.slice(2)) {
   renderProcessHistory,
   renderProcessInspection,
   renderProcessList,
+  renderProcessLog,
   renderSessionRunStart,
   renderSessionRunStatus,
   renderWorkspaceStatus,

package/dist/cjs/package.json

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

package/dist/mjs/cli.mjs

@@ -72,14 +72,19 @@ const K8S_HELP_TEXT = [
 ].join("\n");
 const SESSION_RUN_HELP_TEXT = [
   "Usage:",
-  '  r5dctl -p <project> session start --worker <label> --worktree <branch> --model <tier> [-f|--follow|--watch] [--tools] "<prompt>"',
-  '  r5dctl -p <project> session start --worker <label> --new-worktree <branch> --source worktree:<branch> --model <tier> [-f|--follow|--watch] [--tools] "<prompt>"',
+  '  r5dctl -p <project> session start --worker <label> --worktree <branch> --model <tier> [-f|--follow|--watch] [--tools] [--parent-session <session-id>] "<prompt>"',
+  '  r5dctl -p <project> session start --worker <label> --new-worktree <branch> --source worktree:<branch> [--working-tree carry|clean] --model <tier> [-f|--follow|--watch] [--tools] [--parent-session <session-id>] "<prompt>"',
   "  r5dctl session status <session-id>",
   '  r5dctl session prompt --worker <label> --mode <mode> --model <tier> <session-id> "<prompt>"',
   "  r5dctl session stop <session-id>",
+  "  r5dctl session process-log <run-id> [--tail <n>] [--grep <pattern>]",
   "",
   "Create, inspect, resume, and stop ordinary agent sessions.",
+  "A new worktree starts with the source checkout's uncommitted changes (--working-tree carry, the default);",
+  "--working-tree clean checks out the source branch's current commit only. Start and status print the mode, never a commit hash.",
   "Use -f/--follow/--watch to attach after a start; Ctrl-C detaches without stopping the session.",
+  "process-log prints a shell run's stored stdout/stderr from the server: the whole log, its last n lines,",
+  "or the lines matching a JavaScript regular expression. The log is not a file on the worker.",
   ""
 ].join("\n");
 const SHARED_HELP_ENTRIES = [
@@ -179,8 +184,8 @@ const SHARED_HELP_ENTRIES = [
   },
   {
     section: "sessions",
-    usage: '-p <project> session start --worker <label> (--worktree <branch>|--new-worktree <branch> --source worktree:<branch>) --model <tier> [-f|--follow|--watch] [--tools] "<prompt>"',
-    description: "Start an ordinary agent session on an explicit existing or new worktree."
+    usage: '-p <project> session start --worker <label> (--worktree <branch>|--new-worktree <branch> --source worktree:<branch> [--working-tree carry|clean]) --model <tier> [-f|--follow|--watch] [--tools] [--parent-session <session-id>] "<prompt>"',
+    description: "Start an ordinary agent session on an explicit existing or new worktree. A new worktree carries the source checkout's uncommitted changes unless --working-tree clean is passed. --parent-session links it like start_subagent: the parent is notified when the run finishes."
   },
   {
     section: "sessions",
@@ -197,6 +202,11 @@ const SHARED_HELP_ENTRIES = [
     usage: "session stop <session-id>",
     description: "Stop an active session generation."
   },
+  {
+    section: "sessions",
+    usage: "session process-log <run-id> [--tail <n>] [--grep <pattern>]",
+    description: "Print a shell run's stored stdout/stderr from the server: the whole log, its last lines, or lines matching a regular expression."
+  },
   {
     section: "sessions",
     usage: '-s <session-id> answer-questions --worker <label> --mode <mode> --model <tier> -a1 "<answer>" ...',
@@ -460,6 +470,12 @@ function parseWorktreeSource(rawValue) {
   }
   return { type, branchName };
 }
+function parseWorkingTreeMode(rawValue) {
+  if (rawValue === void 0) return "carry";
+  const mode = rawValue.trim();
+  if (mode !== "carry" && mode !== "clean") throw new Error("Invalid --working-tree. Expected carry or clean");
+  return mode;
+}
 function requireModel(value) {
   const model = requireValue(value?.trim(), "--model <tier> is required");
   if (!MODEL_TIERS.has(model)) throw new Error("Invalid --model. Expected one of: low, medium, high, max");
@@ -485,7 +501,7 @@ function parseSessionRunCommand(options, args) {
     const project = requireValue(options.project, "--project/-p is required for `session start`");
     const parsed = parseCommandOperands(
       commandArgs,
-      /* @__PURE__ */ new Set(["--worker", "--worktree", "--new-worktree", "--source", "--model"]),
+      /* @__PURE__ */ new Set(["--worker", "--worktree", "--new-worktree", "--source", "--working-tree", "--model", "--parent-session"]),
       /* @__PURE__ */ new Map([
         ["-f", "--follow"],
         ["--follow", "--follow"],
@@ -504,6 +520,9 @@ function parseSessionRunCommand(options, args) {
     }
     const sourceValue = parsed.values.get("--source");
     if (worktree && sourceValue) throw new Error("--source is only supported with --new-worktree");
+    const workingTreeValue = parsed.values.get("--working-tree");
+    if (worktree && workingTreeValue !== void 0) throw new Error("--working-tree is only supported with --new-worktree");
+    const parentSessionId = parsed.values.get("--parent-session")?.trim();
     return {
       kind: "start",
       project,
@@ -512,7 +531,8 @@ function parseSessionRunCommand(options, args) {
       prompt,
       follow: parsed.booleans.has("--follow"),
       includeTools: parsed.booleans.has("--tools"),
-      ...worktree ? { worktree } : { newWorktree, source: parseWorktreeSource(sourceValue) }
+      ...parentSessionId ? { parentSessionId } : {},
+      ...worktree ? { worktree } : { newWorktree, source: parseWorktreeSource(sourceValue), workingTree: parseWorkingTreeMode(workingTreeValue) }
     };
   }
   rejectSessionRunGlobalScopes(options, false);
@@ -538,6 +558,16 @@ function parseSessionRunCommand(options, args) {
   }
   throw new Error(`Unknown session command: ${subcommand}`);
 }
+function parseSessionProcessLogArgs(args) {
+  const parsed = parseCommandOperands(args, /* @__PURE__ */ new Set(["--tail", "--grep"]), /* @__PURE__ */ new Map(), "session process-log");
+  const runId = requireValue(parsed.positionals[0], "Process run id is required for `session process-log`");
+  if (parsed.positionals.length > 1) throw new Error(`Unexpected session process-log argument: ${parsed.positionals[1]}`);
+  const tailValue = parsed.values.get("--tail");
+  const tail = tailValue === void 0 ? void 0 : Number(tailValue);
+  if (tail !== void 0 && (!Number.isInteger(tail) || tail < 1)) throw new Error("--tail must be a positive integer");
+  const grep = parsed.values.get("--grep");
+  return { runId, ...tail !== void 0 ? { tail } : {}, ...grep !== void 0 ? { grep } : {} };
+}
 function assertAuthLoginArgs(args) {
   const valueFlags = /* @__PURE__ */ new Set(["--device-name", "--worker-label"]);
   const booleanFlags = /* @__PURE__ */ new Set(["--no-open", "--no-qr"]);
@@ -1595,6 +1625,32 @@ function renderProcessList(processes, nowMs = Date.now()) {
 function renderProcessHistory(processes, nowMs = Date.now()) {
   return processes.length === 0 ? "No process history.\n" : renderProcessList(processes, nowMs);
 }
+function renderProcessLog(log) {
+  const sections = [];
+  for (const [name, stream] of [
+    ["stdout", log.stdout],
+    ["stderr", log.stderr]
+  ]) {
+    if (stream.text.length === 0) continue;
+    sections.push(`==> ${name} <==
+${stream.text.endsWith("\n") ? stream.text : `${stream.text}
+`}`);
+  }
+  const selection = [
+    ...log.grep !== void 0 ? [`lines matching /${log.grep}/`] : [],
+    ...log.tailLines !== void 0 ? [`last ${log.tailLines} lines`] : []
+  ];
+  const cut = [log.stdout.truncated ? "stdout" : void 0, log.stderr.truncated ? "stderr" : void 0].filter(Boolean);
+  const summary = [
+    `Run ${log.runId} (${log.status}${log.exitCode !== void 0 ? `, exit ${log.exitCode}` : ""}): `,
+    `stdout ${log.stdout.totalBytes} bytes, stderr ${log.stderr.totalBytes} bytes`,
+    selection.length > 0 ? `; showing ${selection.join(", ")}` : "",
+    cut.length > 0 ? `; ${cut.join(" and ")} cut to ${log.maxBytesPerStream} bytes, narrow with --tail or --grep` : "",
+    sections.length === 0 ? "; no output to show" : ""
+  ].join("");
+  return { text: sections.join(""), summary: `${summary}
+` };
+}
 function renderProcessInspection(process2) {
   return [
     `Run: ${process2.runId}`,
@@ -1748,13 +1804,22 @@ function formatStatusValue(value) {
   }
   return value === void 0 || value === null ? void 0 : String(value);
 }
+function pushWorktreeOriginLines(lines, session) {
+  const source = responseString(session, "sourceBranch");
+  const mode = responseString(session, "workingTree");
+  if (!source || !mode) return;
+  lines.push(`Source: ${source}`);
+  const detail = mode === "carry" ? `carried ${source}'s uncommitted changes at launch` : mode === "clean" ? `clean checkout of ${source}'s commit at launch` : void 0;
+  lines.push(`Working tree: ${mode}${detail ? ` (${detail})` : ""}`);
+}
 function renderSessionRunStart(session) {
   const lines = [
     `Session: ${responseString(session, "sessionId") ?? "(unknown)"}`,
     `Status: ${formatStatusValue(session.status) ?? "queued"}`,
-    `Worktree: ${responseString(session, "branchName") ?? "(provisioning)"}`,
-    `Worker: ${responseString(session, "worker") ?? "(unassigned)"}`
+    `Worktree: ${responseString(session, "branchName") ?? "(provisioning)"}`
   ];
+  pushWorktreeOriginLines(lines, session);
+  lines.push(`Worker: ${responseString(session, "worker") ?? "(unassigned)"}`);
   const sessionUrl = responseString(session, "sessionUrl");
   if (sessionUrl) lines.push(`URL: ${sessionUrl}`);
   const sessionId = responseString(session, "sessionId");
@@ -1762,29 +1827,50 @@ function renderSessionRunStart(session) {
   return `${lines.join("\n")}
 `;
 }
+function formatBranchStateHint(branch) {
+  const target = branch ?? "<branch>";
+  const commands = [
+    `git merge-base <your-branch> ${target}`,
+    `git log --oneline <your-branch>..${target}`,
+    "git status in the branch folder"
+  ];
+  return `inspect the worktree with git (${commands.join("; ")})`;
+}
+function formatQueuedAt(value) {
+  const time = Date.parse(value);
+  return Number.isNaN(time) ? value : new Date(time).toISOString().replace(/\.\d{3}Z$/, "Z");
+}
+function formatProvisioningQueueLine(session) {
+  const position = session.provisioningQueuePosition;
+  const queuedAt = responseString(session, "provisioningQueuedAt");
+  if (typeof position !== "number" || !Number.isInteger(position) || position < 0 || !queuedAt) return void 0;
+  const since = formatQueuedAt(queuedAt);
+  if (position === 0) return `Provisioning: worker started the branch operation at ${since}`;
+  return `Provisioning: queued behind ${position} worker operation${position === 1 ? "" : "s"} since ${since}`;
+}
 function renderSessionRunStatus(session) {
   const status = formatStatusValue(session.status) ?? "unknown";
   const lines = [`Session: ${responseString(session, "sessionId") ?? "(unknown)"}`, `Status: ${status}`];
   const runStatus = formatStatusValue(session.runStatus);
   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}`);
   const branch = responseString(session, "branchName");
   if (branch) lines.push(`Worktree: ${branch}`);
+  pushWorktreeOriginLines(lines, session);
   for (const [label, key] of [
-    ["Workspace head", "workspaceHead"],
-    ["Baseline", "baselineCommit"],
-    ["Head", "headCommit"],
     ["Worker", "worker"],
+    ["Parent session", "parentSessionId"],
     ["Session", "sessionUrl"]
   ]) {
     const value = responseString(session, key);
     if (value) lines.push(`${label}: ${value}`);
   }
+  lines.push(`Branch state: ${formatBranchStateHint(branch)}`);
   const error = responseString(session, "error");
   if (error) lines.push(`Error: ${error}`);
-  const headCommitError = responseString(session, "headCommitError");
-  if (headCommitError) lines.push(`Head error: ${headCommitError}`);
   const diffSummary = responseString(session, "diffSummary");
   if (diffSummary) lines.push("", diffSummary);
   const summary = responseString(session, "summary");
@@ -1802,13 +1888,14 @@ async function dispatchSessionRunCommand(client, command) {
       prompt: command.prompt,
       worker: command.worker,
       model: command.model,
-      requestId: randomUUID()
+      requestId: randomUUID(),
+      ...command.parentSessionId ? { parentSessionId: command.parentSessionId } : {}
     };
     let input;
     if (command.worktree !== void 0) {
       input = { ...commonInput, worktree: command.worktree };
     } else if (command.newWorktree !== void 0 && command.source !== void 0) {
-      input = { ...commonInput, newWorktree: command.newWorktree, source: command.source };
+      input = { ...commonInput, newWorktree: command.newWorktree, source: command.source, workingTree: command.workingTree };
     } else {
       throw new Error("Session start requires an existing or new worktree");
     }
@@ -2448,6 +2535,17 @@ async function executeR5dctlCommand(client, json, args) {
 `);
     return;
   }
+  if (first === "session" && second === "process-log") {
+    const selection = parseSessionProcessLogArgs(args.slice(2));
+    const log = await client.processes.log(selection.runId, {
+      ...selection.tail !== void 0 ? { tail: selection.tail } : {},
+      ...selection.grep !== void 0 ? { grep: selection.grep } : {}
+    });
+    const rendered = renderProcessLog(log);
+    write(log, rendered.text);
+    if (!json) process.stderr.write(rendered.summary);
+    return;
+  }
   if (first === "sessions" && second === "recent") {
     const sessions = await client.sessions.recent(parseRecentSessionArgs(args.slice(2)));
     write(sessions, renderRecentSessionList(sessions));
@@ -3055,6 +3153,20 @@ function resolveCommandExecution(options, rest) {
     };
   }
   if (command === "session") {
+    if (commandArgs[0] === "process-log") {
+      rejectSessionRunGlobalScopes(options, false);
+      const selection = parseSessionProcessLogArgs(commandArgs.slice(1));
+      return {
+        kind: "plugin",
+        pluginArgs: [
+          "session",
+          "process-log",
+          selection.runId,
+          ...selection.tail !== void 0 ? [`--tail=${selection.tail}`] : [],
+          ...selection.grep !== void 0 ? [`--grep=${selection.grep}`] : []
+        ]
+      };
+    }
     return { kind: "session-run", command: parseSessionRunCommand(options, commandArgs) };
   }
   if (command === "answer-questions") {
@@ -3234,6 +3346,7 @@ export {
   parsePromptArgs,
   parsePsHistoryArgs,
   parsePsListArgs,
+  parseSessionProcessLogArgs,
   parseSessionRunCommand,
   parseSetEnvArgs,
   parseShellArgs,
@@ -3250,6 +3363,7 @@ export {
   renderProcessHistory,
   renderProcessInspection,
   renderProcessList,
+  renderProcessLog,
   renderSessionRunStart,
   renderSessionRunStatus,
   renderWorkspaceStatus,

package/dist/mjs/package.json

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

package/dist/types/cli.d.ts

@@ -1,4 +1,4 @@
-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 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 R5dctlProcessLog, type R5dctlProcessRun, type R5dctlSessionEvent, type R5dctlSessionStartInput, type R5dctlWorkspaceStatus, type R5dctlWorkspaceSyncResult, type R5dctlWorkingTreeMode, type R5dctlWorktreeSource, type R5dctlSessionMode, type ChatMode, type ModelTier } from "@ricsam/r5d-api";
 export type GlobalOptions = {
     baseUrl?: string;
     json: boolean;
@@ -53,14 +53,17 @@ type R5dctlSessionStartCommand = {
     prompt: string;
     follow: boolean;
     includeTools: boolean;
+    parentSessionId?: string;
 } & ({
     worktree: string;
     newWorktree?: never;
     source?: never;
+    workingTree?: never;
 } | {
     worktree?: never;
     newWorktree: string;
     source: R5dctlWorktreeSource;
+    workingTree: R5dctlWorkingTreeMode;
 });
 export type R5dctlSessionRunCommand = R5dctlSessionStartCommand | {
     kind: "status";
@@ -77,6 +80,12 @@ export type R5dctlSessionRunCommand = R5dctlSessionStartCommand | {
     sessionId: string;
 };
 export declare function parseSessionRunCommand(options: Pick<GlobalOptions, "project" | "branch" | "session">, args: string[]): R5dctlSessionRunCommand;
+export type R5dctlSessionProcessLogArgs = {
+    runId: string;
+    tail?: number;
+    grep?: string;
+};
+export declare function parseSessionProcessLogArgs(args: string[]): R5dctlSessionProcessLogArgs;
 export declare function parseGlobalArgs(argv: string[]): {
     options: GlobalOptions;
     rest: string[];
@@ -176,6 +185,11 @@ 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;
 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): {
+    text: string;
+    summary: string;
+};
 export declare function renderProcessInspection(process: R5dctlProcessInspection): string;
 export type EnvSummaryData = Record<string, {
     description: string;
@@ -191,11 +205,19 @@ export type R5dctlCommandResponse = {
     sessionId?: string;
     sessionUrl?: string;
     branchName?: string;
+    /** Launch-time worktree origin of a new-worktree run; absent or null on an existing worktree. */
+    sourceBranch?: string | null;
+    workingTree?: string | null;
+    /** Launch-time hashes: present in --json output but never rendered. */
     baselineCommit?: string | null;
     workspaceHead?: string | null;
     worker?: string;
     status?: string;
     runStatus?: unknown;
+    /** Worker queue state while a new worktree provisions; older servers and workers omit it. */
+    provisioningQueuePosition?: number;
+    provisioningQueuedAt?: string;
+    /** Legacy fields older servers still send; never rendered because a reported hash goes stale. */
     headCommit?: string | null;
     headCommitError?: string;
     promptDisposition?: string;

package/package.json

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