@ricsam/r5dctl 0.0.132 → 0.0.134

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,
@@ -178,9 +182,10 @@ const SESSION_RUN_HELP_TEXT = [
   "  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,",
@@ -193,6 +198,11 @@ 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.",
@@ -215,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>]",
@@ -346,13 +361,18 @@ 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: "[-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>] 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 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",
@@ -503,10 +523,14 @@ function renderCliOnlyCommandHelp(entry) {
 `;
 }
 function renderSharedCommandHelp(pathSegments) {
-  const entry = SHARED_HELP_ENTRIES.map((candidate) => ({
-    candidate,
-    usageSegments: candidate.usage.split(" ").map((segment) => segment.replace(/^\[/, "").replace(/\]$/, "")).filter((segment) => !segment.startsWith("-") && !segment.includes("<") && !segment.startsWith("["))
-  })).filter(
+  const entry = SHARED_HELP_ENTRIES.map((candidate) => {
+    const usageSegments = [];
+    for (const segment of candidate.usage.split(/\s+/)) {
+      if (/^[a-z][a-z-]*$/.test(segment)) usageSegments.push(segment);
+      else if (usageSegments.length > 0) break;
+    }
+    return { candidate, usageSegments };
+  }).filter(
     ({ usageSegments }) => usageSegments.length <= pathSegments.length && usageSegments.every((segment, index) => segment === pathSegments[index])
   ).sort((left, right) => right.usageSegments.length - left.usageSegments.length)[0]?.candidate;
   if (!entry) {
@@ -955,13 +979,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) {
@@ -970,7 +1006,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"],
@@ -983,7 +1019,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");
@@ -991,22 +1028,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",
@@ -1019,35 +1086,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}`;
   });
@@ -1055,6 +1142,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"]);
@@ -1896,6 +1988,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)
     ])
@@ -1903,6 +2001,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")}
 `;
 }
@@ -2189,11 +2296,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 = [
@@ -2244,6 +2357,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}`);
@@ -2870,6 +2984,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 });
@@ -2900,7 +3031,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({
@@ -2909,23 +3040,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}.
 `);
@@ -2939,7 +3081,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,
@@ -2947,16 +3089,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, {
@@ -3056,7 +3207,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") {
@@ -3653,24 +3805,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") {
@@ -3844,10 +4015,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,
@@ -3867,6 +4040,7 @@ async function main(argv = process.argv.slice(2)) {
   parseAnswerQuestionsCommandArgs,
   parseBranchCreateArgs,
   parseBranchDeleteArgs,
+  parseCheckoutPathArgs,
   parseClaimDuration,
   parseConversationForkArgs,
   parseConversationInspectWorkArgs,
@@ -3892,6 +4066,7 @@ async function main(argv = process.argv.slice(2)) {
   renderBranchDeletionStatus,
   renderBranchList,
   renderBranchOperation,
+  renderCheckoutPath,
   renderConversationForkResponse,
   renderConversationHeadResponse,
   renderConversationNodeResponse,

package/dist/cjs/package.json

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

package/dist/mjs/cli.mjs

@@ -72,9 +72,10 @@ const SESSION_RUN_HELP_TEXT = [
   "  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,",
@@ -87,6 +88,11 @@ 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.",
@@ -109,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>]",
@@ -240,13 +251,18 @@ 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: "[-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>] 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 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",
@@ -397,10 +413,14 @@ function renderCliOnlyCommandHelp(entry) {
 `;
 }
 function renderSharedCommandHelp(pathSegments) {
-  const entry = SHARED_HELP_ENTRIES.map((candidate) => ({
-    candidate,
-    usageSegments: candidate.usage.split(" ").map((segment) => segment.replace(/^\[/, "").replace(/\]$/, "")).filter((segment) => !segment.startsWith("-") && !segment.includes("<") && !segment.startsWith("["))
-  })).filter(
+  const entry = SHARED_HELP_ENTRIES.map((candidate) => {
+    const usageSegments = [];
+    for (const segment of candidate.usage.split(/\s+/)) {
+      if (/^[a-z][a-z-]*$/.test(segment)) usageSegments.push(segment);
+      else if (usageSegments.length > 0) break;
+    }
+    return { candidate, usageSegments };
+  }).filter(
     ({ usageSegments }) => usageSegments.length <= pathSegments.length && usageSegments.every((segment, index) => segment === pathSegments[index])
   ).sort((left, right) => right.usageSegments.length - left.usageSegments.length)[0]?.candidate;
   if (!entry) {
@@ -849,13 +869,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) {
@@ -864,7 +896,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"],
@@ -877,7 +909,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");
@@ -885,22 +918,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",
@@ -913,35 +976,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}`;
   });
@@ -949,6 +1032,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"]);
@@ -1790,6 +1878,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)
     ])
@@ -1797,6 +1891,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")}
 `;
 }
@@ -2083,11 +2186,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 = [
@@ -2138,6 +2247,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}`);
@@ -2764,6 +2874,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 });
@@ -2794,7 +2921,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({
@@ -2803,23 +2930,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}.
 `);
@@ -2833,7 +2971,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,
@@ -2841,16 +2979,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, {
@@ -2950,7 +3097,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") {
@@ -3547,24 +3695,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") {
@@ -3737,10 +3904,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,
@@ -3760,6 +3929,7 @@ export {
   parseAnswerQuestionsCommandArgs,
   parseBranchCreateArgs,
   parseBranchDeleteArgs,
+  parseCheckoutPathArgs,
   parseClaimDuration,
   parseConversationForkArgs,
   parseConversationInspectWorkArgs,
@@ -3785,6 +3955,7 @@ export {
   renderBranchDeletionStatus,
   renderBranchList,
   renderBranchOperation,
+  renderCheckoutPath,
   renderConversationForkResponse,
   renderConversationHeadResponse,
   renderConversationNodeResponse,

package/dist/mjs/package.json

@@ -1,5 +1,5 @@
 {
   "name": "@ricsam/r5dctl",
-  "version": "0.0.132",
+  "version": "0.0.134",
   "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;
@@ -209,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[];
@@ -318,6 +349,8 @@ export type R5dctlCommandResponse = {
     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. */

package/package.json

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