@ricsam/r5dctl 0.0.131 → 0.0.133

package/README.md

@@ -136,6 +136,7 @@ r5dctl session status <session-id>
 r5dctl session prompt --worker <label> --mode agent --model max --delivery steer <session-id> "Also check the migration"
 r5dctl session prompt --worker <label> --mode agent --model max --delivery force <session-id> "Stop that and fix the build first"
 r5dctl session stop <session-id>
+r5dctl session set-worker <session-id> --worker <label>
 r5dctl session process-log <run-id> --tail 200
 r5dctl session process-log <run-id> --grep "error|failed"
 
@@ -169,6 +170,8 @@ Delivery is not acknowledgment. If a merge or shared-checkout change depends on
 
 `session stop` also stops every sub-agent session the stopped session started, directly or through its own children, and `session status` prints `Child sessions: <active> active of <total>` for a session that launched sub-agents.
 
+`session set-worker` rebinds a stopped session to another connected worker, exactly like the composer's worker selector: it publishes the current worker's workspace, synchronizes the target worker, persists the binding, and the session resumes there on its next prompt or resume. It is refused with `409` while the session's agent runs and with `403` for a worker credential. A running project agent moves its own session with the `switch_worker` tool instead, which needs no stop; workspace chats are rebound only while stopped. Shell runs, r5dctl shells, browser port forwards, and sub-agents started earlier stay on the worker that started them.
+
 `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.

package/dist/cjs/cli.cjs

@@ -30,10 +30,12 @@ var cli_exports = {};
 __export(cli_exports, {
   BRANCH_DELETION_POLL_INTERVAL_MS: () => BRANCH_DELETION_POLL_INTERVAL_MS,
   BRANCH_DELETION_WAIT_TIMEOUT_MS: () => BRANCH_DELETION_WAIT_TIMEOUT_MS,
+  R5dctlClaimScopeMismatchError: () => R5dctlClaimScopeMismatchError,
   advanceTransientDevicePollBackoff: () => advanceTransientDevicePollBackoff,
   branchDeletionConfirmationMessage: () => branchDeletionConfirmationMessage,
   branchDeletionsConfirmationMessage: () => branchDeletionsConfirmationMessage,
   branchDeletionsFailureMessage: () => branchDeletionsFailureMessage,
+  claimScopeMatches: () => claimScopeMatches,
   createBranchThroughPlatform: () => createBranchThroughPlatform,
   deleteBranchThroughPlatform: () => deleteBranchThroughPlatform,
   deleteBranchesThroughPlatform: () => deleteBranchesThroughPlatform,
@@ -53,6 +55,7 @@ __export(cli_exports, {
   parseAnswerQuestionsCommandArgs: () => parseAnswerQuestionsCommandArgs,
   parseBranchCreateArgs: () => parseBranchCreateArgs,
   parseBranchDeleteArgs: () => parseBranchDeleteArgs,
+  parseCheckoutPathArgs: () => parseCheckoutPathArgs,
   parseClaimDuration: () => parseClaimDuration,
   parseConversationForkArgs: () => parseConversationForkArgs,
   parseConversationInspectWorkArgs: () => parseConversationInspectWorkArgs,
@@ -78,6 +81,7 @@ __export(cli_exports, {
   renderBranchDeletionStatus: () => renderBranchDeletionStatus,
   renderBranchList: () => renderBranchList,
   renderBranchOperation: () => renderBranchOperation,
+  renderCheckoutPath: () => renderCheckoutPath,
   renderConversationForkResponse: () => renderConversationForkResponse,
   renderConversationHeadResponse: () => renderConversationHeadResponse,
   renderConversationNodeResponse: () => renderConversationNodeResponse,
@@ -95,6 +99,7 @@ __export(cli_exports, {
   renderSessionList: () => renderSessionList,
   renderSessionRunStart: () => renderSessionRunStart,
   renderSessionRunStatus: () => renderSessionRunStatus,
+  renderSessionSetWorker: () => renderSessionSetWorker,
   renderWorkerCapacity: () => renderWorkerCapacity,
   renderWorkspaceStatus: () => renderWorkspaceStatus,
   renderWorkspaceSync: () => renderWorkspaceSync,
@@ -175,10 +180,12 @@ const SESSION_RUN_HELP_TEXT = [
   "  r5dctl session status <session-id>",
   '  r5dctl session prompt --worker <label> --mode <mode> --model <tier> [--delivery queue|steer|force] [--sender <name>] <session-id> "<prompt>"',
   "  r5dctl session stop <session-id>",
+  "  r5dctl session set-worker <session-id> --worker <label>",
   "  r5dctl session process-log <run-id> [--tail <n>] [--grep <pattern>]",
-  "  r5dctl [-s <session-id>] session claim <topic> [--ttl <duration>] [--note <text>]",
-  "  r5dctl [-s <session-id>] session claim <topic> --status | --renew [--ttl <duration>] | --release",
-  "  r5dctl [-s <session-id>] session claims",
+  "  r5dctl [-s <session-id>] [-p <project> --branch <branch>] session claim <topic> [--ttl <duration>] [--note <text>]",
+  "  r5dctl [-s <session-id>] [-p <project> --branch <branch>] session claim <topic> --status | --renew [--ttl <duration>] | --release",
+  "  r5dctl [-s <session-id>] [-p <project> --branch <branch>] session claims",
+  "  r5dctl [-s <session-id>] -p <project> --branch <branch> checkout path",
   "",
   "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,",
@@ -191,12 +198,19 @@ const SESSION_RUN_HELP_TEXT = [
   "on a pause, wait for the recipient's explicit reply before proceeding.",
   "claim takes atomic ownership of a topic within the session's project branch (one winner; a losing call prints the holder and expiry).",
   "Claims expire at --ttl (default 30m, max 24h) unless renewed; --renew and --release are fenced to the holder and its claim generation.",
+  "-p <project> --branch <branch> (both or neither) claims on a sibling checkout the same user owns instead of the session's own branch.",
+  "The reserved topic `checkout` declares tracked-file writes in that checkout: claim it before running the command, hold it until the",
+  "write is done, and release it. A running session native to that branch holds `checkout` implicitly, so the call names who to message.",
+  "Commands started while a cross-scope `checkout` claim is held also fence the claimed checkout on the bound worker (the fence line says",
+  "whether the worker supports it). checkout path prints where a project branch is checked out on the session's bound worker.",
   "Agent shells act as their own session; user credentials select the acting session with -s or R5D_SESSION_ID.",
   "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.",
+  "set-worker rebinds a stopped session to another connected worker: it publishes the current worker's workspace,",
+  "synchronizes the target, and the session resumes there. A running agent moves itself with its switch_worker tool.",
   ""
 ].join("\n");
 const SHARED_HELP_ENTRIES = [
@@ -211,6 +225,11 @@ const SHARED_HELP_ENTRIES = [
   { section: "auth", usage: "auth api-key list", description: "List API keys for the current account." },
   { section: "auth", usage: "auth api-key revoke <key-id>", description: "Revoke an API key." },
   { section: "workspace", usage: "workspace status", description: "Inspect per-user workspace Git state and active remediation." },
+  {
+    section: "workspace",
+    usage: "workspace recover-hydration --worker <label> --transaction <id> --confirm",
+    description: "Preserve current checkout files and archive interrupted hydration evidence, then reconcile from the previous recorded basis. Stop active worker processes first."
+  },
   {
     section: "workspace",
     usage: "workspace sync [--worker <label>]",
@@ -337,13 +356,23 @@ const SHARED_HELP_ENTRIES = [
   },
   {
     section: "sessions",
-    usage: "[-s <session-id>] session claim <topic> [--ttl <duration>] [--note <text>] [--status|--renew|--release]",
-    description: "Atomically own a coordination topic within the session's project branch; one winner, and a losing call prints the current holder and expiry. --status reads it, --renew extends your lease, --release gives it up. Agent shells act as their own session."
+    usage: "session set-worker <session-id> --worker <label>",
+    description: "Rebind a stopped session to another connected worker: publish the current worker's workspace, synchronize the target, and resume there. Refused while the agent runs; a running agent switches itself with switch_worker."
   },
   {
     section: "sessions",
-    usage: "[-s <session-id>] session claims",
-    description: "List the claims on the session's project branch with holder, generation, and expiry."
+    usage: "[-s <session-id>] [-p <project> --branch <branch>] session claim <topic> [--ttl <duration>] [--note <text>] [--status|--renew|--release]",
+    description: "Atomically own a coordination topic within the session's project branch, or with -p and --branch on a sibling checkout; one winner, and a losing call prints the current holder and expiry. --status reads it, --renew extends your lease, --release gives it up. Claim the reserved topic `checkout` before writing tracked files in another checkout. Agent shells act as their own session."
+  },
+  {
+    section: "sessions",
+    usage: "[-s <session-id>] [-p <project> --branch <branch>] session claims",
+    description: "List the claims on the session's project branch, or on a sibling checkout, with holder, origin branch, generation, and expiry."
+  },
+  {
+    section: "branches",
+    usage: "[-s <session-id>] -p <project> --branch <branch> checkout path",
+    description: "Print the absolute path of a project branch checkout on the acting session's bound worker."
   },
   {
     section: "sessions",
@@ -903,6 +932,12 @@ function parseSessionRunCommand(options, args, env = process.env) {
     if (parsed.positionals.length > 1) throw new Error(`Unexpected session ${subcommand} argument: ${parsed.positionals[1]}`);
     return { kind: subcommand, sessionId };
   }
+  if (subcommand === "set-worker") {
+    const parsed = parseCommandOperands(commandArgs, /* @__PURE__ */ new Set(["--worker"]), /* @__PURE__ */ new Map(), "session set-worker");
+    const sessionId = requireValue(parsed.positionals[0], "Session id is required for `session set-worker`");
+    if (parsed.positionals.length > 1) throw new Error(`Unexpected session set-worker argument: ${parsed.positionals[1]}`);
+    return { kind: "set-worker", sessionId, worker: requireWorker(parsed.values) };
+  }
   if (subcommand === "prompt") {
     const parsed = parseCommandOperands(
       commandArgs,
@@ -940,13 +975,25 @@ function parseSessionProcessLogArgs(args) {
   const grep = parsed.values.get("--grep");
   return { runId, ...tail !== void 0 ? { tail } : {}, ...grep !== void 0 ? { grep } : {} };
 }
+function resolveClaimScope(explicitProject, explicitBranch, options) {
+  const project = explicitProject?.trim() || options.project?.trim() || void 0;
+  const branch = explicitBranch?.trim() || options.branch?.trim() || void 0;
+  if (project === void 0 && branch === void 0) return void 0;
+  if (project === void 0 || branch === void 0) {
+    throw new Error(
+      "A scoped claim needs both -p/--project and --branch/-b; pass both to act on a sibling checkout, or neither for the session's own branch"
+    );
+  }
+  return { projectId: project, branchName: branch };
+}
 const CLAIM_DURATION_PATTERN = /^(\d+)([smh])$/;
 function parseClaimDuration(value) {
   const match = CLAIM_DURATION_PATTERN.exec(value.trim());
   if (!match) throw new Error("Invalid --ttl. Expected a duration such as 90s, 30m, or 2h");
   const amount = Number(match[1]);
   const seconds = match[2] === "s" ? amount : match[2] === "m" ? amount * 60 : amount * 3600;
-  if (!Number.isSafeInteger(seconds) || seconds < 1 || seconds > 86400) throw new Error("Invalid --ttl. Use a duration between 1s and 24h");
+  if (!Number.isSafeInteger(seconds) || seconds < 1 || seconds > 86400)
+    throw new Error("Invalid --ttl. Use a duration between 1s and 24h");
   return seconds;
 }
 function resolveClaimSessionId(explicit, options, env) {
@@ -955,7 +1002,7 @@ function resolveClaimSessionId(explicit, options, env) {
 function parseSessionClaimArgs(args, options = {}, env = process.env) {
   const parsed = parseCommandOperands(
     args,
-    /* @__PURE__ */ new Set(["--ttl", "--note", "--generation", "--session"]),
+    /* @__PURE__ */ new Set(["--ttl", "--note", "--generation", "--session", "--project", "--branch"]),
     /* @__PURE__ */ new Map([
       ["--status", "--status"],
       ["--renew", "--renew"],
@@ -968,7 +1015,8 @@ function parseSessionClaimArgs(args, options = {}, env = process.env) {
   if (parsed.booleans.size > 1) throw new Error("Use only one of --status, --renew, or --release");
   const action = parsed.booleans.has("--status") ? "status" : parsed.booleans.has("--renew") ? "renew" : parsed.booleans.has("--release") ? "release" : "acquire";
   const ttl = parsed.values.get("--ttl");
-  if (ttl !== void 0 && action !== "acquire" && action !== "renew") throw new Error("--ttl is only supported when acquiring or renewing a claim");
+  if (ttl !== void 0 && action !== "acquire" && action !== "renew")
+    throw new Error("--ttl is only supported when acquiring or renewing a claim");
   const note = parsed.values.get("--note");
   if (note !== void 0 && action !== "acquire") throw new Error("--note is only supported when acquiring a claim");
   const generationValue = parsed.values.get("--generation");
@@ -976,22 +1024,52 @@ function parseSessionClaimArgs(args, options = {}, env = process.env) {
     throw new Error("--generation is only supported with --renew or --release");
   }
   const generation = generationValue === void 0 ? void 0 : Number(generationValue);
-  if (generation !== void 0 && (!Number.isSafeInteger(generation) || generation < 1)) throw new Error("--generation must be a positive integer");
+  if (generation !== void 0 && (!Number.isSafeInteger(generation) || generation < 1))
+    throw new Error("--generation must be a positive integer");
   const sessionId = resolveClaimSessionId(parsed.values.get("--session"), options, env);
+  const scope = resolveClaimScope(parsed.values.get("--project"), parsed.values.get("--branch"), options);
   return {
     action,
     topic,
     ...sessionId ? { sessionId } : {},
+    ...scope ? { scope } : {},
     ...ttl !== void 0 ? { ttlSeconds: parseClaimDuration(ttl) } : {},
     ...note !== void 0 ? { note } : {},
     ...generation !== void 0 ? { generation } : {}
   };
 }
 function parseSessionClaimsListArgs(args, options = {}, env = process.env) {
-  const parsed = parseCommandOperands(args, /* @__PURE__ */ new Set(["--session"]), /* @__PURE__ */ new Map(), "session claims");
+  const parsed = parseCommandOperands(args, /* @__PURE__ */ new Set(["--session", "--project", "--branch"]), /* @__PURE__ */ new Map(), "session claims");
   if (parsed.positionals.length > 0) throw new Error(`Unexpected session claims argument: ${parsed.positionals[0]}`);
   const sessionId = resolveClaimSessionId(parsed.values.get("--session"), options, env);
-  return sessionId ? { sessionId } : {};
+  const scope = resolveClaimScope(parsed.values.get("--project"), parsed.values.get("--branch"), options);
+  return { ...sessionId ? { sessionId } : {}, ...scope ? { scope } : {} };
+}
+function parseCheckoutPathArgs(args, options = {}, env = process.env) {
+  const parsed = parseCommandOperands(args, /* @__PURE__ */ new Set(["--session", "--project", "--branch"]), /* @__PURE__ */ new Map(), "checkout path");
+  if (parsed.positionals.length > 0) throw new Error(`Unexpected checkout path argument: ${parsed.positionals[0]}`);
+  const projectId = parsed.values.get("--project")?.trim() || options.project?.trim();
+  const branchName = parsed.values.get("--branch")?.trim() || options.branch?.trim();
+  if (!projectId) throw new Error("--project/-p is required for `checkout path`");
+  if (!branchName) throw new Error("--branch/-b is required for `checkout path`");
+  const sessionId = resolveClaimSessionId(parsed.values.get("--session"), options, env);
+  return { projectId, branchName, ...sessionId ? { sessionId } : {} };
+}
+class R5dctlClaimScopeMismatchError extends Error {
+  constructor(requested, answered) {
+    super(
+      `The server did not apply the requested claim scope ${requested.projectId}#${requested.branchName}; it answered for ${answered.projectPath ?? answered.projectId}#${answered.branchName}. Update the r5d server before using scoped claims`
+    );
+    this.name = "R5dctlClaimScopeMismatchError";
+  }
+}
+function claimScopeMatches(requested, answered) {
+  if (!requested || !answered) return true;
+  const projectMatches = answered.projectId === requested.projectId || answered.projectPath === requested.projectId;
+  return projectMatches && answered.branchName === requested.branchName;
+}
+function assertClaimScopeEcho(requested, answered) {
+  if (!claimScopeMatches(requested, answered)) throw new R5dctlClaimScopeMismatchError(requested, answered);
 }
 const CLAIM_OUTCOME_TEXT = {
   acquired: "acquired",
@@ -1004,35 +1082,55 @@ const CLAIM_OUTCOME_TEXT = {
   released: "released"
 };
 function formatClaimExpiry(expiresAt, nowMs) {
+  if (expiresAt === null) return "while the holder runs (implicit)";
   const expiresAtMs = Date.parse(expiresAt);
   if (!Number.isFinite(expiresAtMs)) return expiresAt;
   return expiresAtMs <= nowMs ? `${expiresAt} (expired ${formatProcessAge(expiresAt, nowMs)} ago)` : `${expiresAt} (in ${formatProcessAge(new Date(nowMs).toISOString(), expiresAtMs)})`;
 }
+function describeClaimScope(scope) {
+  return `${scope.projectPath ?? scope.projectId}#${scope.branchName}`;
+}
 function describeClaimHolder(claim) {
   const name = claim.holderSessionName ? ` ${JSON.stringify(claim.holderSessionName)}` : "";
-  return `${claim.holderSessionId}${name}${claim.heldByActor ? " (this session)" : ""}`;
+  const self = claim.heldByActor ? " (this session)" : "";
+  let origin = "";
+  if (claim.holderBranchName !== void 0 && claim.holderBranchName !== null) {
+    const native = claim.holderProjectId === claim.projectId && claim.holderBranchName === claim.branchName;
+    if (native) origin = claim.implicit ? " (native, running)" : " (native)";
+    else if (claim.holderProjectId === claim.projectId) origin = ` (foreign: native to branch ${claim.holderBranchName})`;
+    else origin = ` (foreign: native to ${claim.holderProjectId ?? "unknown"}#${claim.holderBranchName})`;
+  }
+  return `${claim.holderSessionId}${name}${self}${origin}`;
+}
+function describeClaimFence(response) {
+  if (response.fenceExtended === void 0) return void 0;
+  if (response.fenceExtended)
+    return "Fence: commands this session starts while holding the claim also fence the claimed checkout on the bound worker";
+  return `Fence: claim acquired, but ${response.fenceDetail ?? "the bound worker does not fence sibling checkouts (update the worker)"}; the claim still coordinates between sessions`;
 }
 function renderSessionClaimResponse(response, nowMs = Date.now()) {
   const lines = [`Outcome: ${CLAIM_OUTCOME_TEXT[response.outcome] ?? response.outcome}`, `Acting session: ${response.actorSessionId}`];
   if (response.claim) {
     lines.push(
       `Claim: ${response.claim.topic}`,
-      `Branch: ${response.claim.branchName}`,
+      `Scope: ${describeClaimScope(response.claim)}`,
       `Holder: ${describeClaimHolder(response.claim)}`,
       `Generation: ${response.claim.generation}`,
       `Expires: ${formatClaimExpiry(response.claim.expiresAt, nowMs)}`
     );
     if (response.claim.note) lines.push(`Note: ${response.claim.note}`);
   }
+  const fence = describeClaimFence(response);
+  if (fence) lines.push(fence);
   return `${lines.join("\n")}
 `;
 }
 function renderSessionClaimList(response, nowMs = Date.now()) {
-  const header = `Claims on ${response.branchName} (acting session ${response.actorSessionId})`;
+  const header = `Claims on ${describeClaimScope(response)} (acting session ${response.actorSessionId})`;
   if (response.claims.length === 0) return `${header}: none
 `;
   const rows = response.claims.map((claim) => {
-    const expiry = claim.expired ? "expired" : "expires";
+    const expiry = claim.expired ? "expired" : claim.expiresAt === null ? "held" : "expires";
     const note = claim.note ? `  note: ${claim.note}` : "";
     return `- ${claim.topic}  holder ${describeClaimHolder(claim)}  generation ${claim.generation}  ${expiry} ${formatClaimExpiry(claim.expiresAt, nowMs)}${note}`;
   });
@@ -1040,6 +1138,11 @@ function renderSessionClaimList(response, nowMs = Date.now()) {
 ${rows.join("\n")}
 `;
 }
+function renderCheckoutPath(response) {
+  return [`Checkout: ${response.projectPath}#${response.branchName}`, `Worker: ${response.worker}`, `Path: ${response.path}`, ""].join(
+    "\n"
+  );
+}
 function assertAuthLoginArgs(args) {
   const valueFlags = /* @__PURE__ */ new Set(["--device-name", "--worker-label"]);
   const booleanFlags = /* @__PURE__ */ new Set(["--no-open", "--no-qr"]);
@@ -1881,6 +1984,12 @@ 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}`,
+      ...worker.hydrationRecovery ? [
+        `  Interrupted hydration ${worker.hydrationRecovery.transactionId}: files and snapshots preserved; execution is fenced.`,
+        `  Evidence: ${worker.hydrationRecovery.transactionPath}`,
+        ...(worker.hydrationRecovery.retainedPaths ?? []).map((retainedPath) => `  Retained writer entry: ${retainedPath}`),
+        `  After stopping active processes: r5dctl workspace recover-hydration --worker ${JSON.stringify(worker.workerLabel)} --transaction ${worker.hydrationRecovery.transactionId} --confirm`
+      ] : [],
       ...renderMissingCheckouts(worker.workerLabel, worker.missingCheckouts ?? []),
       ...renderWorkerCapacity(worker.workerLabel, worker.capacity)
     ])
@@ -1888,6 +1997,15 @@ function renderWorkspaceStatus(status) {
   if (status.latestSync?.missingCheckouts?.length && !status.workers.some((worker) => worker.missingCheckouts?.length)) {
     lines.push(...renderMissingCheckouts(status.latestSync.workerLabel, status.latestSync.missingCheckouts));
   }
+  if (status.latestSync?.hydrationRecovery && !status.workers.some((worker) => worker.workerLabel === status.latestSync.workerLabel)) {
+    lines.push(
+      `Disconnected worker ${status.latestSync.workerLabel} reported interrupted hydration ${status.latestSync.hydrationRecovery.transactionId}; preserved evidence: ${status.latestSync.hydrationRecovery.transactionPath}. Reconnect it, inspect workspace status, and preserve the transaction before resuming work.`,
+      ...(status.latestSync.hydrationRecovery.retainedPaths ?? []).map((retainedPath) => `  Retained writer entry: ${retainedPath}`)
+    );
+  }
+  for (const [mountId, skip] of Object.entries(status.latestSync?.mountSkipReasons ?? {})) {
+    for (const retainedPath of skip.retainedPaths ?? []) lines.push(`Retained writer entry for ${mountId}: ${retainedPath}`);
+  }
   return `${lines.join("\n")}
 `;
 }
@@ -2174,11 +2292,17 @@ function renderSessionRunStart(session) {
   lines.push(`Worker: ${responseString(session, "worker") ?? "(unassigned)"}`);
   const sessionUrl = responseString(session, "sessionUrl");
   if (sessionUrl) lines.push(`URL: ${sessionUrl}`);
+  lines.push(...formatSessionWarningLines(session));
   const sessionId = responseString(session, "sessionId");
   if (sessionId) lines.push("", `Next: r5dctl session status ${sessionId}`);
   return `${lines.join("\n")}
 `;
 }
+function formatSessionWarningLines(session) {
+  const warnings = session.warnings;
+  if (!Array.isArray(warnings)) return [];
+  return warnings.filter((warning) => typeof warning === "string" && warning.length > 0).map((warning) => `Warning: ${warning}`);
+}
 function formatBranchStateHint(branch) {
   const target = branch ?? "<branch>";
   const commands = [
@@ -2229,6 +2353,7 @@ function renderSessionRunStatus(session) {
   }
   const childSessions = formatChildSessionsLine(session);
   if (childSessions) lines.push(childSessions);
+  lines.push(...formatSessionWarningLines(session));
   lines.push(`Branch state: ${formatBranchStateHint(branch)}`);
   const error = responseString(session, "error");
   if (error) lines.push(`Error: ${error}`);
@@ -2279,9 +2404,23 @@ async function dispatchSessionRunCommand(client, command) {
     });
     return { data: data2, human: renderSessionRunStatus(data2) };
   }
+  if (command.kind === "set-worker") {
+    const data2 = await client.sessions.setWorker(command.sessionId, { worker: command.worker });
+    return { data: data2, human: renderSessionSetWorker(data2) };
+  }
   const data = await client.sessions.stop(command.sessionId);
   return { data, human: renderSessionRunStatus(data) };
 }
+function renderSessionSetWorker(response) {
+  const previous = typeof response.previousWorker === "string" && response.previousWorker.length > 0 ? response.previousWorker : null;
+  const lines = [
+    `Session: ${responseString(response, "sessionId") ?? "(unknown)"}`,
+    `Worker: ${responseString(response, "worker") ?? "(unassigned)"}${previous ? ` (was ${previous})` : ""}`,
+    "The session resumes on this worker; shell runs and sub-agents started earlier stay where they ran."
+  ];
+  return `${lines.join("\n")}
+`;
+}
 async function waitForSessionProvisioning(client, initial, options = {}) {
   const sessionId = requireValue(responseString(initial, "sessionId"), "Session start did not return a session id");
   const wait = options.wait ?? import_promises.setTimeout;
@@ -2841,6 +2980,23 @@ async function executeR5dctlCommand(client, json, args) {
     write(result, renderWorkspaceSync(result));
     return;
   }
+  if (first === "workspace" && second === "recover-hydration") {
+    let worker;
+    let transactionId;
+    let confirmed = false;
+    for (let index = 2; index < args.length; index += 1) {
+      const arg = args[index];
+      if (arg === "--worker") worker = requireValue(args[++index], "Missing worker label");
+      else if (arg === "--transaction") transactionId = requireValue(args[++index], "Missing transaction id");
+      else if (arg === "--confirm") confirmed = true;
+      else throw new Error(`Unexpected recovery argument: ${arg}`);
+    }
+    if (!worker || !transactionId || !confirmed)
+      throw new Error("workspace recover-hydration requires --worker, --transaction and --confirm; inspect workspace status first");
+    const result = await client.workspace.recoverHydration({ worker, transactionId, confirmed: true });
+    write(result, renderWorkspaceSync(result));
+    return;
+  }
   if (first === "workspace" && second === "reset") {
     const parsed = parseWorkspaceWorkerArgs(args.slice(2), { allowConfirm: true });
     const result = await client.workspace.reset({ worker: parsed.worker, confirmed: true });
@@ -2871,7 +3027,7 @@ async function executeR5dctlCommand(client, json, args) {
   }
   if (first === "session" && second === "claim") {
     const claim = parseSessionClaimArgs(args.slice(2), {}, {});
-    const scope = claim.sessionId ? { sessionId: claim.sessionId } : {};
+    const scope = { ...claim.sessionId ? { sessionId: claim.sessionId } : {}, ...claim.scope ? { scope: claim.scope } : {} };
     const nowMs = Date.now();
     if (claim.action === "acquire") {
       const result2 = await client.claims.acquire({
@@ -2880,23 +3036,34 @@ async function executeR5dctlCommand(client, json, args) {
         ...claim.ttlSeconds !== void 0 ? { ttlSeconds: claim.ttlSeconds } : {},
         ...claim.note !== void 0 ? { note: claim.note } : {}
       });
+      if (!claimScopeMatches(claim.scope, result2.claim)) {
+        if (result2.outcome === "acquired" && result2.claim.heldByActor) {
+          await client.claims.release({
+            topic: claim.topic,
+            ...claim.sessionId ? { sessionId: claim.sessionId } : {},
+            generation: result2.claim.generation
+          }).catch(() => void 0);
+        }
+        throw new R5dctlClaimScopeMismatchError(claim.scope, result2.claim);
+      }
       write(result2, renderSessionClaimResponse(result2, nowMs));
       if (result2.outcome === "held_by_other") {
-        throw new Error(
-          `Claim ${claim.topic} is held by session ${result2.claim.holderSessionId} until ${result2.claim.expiresAt}; not acquired`
-        );
+        const until = result2.claim.expiresAt === null ? "while it runs (native session)" : `until ${result2.claim.expiresAt}`;
+        throw new Error(`Claim ${claim.topic} is held by session ${result2.claim.holderSessionId} ${until}; not acquired`);
       }
       return;
     }
     if (claim.action === "status") {
       const list = await client.claims.list({ ...scope, topic: claim.topic });
+      assertClaimScopeEcho(claim.scope, list);
       write(list, renderSessionClaimList(list, nowMs));
       return;
     }
     let generation = claim.generation;
-    if (generation === void 0) {
+    if (generation === void 0 || claim.scope) {
       const list = await client.claims.list({ ...scope, topic: claim.topic });
-      const current = list.claims[0];
+      assertClaimScopeEcho(claim.scope, list);
+      const current = list.claims.find((entry) => entry.heldByActor) ?? list.claims[0];
       if (!current) {
         write({ outcome: "missing", actorSessionId: list.actorSessionId, claim: null }, `No claim on ${claim.topic}.
 `);
@@ -2910,7 +3077,7 @@ async function executeR5dctlCommand(client, json, args) {
         );
         throw new Error(`Claim ${claim.topic} is held by session ${current.holderSessionId}, not by ${list.actorSessionId}`);
       }
-      generation = current.generation;
+      generation ??= current.generation;
     }
     const result = claim.action === "renew" ? await client.claims.renew({
       topic: claim.topic,
@@ -2918,16 +3085,25 @@ async function executeR5dctlCommand(client, json, args) {
       generation,
       ...claim.ttlSeconds !== void 0 ? { ttlSeconds: claim.ttlSeconds } : {}
     }) : await client.claims.release({ topic: claim.topic, ...scope, generation });
+    assertClaimScopeEcho(claim.scope, result.claim);
     write(result, renderSessionClaimResponse(result, nowMs));
     const succeeded = result.outcome === "renewed" || result.outcome === "released" || claim.action === "release" && result.outcome === "missing";
     if (!succeeded) throw new Error(`Claim ${claim.topic}: ${CLAIM_OUTCOME_TEXT[result.outcome] ?? result.outcome}`);
     return;
   }
   if (first === "session" && second === "claims") {
-    const list = await client.claims.list(parseSessionClaimsListArgs(args.slice(2), {}, {}));
+    const selection = parseSessionClaimsListArgs(args.slice(2), {}, {});
+    const list = await client.claims.list(selection);
+    assertClaimScopeEcho(selection.scope, list);
     write(list, renderSessionClaimList(list));
     return;
   }
+  if (first === "checkout" && second === "path") {
+    const selection = parseCheckoutPathArgs(args.slice(2), {}, {});
+    const result = await client.checkouts.path(selection);
+    write(result, renderCheckoutPath(result));
+    return;
+  }
   if (first === "session" && second === "process-log") {
     const selection = parseSessionProcessLogArgs(args.slice(2));
     const log = await client.processes.log(selection.runId, {
@@ -3027,7 +3203,8 @@ ${result.deletion ? `Deletion: ${result.deletion.status}${result.deletion.error
       throw new Error(branchDeletionsConfirmationMessage(deletion.branches));
     }
     if (json) write({ results: deletion.results }, "");
-    if (deletion.results.some((result) => !result.deleted && !result.accepted)) throw new Error(branchDeletionsFailureMessage(deletion.results));
+    if (deletion.results.some((result) => !result.deleted && !result.accepted))
+      throw new Error(branchDeletionsFailureMessage(deletion.results));
     return;
   }
   if (first === "projects" && second === "branches" && third === "describe-deletion" || first === "describe" && second === "branch-deletion") {
@@ -3624,24 +3801,43 @@ function resolveCommandExecution(options, rest) {
       ...parseShellArgs(commandArgs)
     };
   }
+  if (command === "checkout") {
+    if (commandArgs[0] !== "path") throw new Error("Unknown checkout command");
+    const parsed = parseCheckoutPathArgs(commandArgs.slice(1), options);
+    return {
+      kind: "plugin",
+      pluginArgs: [
+        "checkout",
+        "path",
+        `--project=${parsed.projectId}`,
+        `--branch=${parsed.branchName}`,
+        ...parsed.sessionId ? [`--session=${parsed.sessionId}`] : []
+      ]
+    };
+  }
   if (command === "session") {
     if (commandArgs[0] === "claim" || commandArgs[0] === "claims") {
-      if (options.project) throw new Error("--project/-p is not supported for `session claim`; the acting session selects the project branch");
-      if (options.branch) throw new Error("--branch/-b is not supported for `session claim`; the acting session selects the branch");
       const parsed = commandArgs[0] === "claim" ? parseSessionClaimArgs(commandArgs.slice(1), options) : parseSessionClaimsListArgs(commandArgs.slice(1), options);
-      const withoutSessionValue = [];
+      const normalizedFlags = /* @__PURE__ */ new Set(["--session", "--project", "--branch"]);
+      const withoutNormalizedValues = [];
       for (let index = 0; index < commandArgs.slice(1).length; index += 1) {
         const arg = commandArgs.slice(1)[index];
-        if (arg === "--session") {
+        if (normalizedFlags.has(arg)) {
           index += 1;
           continue;
         }
-        if (arg.startsWith("--session=")) continue;
-        withoutSessionValue.push(arg);
+        if ([...normalizedFlags].some((flag) => arg.startsWith(`${flag}=`))) continue;
+        withoutNormalizedValues.push(arg);
       }
       return {
         kind: "plugin",
-        pluginArgs: ["session", commandArgs[0], ...withoutSessionValue, ...parsed.sessionId ? [`--session=${parsed.sessionId}`] : []]
+        pluginArgs: [
+          "session",
+          commandArgs[0],
+          ...withoutNormalizedValues,
+          ...parsed.scope ? [`--project=${parsed.scope.projectId}`, `--branch=${parsed.scope.branchName}`] : [],
+          ...parsed.sessionId ? [`--session=${parsed.sessionId}`] : []
+        ]
       };
     }
     if (commandArgs[0] === "process-log") {
@@ -3815,10 +4011,12 @@ async function main(argv = process.argv.slice(2)) {
 0 && (module.exports = {
   BRANCH_DELETION_POLL_INTERVAL_MS,
   BRANCH_DELETION_WAIT_TIMEOUT_MS,
+  R5dctlClaimScopeMismatchError,
   advanceTransientDevicePollBackoff,
   branchDeletionConfirmationMessage,
   branchDeletionsConfirmationMessage,
   branchDeletionsFailureMessage,
+  claimScopeMatches,
   createBranchThroughPlatform,
   deleteBranchThroughPlatform,
   deleteBranchesThroughPlatform,
@@ -3838,6 +4036,7 @@ async function main(argv = process.argv.slice(2)) {
   parseAnswerQuestionsCommandArgs,
   parseBranchCreateArgs,
   parseBranchDeleteArgs,
+  parseCheckoutPathArgs,
   parseClaimDuration,
   parseConversationForkArgs,
   parseConversationInspectWorkArgs,
@@ -3863,6 +4062,7 @@ async function main(argv = process.argv.slice(2)) {
   renderBranchDeletionStatus,
   renderBranchList,
   renderBranchOperation,
+  renderCheckoutPath,
   renderConversationForkResponse,
   renderConversationHeadResponse,
   renderConversationNodeResponse,
@@ -3880,6 +4080,7 @@ async function main(argv = process.argv.slice(2)) {
   renderSessionList,
   renderSessionRunStart,
   renderSessionRunStatus,
+  renderSessionSetWorker,
   renderWorkerCapacity,
   renderWorkspaceStatus,
   renderWorkspaceSync,

package/dist/cjs/package.json

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

package/dist/mjs/cli.mjs

@@ -70,10 +70,12 @@ const SESSION_RUN_HELP_TEXT = [
   "  r5dctl session status <session-id>",
   '  r5dctl session prompt --worker <label> --mode <mode> --model <tier> [--delivery queue|steer|force] [--sender <name>] <session-id> "<prompt>"',
   "  r5dctl session stop <session-id>",
+  "  r5dctl session set-worker <session-id> --worker <label>",
   "  r5dctl session process-log <run-id> [--tail <n>] [--grep <pattern>]",
-  "  r5dctl [-s <session-id>] session claim <topic> [--ttl <duration>] [--note <text>]",
-  "  r5dctl [-s <session-id>] session claim <topic> --status | --renew [--ttl <duration>] | --release",
-  "  r5dctl [-s <session-id>] session claims",
+  "  r5dctl [-s <session-id>] [-p <project> --branch <branch>] session claim <topic> [--ttl <duration>] [--note <text>]",
+  "  r5dctl [-s <session-id>] [-p <project> --branch <branch>] session claim <topic> --status | --renew [--ttl <duration>] | --release",
+  "  r5dctl [-s <session-id>] [-p <project> --branch <branch>] session claims",
+  "  r5dctl [-s <session-id>] -p <project> --branch <branch> checkout path",
   "",
   "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,",
@@ -86,12 +88,19 @@ const SESSION_RUN_HELP_TEXT = [
   "on a pause, wait for the recipient's explicit reply before proceeding.",
   "claim takes atomic ownership of a topic within the session's project branch (one winner; a losing call prints the holder and expiry).",
   "Claims expire at --ttl (default 30m, max 24h) unless renewed; --renew and --release are fenced to the holder and its claim generation.",
+  "-p <project> --branch <branch> (both or neither) claims on a sibling checkout the same user owns instead of the session's own branch.",
+  "The reserved topic `checkout` declares tracked-file writes in that checkout: claim it before running the command, hold it until the",
+  "write is done, and release it. A running session native to that branch holds `checkout` implicitly, so the call names who to message.",
+  "Commands started while a cross-scope `checkout` claim is held also fence the claimed checkout on the bound worker (the fence line says",
+  "whether the worker supports it). checkout path prints where a project branch is checked out on the session's bound worker.",
   "Agent shells act as their own session; user credentials select the acting session with -s or R5D_SESSION_ID.",
   "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.",
+  "set-worker rebinds a stopped session to another connected worker: it publishes the current worker's workspace,",
+  "synchronizes the target, and the session resumes there. A running agent moves itself with its switch_worker tool.",
   ""
 ].join("\n");
 const SHARED_HELP_ENTRIES = [
@@ -106,6 +115,11 @@ const SHARED_HELP_ENTRIES = [
   { section: "auth", usage: "auth api-key list", description: "List API keys for the current account." },
   { section: "auth", usage: "auth api-key revoke <key-id>", description: "Revoke an API key." },
   { section: "workspace", usage: "workspace status", description: "Inspect per-user workspace Git state and active remediation." },
+  {
+    section: "workspace",
+    usage: "workspace recover-hydration --worker <label> --transaction <id> --confirm",
+    description: "Preserve current checkout files and archive interrupted hydration evidence, then reconcile from the previous recorded basis. Stop active worker processes first."
+  },
   {
     section: "workspace",
     usage: "workspace sync [--worker <label>]",
@@ -232,13 +246,23 @@ const SHARED_HELP_ENTRIES = [
   },
   {
     section: "sessions",
-    usage: "[-s <session-id>] session claim <topic> [--ttl <duration>] [--note <text>] [--status|--renew|--release]",
-    description: "Atomically own a coordination topic within the session's project branch; one winner, and a losing call prints the current holder and expiry. --status reads it, --renew extends your lease, --release gives it up. Agent shells act as their own session."
+    usage: "session set-worker <session-id> --worker <label>",
+    description: "Rebind a stopped session to another connected worker: publish the current worker's workspace, synchronize the target, and resume there. Refused while the agent runs; a running agent switches itself with switch_worker."
   },
   {
     section: "sessions",
-    usage: "[-s <session-id>] session claims",
-    description: "List the claims on the session's project branch with holder, generation, and expiry."
+    usage: "[-s <session-id>] [-p <project> --branch <branch>] session claim <topic> [--ttl <duration>] [--note <text>] [--status|--renew|--release]",
+    description: "Atomically own a coordination topic within the session's project branch, or with -p and --branch on a sibling checkout; one winner, and a losing call prints the current holder and expiry. --status reads it, --renew extends your lease, --release gives it up. Claim the reserved topic `checkout` before writing tracked files in another checkout. Agent shells act as their own session."
+  },
+  {
+    section: "sessions",
+    usage: "[-s <session-id>] [-p <project> --branch <branch>] session claims",
+    description: "List the claims on the session's project branch, or on a sibling checkout, with holder, origin branch, generation, and expiry."
+  },
+  {
+    section: "branches",
+    usage: "[-s <session-id>] -p <project> --branch <branch> checkout path",
+    description: "Print the absolute path of a project branch checkout on the acting session's bound worker."
   },
   {
     section: "sessions",
@@ -798,6 +822,12 @@ function parseSessionRunCommand(options, args, env = process.env) {
     if (parsed.positionals.length > 1) throw new Error(`Unexpected session ${subcommand} argument: ${parsed.positionals[1]}`);
     return { kind: subcommand, sessionId };
   }
+  if (subcommand === "set-worker") {
+    const parsed = parseCommandOperands(commandArgs, /* @__PURE__ */ new Set(["--worker"]), /* @__PURE__ */ new Map(), "session set-worker");
+    const sessionId = requireValue(parsed.positionals[0], "Session id is required for `session set-worker`");
+    if (parsed.positionals.length > 1) throw new Error(`Unexpected session set-worker argument: ${parsed.positionals[1]}`);
+    return { kind: "set-worker", sessionId, worker: requireWorker(parsed.values) };
+  }
   if (subcommand === "prompt") {
     const parsed = parseCommandOperands(
       commandArgs,
@@ -835,13 +865,25 @@ function parseSessionProcessLogArgs(args) {
   const grep = parsed.values.get("--grep");
   return { runId, ...tail !== void 0 ? { tail } : {}, ...grep !== void 0 ? { grep } : {} };
 }
+function resolveClaimScope(explicitProject, explicitBranch, options) {
+  const project = explicitProject?.trim() || options.project?.trim() || void 0;
+  const branch = explicitBranch?.trim() || options.branch?.trim() || void 0;
+  if (project === void 0 && branch === void 0) return void 0;
+  if (project === void 0 || branch === void 0) {
+    throw new Error(
+      "A scoped claim needs both -p/--project and --branch/-b; pass both to act on a sibling checkout, or neither for the session's own branch"
+    );
+  }
+  return { projectId: project, branchName: branch };
+}
 const CLAIM_DURATION_PATTERN = /^(\d+)([smh])$/;
 function parseClaimDuration(value) {
   const match = CLAIM_DURATION_PATTERN.exec(value.trim());
   if (!match) throw new Error("Invalid --ttl. Expected a duration such as 90s, 30m, or 2h");
   const amount = Number(match[1]);
   const seconds = match[2] === "s" ? amount : match[2] === "m" ? amount * 60 : amount * 3600;
-  if (!Number.isSafeInteger(seconds) || seconds < 1 || seconds > 86400) throw new Error("Invalid --ttl. Use a duration between 1s and 24h");
+  if (!Number.isSafeInteger(seconds) || seconds < 1 || seconds > 86400)
+    throw new Error("Invalid --ttl. Use a duration between 1s and 24h");
   return seconds;
 }
 function resolveClaimSessionId(explicit, options, env) {
@@ -850,7 +892,7 @@ function resolveClaimSessionId(explicit, options, env) {
 function parseSessionClaimArgs(args, options = {}, env = process.env) {
   const parsed = parseCommandOperands(
     args,
-    /* @__PURE__ */ new Set(["--ttl", "--note", "--generation", "--session"]),
+    /* @__PURE__ */ new Set(["--ttl", "--note", "--generation", "--session", "--project", "--branch"]),
     /* @__PURE__ */ new Map([
       ["--status", "--status"],
       ["--renew", "--renew"],
@@ -863,7 +905,8 @@ function parseSessionClaimArgs(args, options = {}, env = process.env) {
   if (parsed.booleans.size > 1) throw new Error("Use only one of --status, --renew, or --release");
   const action = parsed.booleans.has("--status") ? "status" : parsed.booleans.has("--renew") ? "renew" : parsed.booleans.has("--release") ? "release" : "acquire";
   const ttl = parsed.values.get("--ttl");
-  if (ttl !== void 0 && action !== "acquire" && action !== "renew") throw new Error("--ttl is only supported when acquiring or renewing a claim");
+  if (ttl !== void 0 && action !== "acquire" && action !== "renew")
+    throw new Error("--ttl is only supported when acquiring or renewing a claim");
   const note = parsed.values.get("--note");
   if (note !== void 0 && action !== "acquire") throw new Error("--note is only supported when acquiring a claim");
   const generationValue = parsed.values.get("--generation");
@@ -871,22 +914,52 @@ function parseSessionClaimArgs(args, options = {}, env = process.env) {
     throw new Error("--generation is only supported with --renew or --release");
   }
   const generation = generationValue === void 0 ? void 0 : Number(generationValue);
-  if (generation !== void 0 && (!Number.isSafeInteger(generation) || generation < 1)) throw new Error("--generation must be a positive integer");
+  if (generation !== void 0 && (!Number.isSafeInteger(generation) || generation < 1))
+    throw new Error("--generation must be a positive integer");
   const sessionId = resolveClaimSessionId(parsed.values.get("--session"), options, env);
+  const scope = resolveClaimScope(parsed.values.get("--project"), parsed.values.get("--branch"), options);
   return {
     action,
     topic,
     ...sessionId ? { sessionId } : {},
+    ...scope ? { scope } : {},
     ...ttl !== void 0 ? { ttlSeconds: parseClaimDuration(ttl) } : {},
     ...note !== void 0 ? { note } : {},
     ...generation !== void 0 ? { generation } : {}
   };
 }
 function parseSessionClaimsListArgs(args, options = {}, env = process.env) {
-  const parsed = parseCommandOperands(args, /* @__PURE__ */ new Set(["--session"]), /* @__PURE__ */ new Map(), "session claims");
+  const parsed = parseCommandOperands(args, /* @__PURE__ */ new Set(["--session", "--project", "--branch"]), /* @__PURE__ */ new Map(), "session claims");
   if (parsed.positionals.length > 0) throw new Error(`Unexpected session claims argument: ${parsed.positionals[0]}`);
   const sessionId = resolveClaimSessionId(parsed.values.get("--session"), options, env);
-  return sessionId ? { sessionId } : {};
+  const scope = resolveClaimScope(parsed.values.get("--project"), parsed.values.get("--branch"), options);
+  return { ...sessionId ? { sessionId } : {}, ...scope ? { scope } : {} };
+}
+function parseCheckoutPathArgs(args, options = {}, env = process.env) {
+  const parsed = parseCommandOperands(args, /* @__PURE__ */ new Set(["--session", "--project", "--branch"]), /* @__PURE__ */ new Map(), "checkout path");
+  if (parsed.positionals.length > 0) throw new Error(`Unexpected checkout path argument: ${parsed.positionals[0]}`);
+  const projectId = parsed.values.get("--project")?.trim() || options.project?.trim();
+  const branchName = parsed.values.get("--branch")?.trim() || options.branch?.trim();
+  if (!projectId) throw new Error("--project/-p is required for `checkout path`");
+  if (!branchName) throw new Error("--branch/-b is required for `checkout path`");
+  const sessionId = resolveClaimSessionId(parsed.values.get("--session"), options, env);
+  return { projectId, branchName, ...sessionId ? { sessionId } : {} };
+}
+class R5dctlClaimScopeMismatchError extends Error {
+  constructor(requested, answered) {
+    super(
+      `The server did not apply the requested claim scope ${requested.projectId}#${requested.branchName}; it answered for ${answered.projectPath ?? answered.projectId}#${answered.branchName}. Update the r5d server before using scoped claims`
+    );
+    this.name = "R5dctlClaimScopeMismatchError";
+  }
+}
+function claimScopeMatches(requested, answered) {
+  if (!requested || !answered) return true;
+  const projectMatches = answered.projectId === requested.projectId || answered.projectPath === requested.projectId;
+  return projectMatches && answered.branchName === requested.branchName;
+}
+function assertClaimScopeEcho(requested, answered) {
+  if (!claimScopeMatches(requested, answered)) throw new R5dctlClaimScopeMismatchError(requested, answered);
 }
 const CLAIM_OUTCOME_TEXT = {
   acquired: "acquired",
@@ -899,35 +972,55 @@ const CLAIM_OUTCOME_TEXT = {
   released: "released"
 };
 function formatClaimExpiry(expiresAt, nowMs) {
+  if (expiresAt === null) return "while the holder runs (implicit)";
   const expiresAtMs = Date.parse(expiresAt);
   if (!Number.isFinite(expiresAtMs)) return expiresAt;
   return expiresAtMs <= nowMs ? `${expiresAt} (expired ${formatProcessAge(expiresAt, nowMs)} ago)` : `${expiresAt} (in ${formatProcessAge(new Date(nowMs).toISOString(), expiresAtMs)})`;
 }
+function describeClaimScope(scope) {
+  return `${scope.projectPath ?? scope.projectId}#${scope.branchName}`;
+}
 function describeClaimHolder(claim) {
   const name = claim.holderSessionName ? ` ${JSON.stringify(claim.holderSessionName)}` : "";
-  return `${claim.holderSessionId}${name}${claim.heldByActor ? " (this session)" : ""}`;
+  const self = claim.heldByActor ? " (this session)" : "";
+  let origin = "";
+  if (claim.holderBranchName !== void 0 && claim.holderBranchName !== null) {
+    const native = claim.holderProjectId === claim.projectId && claim.holderBranchName === claim.branchName;
+    if (native) origin = claim.implicit ? " (native, running)" : " (native)";
+    else if (claim.holderProjectId === claim.projectId) origin = ` (foreign: native to branch ${claim.holderBranchName})`;
+    else origin = ` (foreign: native to ${claim.holderProjectId ?? "unknown"}#${claim.holderBranchName})`;
+  }
+  return `${claim.holderSessionId}${name}${self}${origin}`;
+}
+function describeClaimFence(response) {
+  if (response.fenceExtended === void 0) return void 0;
+  if (response.fenceExtended)
+    return "Fence: commands this session starts while holding the claim also fence the claimed checkout on the bound worker";
+  return `Fence: claim acquired, but ${response.fenceDetail ?? "the bound worker does not fence sibling checkouts (update the worker)"}; the claim still coordinates between sessions`;
 }
 function renderSessionClaimResponse(response, nowMs = Date.now()) {
   const lines = [`Outcome: ${CLAIM_OUTCOME_TEXT[response.outcome] ?? response.outcome}`, `Acting session: ${response.actorSessionId}`];
   if (response.claim) {
     lines.push(
       `Claim: ${response.claim.topic}`,
-      `Branch: ${response.claim.branchName}`,
+      `Scope: ${describeClaimScope(response.claim)}`,
       `Holder: ${describeClaimHolder(response.claim)}`,
       `Generation: ${response.claim.generation}`,
       `Expires: ${formatClaimExpiry(response.claim.expiresAt, nowMs)}`
     );
     if (response.claim.note) lines.push(`Note: ${response.claim.note}`);
   }
+  const fence = describeClaimFence(response);
+  if (fence) lines.push(fence);
   return `${lines.join("\n")}
 `;
 }
 function renderSessionClaimList(response, nowMs = Date.now()) {
-  const header = `Claims on ${response.branchName} (acting session ${response.actorSessionId})`;
+  const header = `Claims on ${describeClaimScope(response)} (acting session ${response.actorSessionId})`;
   if (response.claims.length === 0) return `${header}: none
 `;
   const rows = response.claims.map((claim) => {
-    const expiry = claim.expired ? "expired" : "expires";
+    const expiry = claim.expired ? "expired" : claim.expiresAt === null ? "held" : "expires";
     const note = claim.note ? `  note: ${claim.note}` : "";
     return `- ${claim.topic}  holder ${describeClaimHolder(claim)}  generation ${claim.generation}  ${expiry} ${formatClaimExpiry(claim.expiresAt, nowMs)}${note}`;
   });
@@ -935,6 +1028,11 @@ function renderSessionClaimList(response, nowMs = Date.now()) {
 ${rows.join("\n")}
 `;
 }
+function renderCheckoutPath(response) {
+  return [`Checkout: ${response.projectPath}#${response.branchName}`, `Worker: ${response.worker}`, `Path: ${response.path}`, ""].join(
+    "\n"
+  );
+}
 function assertAuthLoginArgs(args) {
   const valueFlags = /* @__PURE__ */ new Set(["--device-name", "--worker-label"]);
   const booleanFlags = /* @__PURE__ */ new Set(["--no-open", "--no-qr"]);
@@ -1776,6 +1874,12 @@ 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}`,
+      ...worker.hydrationRecovery ? [
+        `  Interrupted hydration ${worker.hydrationRecovery.transactionId}: files and snapshots preserved; execution is fenced.`,
+        `  Evidence: ${worker.hydrationRecovery.transactionPath}`,
+        ...(worker.hydrationRecovery.retainedPaths ?? []).map((retainedPath) => `  Retained writer entry: ${retainedPath}`),
+        `  After stopping active processes: r5dctl workspace recover-hydration --worker ${JSON.stringify(worker.workerLabel)} --transaction ${worker.hydrationRecovery.transactionId} --confirm`
+      ] : [],
       ...renderMissingCheckouts(worker.workerLabel, worker.missingCheckouts ?? []),
       ...renderWorkerCapacity(worker.workerLabel, worker.capacity)
     ])
@@ -1783,6 +1887,15 @@ function renderWorkspaceStatus(status) {
   if (status.latestSync?.missingCheckouts?.length && !status.workers.some((worker) => worker.missingCheckouts?.length)) {
     lines.push(...renderMissingCheckouts(status.latestSync.workerLabel, status.latestSync.missingCheckouts));
   }
+  if (status.latestSync?.hydrationRecovery && !status.workers.some((worker) => worker.workerLabel === status.latestSync.workerLabel)) {
+    lines.push(
+      `Disconnected worker ${status.latestSync.workerLabel} reported interrupted hydration ${status.latestSync.hydrationRecovery.transactionId}; preserved evidence: ${status.latestSync.hydrationRecovery.transactionPath}. Reconnect it, inspect workspace status, and preserve the transaction before resuming work.`,
+      ...(status.latestSync.hydrationRecovery.retainedPaths ?? []).map((retainedPath) => `  Retained writer entry: ${retainedPath}`)
+    );
+  }
+  for (const [mountId, skip] of Object.entries(status.latestSync?.mountSkipReasons ?? {})) {
+    for (const retainedPath of skip.retainedPaths ?? []) lines.push(`Retained writer entry for ${mountId}: ${retainedPath}`);
+  }
   return `${lines.join("\n")}
 `;
 }
@@ -2069,11 +2182,17 @@ function renderSessionRunStart(session) {
   lines.push(`Worker: ${responseString(session, "worker") ?? "(unassigned)"}`);
   const sessionUrl = responseString(session, "sessionUrl");
   if (sessionUrl) lines.push(`URL: ${sessionUrl}`);
+  lines.push(...formatSessionWarningLines(session));
   const sessionId = responseString(session, "sessionId");
   if (sessionId) lines.push("", `Next: r5dctl session status ${sessionId}`);
   return `${lines.join("\n")}
 `;
 }
+function formatSessionWarningLines(session) {
+  const warnings = session.warnings;
+  if (!Array.isArray(warnings)) return [];
+  return warnings.filter((warning) => typeof warning === "string" && warning.length > 0).map((warning) => `Warning: ${warning}`);
+}
 function formatBranchStateHint(branch) {
   const target = branch ?? "<branch>";
   const commands = [
@@ -2124,6 +2243,7 @@ function renderSessionRunStatus(session) {
   }
   const childSessions = formatChildSessionsLine(session);
   if (childSessions) lines.push(childSessions);
+  lines.push(...formatSessionWarningLines(session));
   lines.push(`Branch state: ${formatBranchStateHint(branch)}`);
   const error = responseString(session, "error");
   if (error) lines.push(`Error: ${error}`);
@@ -2174,9 +2294,23 @@ async function dispatchSessionRunCommand(client, command) {
     });
     return { data: data2, human: renderSessionRunStatus(data2) };
   }
+  if (command.kind === "set-worker") {
+    const data2 = await client.sessions.setWorker(command.sessionId, { worker: command.worker });
+    return { data: data2, human: renderSessionSetWorker(data2) };
+  }
   const data = await client.sessions.stop(command.sessionId);
   return { data, human: renderSessionRunStatus(data) };
 }
+function renderSessionSetWorker(response) {
+  const previous = typeof response.previousWorker === "string" && response.previousWorker.length > 0 ? response.previousWorker : null;
+  const lines = [
+    `Session: ${responseString(response, "sessionId") ?? "(unknown)"}`,
+    `Worker: ${responseString(response, "worker") ?? "(unassigned)"}${previous ? ` (was ${previous})` : ""}`,
+    "The session resumes on this worker; shell runs and sub-agents started earlier stay where they ran."
+  ];
+  return `${lines.join("\n")}
+`;
+}
 async function waitForSessionProvisioning(client, initial, options = {}) {
   const sessionId = requireValue(responseString(initial, "sessionId"), "Session start did not return a session id");
   const wait = options.wait ?? sleep;
@@ -2736,6 +2870,23 @@ async function executeR5dctlCommand(client, json, args) {
     write(result, renderWorkspaceSync(result));
     return;
   }
+  if (first === "workspace" && second === "recover-hydration") {
+    let worker;
+    let transactionId;
+    let confirmed = false;
+    for (let index = 2; index < args.length; index += 1) {
+      const arg = args[index];
+      if (arg === "--worker") worker = requireValue(args[++index], "Missing worker label");
+      else if (arg === "--transaction") transactionId = requireValue(args[++index], "Missing transaction id");
+      else if (arg === "--confirm") confirmed = true;
+      else throw new Error(`Unexpected recovery argument: ${arg}`);
+    }
+    if (!worker || !transactionId || !confirmed)
+      throw new Error("workspace recover-hydration requires --worker, --transaction and --confirm; inspect workspace status first");
+    const result = await client.workspace.recoverHydration({ worker, transactionId, confirmed: true });
+    write(result, renderWorkspaceSync(result));
+    return;
+  }
   if (first === "workspace" && second === "reset") {
     const parsed = parseWorkspaceWorkerArgs(args.slice(2), { allowConfirm: true });
     const result = await client.workspace.reset({ worker: parsed.worker, confirmed: true });
@@ -2766,7 +2917,7 @@ async function executeR5dctlCommand(client, json, args) {
   }
   if (first === "session" && second === "claim") {
     const claim = parseSessionClaimArgs(args.slice(2), {}, {});
-    const scope = claim.sessionId ? { sessionId: claim.sessionId } : {};
+    const scope = { ...claim.sessionId ? { sessionId: claim.sessionId } : {}, ...claim.scope ? { scope: claim.scope } : {} };
     const nowMs = Date.now();
     if (claim.action === "acquire") {
       const result2 = await client.claims.acquire({
@@ -2775,23 +2926,34 @@ async function executeR5dctlCommand(client, json, args) {
         ...claim.ttlSeconds !== void 0 ? { ttlSeconds: claim.ttlSeconds } : {},
         ...claim.note !== void 0 ? { note: claim.note } : {}
       });
+      if (!claimScopeMatches(claim.scope, result2.claim)) {
+        if (result2.outcome === "acquired" && result2.claim.heldByActor) {
+          await client.claims.release({
+            topic: claim.topic,
+            ...claim.sessionId ? { sessionId: claim.sessionId } : {},
+            generation: result2.claim.generation
+          }).catch(() => void 0);
+        }
+        throw new R5dctlClaimScopeMismatchError(claim.scope, result2.claim);
+      }
       write(result2, renderSessionClaimResponse(result2, nowMs));
       if (result2.outcome === "held_by_other") {
-        throw new Error(
-          `Claim ${claim.topic} is held by session ${result2.claim.holderSessionId} until ${result2.claim.expiresAt}; not acquired`
-        );
+        const until = result2.claim.expiresAt === null ? "while it runs (native session)" : `until ${result2.claim.expiresAt}`;
+        throw new Error(`Claim ${claim.topic} is held by session ${result2.claim.holderSessionId} ${until}; not acquired`);
       }
       return;
     }
     if (claim.action === "status") {
       const list = await client.claims.list({ ...scope, topic: claim.topic });
+      assertClaimScopeEcho(claim.scope, list);
       write(list, renderSessionClaimList(list, nowMs));
       return;
     }
     let generation = claim.generation;
-    if (generation === void 0) {
+    if (generation === void 0 || claim.scope) {
       const list = await client.claims.list({ ...scope, topic: claim.topic });
-      const current = list.claims[0];
+      assertClaimScopeEcho(claim.scope, list);
+      const current = list.claims.find((entry) => entry.heldByActor) ?? list.claims[0];
       if (!current) {
         write({ outcome: "missing", actorSessionId: list.actorSessionId, claim: null }, `No claim on ${claim.topic}.
 `);
@@ -2805,7 +2967,7 @@ async function executeR5dctlCommand(client, json, args) {
         );
         throw new Error(`Claim ${claim.topic} is held by session ${current.holderSessionId}, not by ${list.actorSessionId}`);
       }
-      generation = current.generation;
+      generation ??= current.generation;
     }
     const result = claim.action === "renew" ? await client.claims.renew({
       topic: claim.topic,
@@ -2813,16 +2975,25 @@ async function executeR5dctlCommand(client, json, args) {
       generation,
       ...claim.ttlSeconds !== void 0 ? { ttlSeconds: claim.ttlSeconds } : {}
     }) : await client.claims.release({ topic: claim.topic, ...scope, generation });
+    assertClaimScopeEcho(claim.scope, result.claim);
     write(result, renderSessionClaimResponse(result, nowMs));
     const succeeded = result.outcome === "renewed" || result.outcome === "released" || claim.action === "release" && result.outcome === "missing";
     if (!succeeded) throw new Error(`Claim ${claim.topic}: ${CLAIM_OUTCOME_TEXT[result.outcome] ?? result.outcome}`);
     return;
   }
   if (first === "session" && second === "claims") {
-    const list = await client.claims.list(parseSessionClaimsListArgs(args.slice(2), {}, {}));
+    const selection = parseSessionClaimsListArgs(args.slice(2), {}, {});
+    const list = await client.claims.list(selection);
+    assertClaimScopeEcho(selection.scope, list);
     write(list, renderSessionClaimList(list));
     return;
   }
+  if (first === "checkout" && second === "path") {
+    const selection = parseCheckoutPathArgs(args.slice(2), {}, {});
+    const result = await client.checkouts.path(selection);
+    write(result, renderCheckoutPath(result));
+    return;
+  }
   if (first === "session" && second === "process-log") {
     const selection = parseSessionProcessLogArgs(args.slice(2));
     const log = await client.processes.log(selection.runId, {
@@ -2922,7 +3093,8 @@ ${result.deletion ? `Deletion: ${result.deletion.status}${result.deletion.error
       throw new Error(branchDeletionsConfirmationMessage(deletion.branches));
     }
     if (json) write({ results: deletion.results }, "");
-    if (deletion.results.some((result) => !result.deleted && !result.accepted)) throw new Error(branchDeletionsFailureMessage(deletion.results));
+    if (deletion.results.some((result) => !result.deleted && !result.accepted))
+      throw new Error(branchDeletionsFailureMessage(deletion.results));
     return;
   }
   if (first === "projects" && second === "branches" && third === "describe-deletion" || first === "describe" && second === "branch-deletion") {
@@ -3519,24 +3691,43 @@ function resolveCommandExecution(options, rest) {
       ...parseShellArgs(commandArgs)
     };
   }
+  if (command === "checkout") {
+    if (commandArgs[0] !== "path") throw new Error("Unknown checkout command");
+    const parsed = parseCheckoutPathArgs(commandArgs.slice(1), options);
+    return {
+      kind: "plugin",
+      pluginArgs: [
+        "checkout",
+        "path",
+        `--project=${parsed.projectId}`,
+        `--branch=${parsed.branchName}`,
+        ...parsed.sessionId ? [`--session=${parsed.sessionId}`] : []
+      ]
+    };
+  }
   if (command === "session") {
     if (commandArgs[0] === "claim" || commandArgs[0] === "claims") {
-      if (options.project) throw new Error("--project/-p is not supported for `session claim`; the acting session selects the project branch");
-      if (options.branch) throw new Error("--branch/-b is not supported for `session claim`; the acting session selects the branch");
       const parsed = commandArgs[0] === "claim" ? parseSessionClaimArgs(commandArgs.slice(1), options) : parseSessionClaimsListArgs(commandArgs.slice(1), options);
-      const withoutSessionValue = [];
+      const normalizedFlags = /* @__PURE__ */ new Set(["--session", "--project", "--branch"]);
+      const withoutNormalizedValues = [];
       for (let index = 0; index < commandArgs.slice(1).length; index += 1) {
         const arg = commandArgs.slice(1)[index];
-        if (arg === "--session") {
+        if (normalizedFlags.has(arg)) {
           index += 1;
           continue;
         }
-        if (arg.startsWith("--session=")) continue;
-        withoutSessionValue.push(arg);
+        if ([...normalizedFlags].some((flag) => arg.startsWith(`${flag}=`))) continue;
+        withoutNormalizedValues.push(arg);
       }
       return {
         kind: "plugin",
-        pluginArgs: ["session", commandArgs[0], ...withoutSessionValue, ...parsed.sessionId ? [`--session=${parsed.sessionId}`] : []]
+        pluginArgs: [
+          "session",
+          commandArgs[0],
+          ...withoutNormalizedValues,
+          ...parsed.scope ? [`--project=${parsed.scope.projectId}`, `--branch=${parsed.scope.branchName}`] : [],
+          ...parsed.sessionId ? [`--session=${parsed.sessionId}`] : []
+        ]
       };
     }
     if (commandArgs[0] === "process-log") {
@@ -3709,10 +3900,12 @@ async function main(argv = process.argv.slice(2)) {
 export {
   BRANCH_DELETION_POLL_INTERVAL_MS,
   BRANCH_DELETION_WAIT_TIMEOUT_MS,
+  R5dctlClaimScopeMismatchError,
   advanceTransientDevicePollBackoff,
   branchDeletionConfirmationMessage,
   branchDeletionsConfirmationMessage,
   branchDeletionsFailureMessage,
+  claimScopeMatches,
   createBranchThroughPlatform,
   deleteBranchThroughPlatform,
   deleteBranchesThroughPlatform,
@@ -3732,6 +3925,7 @@ export {
   parseAnswerQuestionsCommandArgs,
   parseBranchCreateArgs,
   parseBranchDeleteArgs,
+  parseCheckoutPathArgs,
   parseClaimDuration,
   parseConversationForkArgs,
   parseConversationInspectWorkArgs,
@@ -3757,6 +3951,7 @@ export {
   renderBranchDeletionStatus,
   renderBranchList,
   renderBranchOperation,
+  renderCheckoutPath,
   renderConversationForkResponse,
   renderConversationHeadResponse,
   renderConversationNodeResponse,
@@ -3774,6 +3969,7 @@ export {
   renderSessionList,
   renderSessionRunStart,
   renderSessionRunStatus,
+  renderSessionSetWorker,
   renderWorkerCapacity,
   renderWorkspaceStatus,
   renderWorkspaceSync,

package/dist/mjs/package.json

@@ -1,5 +1,5 @@
 {
   "name": "@ricsam/r5dctl",
-  "version": "0.0.131",
+  "version": "0.0.133",
   "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 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 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 { type AccountCommand } from "./account";
 export type GlobalOptions = {
     baseUrl?: string;
@@ -84,6 +84,10 @@ export type R5dctlSessionRunCommand = R5dctlSessionStartCommand | {
 } | {
     kind: "stop";
     sessionId: string;
+} | {
+    kind: "set-worker";
+    sessionId: string;
+    worker: string;
 };
 export type R5dctlBranchCreateArgs = {
     source: R5dctlWorktreeSource;
@@ -205,23 +209,54 @@ export type R5dctlSessionClaimArgs = {
     topic: string;
     /** The acting session; omitted lets a worker credential act as its own verified session. */
     sessionId?: string;
+    /** A sibling checkout to claim on instead of the acting session's own branch. */
+    scope?: R5dctlSessionClaimScope;
     ttlSeconds?: number;
     note?: string;
     /** Claim generation observed by the caller; renew and release are fenced to it. */
     generation?: number;
 };
+type ClaimScopeOptions = Pick<GlobalOptions, "session" | "project" | "branch">;
 /** `90s`, `30m`, `2h`; the server clamps to between one minute and one day. */
 export declare function parseClaimDuration(value: string): number;
-export declare function parseSessionClaimArgs(args: string[], options?: Pick<GlobalOptions, "session">, env?: Record<string, string | undefined>): R5dctlSessionClaimArgs;
-export declare function parseSessionClaimsListArgs(args: string[], options?: Pick<GlobalOptions, "session">, env?: Record<string, string | undefined>): {
+export declare function parseSessionClaimArgs(args: string[], options?: ClaimScopeOptions, env?: Record<string, string | undefined>): R5dctlSessionClaimArgs;
+export declare function parseSessionClaimsListArgs(args: string[], options?: ClaimScopeOptions, env?: Record<string, string | undefined>): {
+    sessionId?: string;
+    scope?: R5dctlSessionClaimScope;
+};
+export type R5dctlCheckoutPathArgs = {
+    projectId: string;
+    branchName: string;
     sessionId?: string;
 };
+/** `checkout path` names the checkout with -p/--project and --branch/-b (both required) and acts as the selected session. */
+export declare function parseCheckoutPathArgs(args: string[], options?: ClaimScopeOptions, env?: Record<string, string | undefined>): R5dctlCheckoutPathArgs;
+/**
+ * A server that predates claim scopes strips the unknown `scope` field and
+ * answers for the acting session's own branch. Every scoped command must see
+ * its scope echoed back, so a claim can never silently land elsewhere.
+ */
+export declare class R5dctlClaimScopeMismatchError extends Error {
+    constructor(requested: R5dctlSessionClaimScope, answered: {
+        projectId: string;
+        projectPath?: string;
+        branchName: string;
+    });
+}
+export declare function claimScopeMatches(requested: R5dctlSessionClaimScope | undefined, answered: {
+    projectId: string;
+    projectPath?: string;
+    branchName: string;
+} | null | undefined): boolean;
 export declare function renderSessionClaimResponse(response: {
     outcome: string;
     actorSessionId: string;
     claim: R5dctlSessionClaim | null;
+    fenceExtended?: boolean;
+    fenceDetail?: string;
 }, nowMs?: number): string;
 export declare function renderSessionClaimList(response: R5dctlSessionClaimListResponse, nowMs?: number): string;
+export declare function renderCheckoutPath(response: R5dctlCheckoutPathResponse): string;
 export declare function parseGlobalArgs(argv: string[]): {
     options: GlobalOptions;
     rest: string[];
@@ -312,6 +347,10 @@ export type R5dctlCommandResponse = {
     baselineCommit?: string | null;
     workspaceHead?: string | null;
     worker?: string;
+    /** The binding a `session set-worker` replaced; null when the session had none. */
+    previousWorker?: string | null;
+    /** Advisory notices about the run's branch (a foreign `checkout` claim, for example); older servers send none. */
+    warnings?: unknown;
     status?: string;
     runStatus?: unknown;
     /** Worker queue state while a new worktree provisions; older servers and workers omit it. */
@@ -347,6 +386,9 @@ export type R5dctlSessionRunClient = {
             delivery?: R5dctlPromptDelivery;
         }) => Promise<R5dctlCommandResponse>;
         stop: (sessionId: string) => Promise<R5dctlCommandResponse>;
+        setWorker: (sessionId: string, input: {
+            worker: string;
+        }) => Promise<R5dctlCommandResponse>;
     };
 };
 export declare function renderSessionRunStart(session: R5dctlCommandResponse): string;
@@ -356,6 +398,7 @@ export type R5dctlCommandDispatchResult = {
     human: string;
 };
 export declare function dispatchSessionRunCommand(client: R5dctlSessionRunClient, command: R5dctlSessionRunCommand): Promise<R5dctlCommandDispatchResult>;
+export declare function renderSessionSetWorker(response: R5dctlCommandResponse): string;
 export declare function waitForSessionProvisioning(client: Pick<R5dctlSessionRunClient, "sessions">, initial: R5dctlCommandResponse, options?: {
     intervalMs?: number;
     wait?: (milliseconds: number) => Promise<unknown>;

package/package.json

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