@ricsam/r5dctl 0.0.117 → 0.0.118

package/dist/cjs/cli.cjs

@@ -54,6 +54,7 @@ __export(cli_exports, {
   parseAnswerQuestionsCommandArgs: () => parseAnswerQuestionsCommandArgs,
   parseBranchCreateArgs: () => parseBranchCreateArgs,
   parseBranchDeleteArgs: () => parseBranchDeleteArgs,
+  parseClaimDuration: () => parseClaimDuration,
   parseConversationForkArgs: () => parseConversationForkArgs,
   parseConversationInspectWorkArgs: () => parseConversationInspectWorkArgs,
   parseConversationOverviewArgs: () => parseConversationOverviewArgs,
@@ -66,6 +67,8 @@ __export(cli_exports, {
   parsePromptArgs: () => parsePromptArgs,
   parsePsHistoryArgs: () => parsePsHistoryArgs,
   parsePsListArgs: () => parsePsListArgs,
+  parseSessionClaimArgs: () => parseSessionClaimArgs,
+  parseSessionClaimsListArgs: () => parseSessionClaimsListArgs,
   parseSessionProcessLogArgs: () => parseSessionProcessLogArgs,
   parseSessionRunCommand: () => parseSessionRunCommand,
   parseSetEnvArgs: () => parseSetEnvArgs,
@@ -89,6 +92,8 @@ __export(cli_exports, {
   renderProcessInspection: () => renderProcessInspection,
   renderProcessList: () => renderProcessList,
   renderProcessLog: () => renderProcessLog,
+  renderSessionClaimList: () => renderSessionClaimList,
+  renderSessionClaimResponse: () => renderSessionClaimResponse,
   renderSessionList: () => renderSessionList,
   renderSessionRunStart: () => renderSessionRunStart,
   renderSessionRunStatus: () => renderSessionRunStatus,
@@ -180,13 +185,22 @@ const SESSION_RUN_HELP_TEXT = [
   '  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 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",
   "",
   "Create, inspect, resume, and stop ordinary agent sessions.",
   "prompt reaches a busy session by --delivery: steer (default) lands after the agent's next tool result,",
   "queue waits for the current turn to finish, force replaces the agent's current tool round. An idle session starts a new generation either way.",
-  "Use --delivery steer for active-session coordination, including merge notices, pause requests, blockers, and handoffs.",
-  "Use force when the current tool round must be interrupted; queue is only for work deliberately deferred until the turn ends.",
-  "Prompt delivery is not acknowledgment. If a shared-checkout change depends on a pause, wait for the recipient's reply before proceeding.",
+  "Send only messages that need action: grants, releases, blockers, corrections, pause/resume, questions, and completion reports;",
+  "batch progress and waiting reports into the update the recipient asked for. Every steer wakes a waiting recipient for a full turn.",
+  "Use force only when the current tool round must be interrupted; queue is only for a follow-up task deliberately deferred until the turn ends.",
+  "The recipient sees the sending session's verified id and name from the credential; --sender only adds a display title",
+  "(defaults to $R5D_SESSION_NAME in an agent shell). Prompt delivery is not acknowledgment: if a shared-checkout change depends",
+  "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.",
+  "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.",
@@ -281,8 +295,8 @@ const SHARED_HELP_ENTRIES = [
   },
   {
     section: "sessions",
-    usage: "conversation overview <session-id> [--skeleton]",
-    description: "Read dialogue and thinking while replacing tool work with inspectable ranges; --skeleton keeps only dialogue, decisions, and per-turn work markers."
+    usage: "conversation overview <session-id> [--skeleton] [--tail <turns>]",
+    description: "Read attributed dialogue and inspectable work ranges; --skeleton keeps bounded commentary and decisions. --tail N shows recent turns in order, capped at 48 KB with explicit omissions; redirect the full overview for earlier history."
   },
   {
     section: "sessions",
@@ -317,13 +331,23 @@ const SHARED_HELP_ENTRIES = [
   {
     section: "sessions",
     usage: 'session prompt --worker <label> --mode <mode> --model <tier> [--delivery queue|steer|force] [--sender <name>] <session-id> "<prompt>"',
-    description: "Prompt a session: steer into the current turn after the next tool result (default), queue behind the turn, or force in place of the current tool round; an idle session starts a new generation. Use steer for active-session coordination; queue only deliberately deferred work. --sender adds an optional title above the message."
+    description: "Prompt a session: steer into the current turn after the next tool result (default), queue a deliberately deferred follow-up behind the turn, or force in place of the current tool round; an idle session starts a new generation. Send only messages that need action; the recipient sees the sender's verified session id, and --sender only adds a display title."
   },
   {
     section: "sessions",
     usage: "session stop <session-id>",
     description: "Stop an active session generation."
   },
+  {
+    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."
+  },
+  {
+    section: "sessions",
+    usage: "[-s <session-id>] session claims",
+    description: "List the claims on the session's project branch with holder, generation, and expiry."
+  },
   {
     section: "sessions",
     usage: "session process-log <run-id> [--tail <n>] [--grep <pattern>]",
@@ -767,7 +791,7 @@ function rejectSessionRunGlobalScopes(options, allowProject) {
   if (options.branch) throw new Error("--branch/-b is not supported for `session`; select the worktree explicitly");
   if (options.session) throw new Error("--session/-s is not supported for `session`; pass the session id explicitly");
 }
-function parseSessionRunCommand(options, args) {
+function parseSessionRunCommand(options, args, env = process.env) {
   const subcommand = requireValue(args[0], "Missing session command");
   const commandArgs = args.slice(1);
   if (subcommand === "start") {
@@ -827,8 +851,9 @@ function parseSessionRunCommand(options, args) {
     const sessionId = requireValue(parsed.positionals[0], "Session id is required for `session prompt`");
     const prompt = parsed.positionals.slice(1).join(" ").trim();
     if (!prompt) throw new Error("Prompt is required for `session prompt`");
-    const sender = parsed.values.get("--sender")?.trim();
-    if (sender !== void 0 && !sender) throw new Error("--sender must not be empty");
+    const explicitSender = parsed.values.get("--sender")?.trim();
+    if (explicitSender !== void 0 && !explicitSender) throw new Error("--sender must not be empty");
+    const sender = explicitSender ?? env.R5D_SESSION_NAME?.trim();
     return {
       kind: "prompt",
       worker: requireWorker(parsed.values),
@@ -852,6 +877,106 @@ function parseSessionProcessLogArgs(args) {
   const grep = parsed.values.get("--grep");
   return { runId, ...tail !== void 0 ? { tail } : {}, ...grep !== void 0 ? { grep } : {} };
 }
+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");
+  return seconds;
+}
+function resolveClaimSessionId(explicit, options, env) {
+  return explicit?.trim() || options.session?.trim() || env.R5D_SESSION_ID?.trim() || void 0;
+}
+function parseSessionClaimArgs(args, options = {}, env = process.env) {
+  const parsed = parseCommandOperands(
+    args,
+    /* @__PURE__ */ new Set(["--ttl", "--note", "--generation", "--session"]),
+    /* @__PURE__ */ new Map([
+      ["--status", "--status"],
+      ["--renew", "--renew"],
+      ["--release", "--release"]
+    ]),
+    "session claim"
+  );
+  const topic = requireValue(parsed.positionals[0]?.trim(), "Topic is required for `session claim`");
+  if (parsed.positionals.length > 1) throw new Error(`Unexpected session claim argument: ${parsed.positionals[1]}`);
+  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");
+  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");
+  if (generationValue !== void 0 && action !== "renew" && action !== "release") {
+    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");
+  const sessionId = resolveClaimSessionId(parsed.values.get("--session"), options, env);
+  return {
+    action,
+    topic,
+    ...sessionId ? { sessionId } : {},
+    ...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");
+  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 CLAIM_OUTCOME_TEXT = {
+  acquired: "acquired",
+  renewed: "renewed",
+  held_by_other: "not acquired: held by another session",
+  not_holder: "not the holder",
+  stale_generation: "stale generation: the claim changed hands since it was observed",
+  expired: "expired: renew failed, claim it again",
+  missing: "no such claim",
+  released: "released"
+};
+function formatClaimExpiry(expiresAt, nowMs) {
+  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 describeClaimHolder(claim) {
+  const name = claim.holderSessionName ? ` ${JSON.stringify(claim.holderSessionName)}` : "";
+  return `${claim.holderSessionId}${name}${claim.heldByActor ? " (this session)" : ""}`;
+}
+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}`,
+      `Holder: ${describeClaimHolder(response.claim)}`,
+      `Generation: ${response.claim.generation}`,
+      `Expires: ${formatClaimExpiry(response.claim.expiresAt, nowMs)}`
+    );
+    if (response.claim.note) lines.push(`Note: ${response.claim.note}`);
+  }
+  return `${lines.join("\n")}
+`;
+}
+function renderSessionClaimList(response, nowMs = Date.now()) {
+  const header = `Claims on ${response.branchName} (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 note = claim.note ? `  note: ${claim.note}` : "";
+    return `- ${claim.topic}  holder ${describeClaimHolder(claim)}  generation ${claim.generation}  ${expiry} ${formatClaimExpiry(claim.expiresAt, nowMs)}${note}`;
+  });
+  return `${header}:
+${rows.join("\n")}
+`;
+}
 function assertAuthLoginArgs(args) {
   const valueFlags = /* @__PURE__ */ new Set(["--device-name", "--worker-label"]);
   const booleanFlags = /* @__PURE__ */ new Set(["--no-open", "--no-qr"]);
@@ -2694,16 +2819,26 @@ function parseConversationInspectWorkArgs(args) {
 }
 function parseConversationOverviewArgs(args) {
   let skeleton = false;
-  for (const arg of args) {
-    if (arg !== "--skeleton") {
-      throw new Error(`Unknown conversation overview argument: ${arg}`);
+  let tail;
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+    if (arg === "--tail") {
+      if (tail !== void 0) throw new Error("Use --tail only once");
+      const value = requireValue(args[++index], "Missing value for --tail");
+      if (!/^[1-9][0-9]*$/.test(value) || !Number.isSafeInteger(Number(value)) || Number(value) > 200) {
+        throw new Error("Invalid --tail value: use a whole number from 1 to 200");
+      }
+      tail = Number(value);
+      continue;
     }
-    if (skeleton) {
-      throw new Error("Use --skeleton only once");
+    if (arg === "--skeleton") {
+      if (skeleton) throw new Error("Use --skeleton only once");
+      skeleton = true;
+      continue;
     }
-    skeleton = true;
+    throw new Error(`Unknown conversation overview argument: ${arg}`);
   }
-  return { skeleton };
+  return { skeleton, ...tail !== void 0 ? { tail } : {} };
 }
 function parseConversationForkArgs(args) {
   let name;
@@ -2858,6 +2993,55 @@ async function executeR5dctlCommand(client, json, args) {
 `);
     return;
   }
+  if (first === "session" && second === "claim") {
+    const claim = parseSessionClaimArgs(args.slice(2), {}, {});
+    const scope = claim.sessionId ? { sessionId: claim.sessionId } : {};
+    const nowMs = Date.now();
+    if (claim.action === "acquire") {
+      const result2 = await client.claims.acquire({
+        topic: claim.topic,
+        ...scope,
+        ...claim.ttlSeconds !== void 0 ? { ttlSeconds: claim.ttlSeconds } : {},
+        ...claim.note !== void 0 ? { note: claim.note } : {}
+      });
+      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`);
+      }
+      return;
+    }
+    if (claim.action === "status") {
+      const list = await client.claims.list({ ...scope, topic: claim.topic });
+      write(list, renderSessionClaimList(list, nowMs));
+      return;
+    }
+    let generation = claim.generation;
+    if (generation === void 0) {
+      const list = await client.claims.list({ ...scope, topic: claim.topic });
+      const current = list.claims[0];
+      if (!current) {
+        write({ outcome: "missing", actorSessionId: list.actorSessionId, claim: null }, `No claim on ${claim.topic}.
+`);
+        if (claim.action === "renew") throw new Error(`No claim on ${claim.topic} to renew`);
+        return;
+      }
+      if (!current.heldByActor) {
+        write({ outcome: "not_holder", actorSessionId: list.actorSessionId, claim: current }, renderSessionClaimResponse({ outcome: "not_holder", actorSessionId: list.actorSessionId, claim: current }, nowMs));
+        throw new Error(`Claim ${claim.topic} is held by session ${current.holderSessionId}, not by ${list.actorSessionId}`);
+      }
+      generation = current.generation;
+    }
+    const result = claim.action === "renew" ? await client.claims.renew({ topic: claim.topic, ...scope, generation, ...claim.ttlSeconds !== void 0 ? { ttlSeconds: claim.ttlSeconds } : {} }) : await client.claims.release({ topic: claim.topic, ...scope, generation });
+    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), {}, {}));
+    write(list, renderSessionClaimList(list));
+    return;
+  }
   if (first === "session" && second === "process-log") {
     const selection = parseSessionProcessLogArgs(args.slice(2));
     const log = await client.processes.log(selection.runId, {
@@ -3015,8 +3199,11 @@ Sessions: ${result.sessions.length}
   }
   if (first === "conversation" && second === "overview") {
     const sessionId = requireValue(args[2], "Missing session id");
-    const { skeleton } = parseConversationOverviewArgs(args.slice(3));
-    const read = await client.sessions.conversationOverview(sessionId, skeleton ? { view: "skeleton" } : {});
+    const { skeleton, tail } = parseConversationOverviewArgs(args.slice(3));
+    const read = await client.sessions.conversationOverview(sessionId, {
+      ...skeleton ? { view: "skeleton" } : {},
+      ...tail !== void 0 ? { tail } : {}
+    });
     write(read, renderConversationOverviewResponse(read));
     return;
   }
@@ -3557,6 +3744,25 @@ function resolveCommandExecution(options, rest) {
     };
   }
   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 = [];
+      for (let index = 0; index < commandArgs.slice(1).length; index += 1) {
+        const arg = commandArgs.slice(1)[index];
+        if (arg === "--session") {
+          index += 1;
+          continue;
+        }
+        if (arg.startsWith("--session=")) continue;
+        withoutSessionValue.push(arg);
+      }
+      return {
+        kind: "plugin",
+        pluginArgs: ["session", commandArgs[0], ...withoutSessionValue, ...parsed.sessionId ? [`--session=${parsed.sessionId}`] : []]
+      };
+    }
     if (commandArgs[0] === "process-log") {
       rejectSessionRunGlobalScopes(options, false);
       const selection = parseSessionProcessLogArgs(commandArgs.slice(1));
@@ -3748,6 +3954,7 @@ async function main(argv = process.argv.slice(2)) {
   parseAnswerQuestionsCommandArgs,
   parseBranchCreateArgs,
   parseBranchDeleteArgs,
+  parseClaimDuration,
   parseConversationForkArgs,
   parseConversationInspectWorkArgs,
   parseConversationOverviewArgs,
@@ -3760,6 +3967,8 @@ async function main(argv = process.argv.slice(2)) {
   parsePromptArgs,
   parsePsHistoryArgs,
   parsePsListArgs,
+  parseSessionClaimArgs,
+  parseSessionClaimsListArgs,
   parseSessionProcessLogArgs,
   parseSessionRunCommand,
   parseSetEnvArgs,
@@ -3783,6 +3992,8 @@ async function main(argv = process.argv.slice(2)) {
   renderProcessInspection,
   renderProcessList,
   renderProcessLog,
+  renderSessionClaimList,
+  renderSessionClaimResponse,
   renderSessionList,
   renderSessionRunStart,
   renderSessionRunStatus,

package/dist/cjs/package.json

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

package/dist/mjs/cli.mjs

@@ -80,13 +80,22 @@ const SESSION_RUN_HELP_TEXT = [
   '  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 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",
   "",
   "Create, inspect, resume, and stop ordinary agent sessions.",
   "prompt reaches a busy session by --delivery: steer (default) lands after the agent's next tool result,",
   "queue waits for the current turn to finish, force replaces the agent's current tool round. An idle session starts a new generation either way.",
-  "Use --delivery steer for active-session coordination, including merge notices, pause requests, blockers, and handoffs.",
-  "Use force when the current tool round must be interrupted; queue is only for work deliberately deferred until the turn ends.",
-  "Prompt delivery is not acknowledgment. If a shared-checkout change depends on a pause, wait for the recipient's reply before proceeding.",
+  "Send only messages that need action: grants, releases, blockers, corrections, pause/resume, questions, and completion reports;",
+  "batch progress and waiting reports into the update the recipient asked for. Every steer wakes a waiting recipient for a full turn.",
+  "Use force only when the current tool round must be interrupted; queue is only for a follow-up task deliberately deferred until the turn ends.",
+  "The recipient sees the sending session's verified id and name from the credential; --sender only adds a display title",
+  "(defaults to $R5D_SESSION_NAME in an agent shell). Prompt delivery is not acknowledgment: if a shared-checkout change depends",
+  "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.",
+  "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.",
@@ -181,8 +190,8 @@ const SHARED_HELP_ENTRIES = [
   },
   {
     section: "sessions",
-    usage: "conversation overview <session-id> [--skeleton]",
-    description: "Read dialogue and thinking while replacing tool work with inspectable ranges; --skeleton keeps only dialogue, decisions, and per-turn work markers."
+    usage: "conversation overview <session-id> [--skeleton] [--tail <turns>]",
+    description: "Read attributed dialogue and inspectable work ranges; --skeleton keeps bounded commentary and decisions. --tail N shows recent turns in order, capped at 48 KB with explicit omissions; redirect the full overview for earlier history."
   },
   {
     section: "sessions",
@@ -217,13 +226,23 @@ const SHARED_HELP_ENTRIES = [
   {
     section: "sessions",
     usage: 'session prompt --worker <label> --mode <mode> --model <tier> [--delivery queue|steer|force] [--sender <name>] <session-id> "<prompt>"',
-    description: "Prompt a session: steer into the current turn after the next tool result (default), queue behind the turn, or force in place of the current tool round; an idle session starts a new generation. Use steer for active-session coordination; queue only deliberately deferred work. --sender adds an optional title above the message."
+    description: "Prompt a session: steer into the current turn after the next tool result (default), queue a deliberately deferred follow-up behind the turn, or force in place of the current tool round; an idle session starts a new generation. Send only messages that need action; the recipient sees the sender's verified session id, and --sender only adds a display title."
   },
   {
     section: "sessions",
     usage: "session stop <session-id>",
     description: "Stop an active session generation."
   },
+  {
+    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."
+  },
+  {
+    section: "sessions",
+    usage: "[-s <session-id>] session claims",
+    description: "List the claims on the session's project branch with holder, generation, and expiry."
+  },
   {
     section: "sessions",
     usage: "session process-log <run-id> [--tail <n>] [--grep <pattern>]",
@@ -667,7 +686,7 @@ function rejectSessionRunGlobalScopes(options, allowProject) {
   if (options.branch) throw new Error("--branch/-b is not supported for `session`; select the worktree explicitly");
   if (options.session) throw new Error("--session/-s is not supported for `session`; pass the session id explicitly");
 }
-function parseSessionRunCommand(options, args) {
+function parseSessionRunCommand(options, args, env = process.env) {
   const subcommand = requireValue(args[0], "Missing session command");
   const commandArgs = args.slice(1);
   if (subcommand === "start") {
@@ -727,8 +746,9 @@ function parseSessionRunCommand(options, args) {
     const sessionId = requireValue(parsed.positionals[0], "Session id is required for `session prompt`");
     const prompt = parsed.positionals.slice(1).join(" ").trim();
     if (!prompt) throw new Error("Prompt is required for `session prompt`");
-    const sender = parsed.values.get("--sender")?.trim();
-    if (sender !== void 0 && !sender) throw new Error("--sender must not be empty");
+    const explicitSender = parsed.values.get("--sender")?.trim();
+    if (explicitSender !== void 0 && !explicitSender) throw new Error("--sender must not be empty");
+    const sender = explicitSender ?? env.R5D_SESSION_NAME?.trim();
     return {
       kind: "prompt",
       worker: requireWorker(parsed.values),
@@ -752,6 +772,106 @@ function parseSessionProcessLogArgs(args) {
   const grep = parsed.values.get("--grep");
   return { runId, ...tail !== void 0 ? { tail } : {}, ...grep !== void 0 ? { grep } : {} };
 }
+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");
+  return seconds;
+}
+function resolveClaimSessionId(explicit, options, env) {
+  return explicit?.trim() || options.session?.trim() || env.R5D_SESSION_ID?.trim() || void 0;
+}
+function parseSessionClaimArgs(args, options = {}, env = process.env) {
+  const parsed = parseCommandOperands(
+    args,
+    /* @__PURE__ */ new Set(["--ttl", "--note", "--generation", "--session"]),
+    /* @__PURE__ */ new Map([
+      ["--status", "--status"],
+      ["--renew", "--renew"],
+      ["--release", "--release"]
+    ]),
+    "session claim"
+  );
+  const topic = requireValue(parsed.positionals[0]?.trim(), "Topic is required for `session claim`");
+  if (parsed.positionals.length > 1) throw new Error(`Unexpected session claim argument: ${parsed.positionals[1]}`);
+  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");
+  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");
+  if (generationValue !== void 0 && action !== "renew" && action !== "release") {
+    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");
+  const sessionId = resolveClaimSessionId(parsed.values.get("--session"), options, env);
+  return {
+    action,
+    topic,
+    ...sessionId ? { sessionId } : {},
+    ...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");
+  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 CLAIM_OUTCOME_TEXT = {
+  acquired: "acquired",
+  renewed: "renewed",
+  held_by_other: "not acquired: held by another session",
+  not_holder: "not the holder",
+  stale_generation: "stale generation: the claim changed hands since it was observed",
+  expired: "expired: renew failed, claim it again",
+  missing: "no such claim",
+  released: "released"
+};
+function formatClaimExpiry(expiresAt, nowMs) {
+  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 describeClaimHolder(claim) {
+  const name = claim.holderSessionName ? ` ${JSON.stringify(claim.holderSessionName)}` : "";
+  return `${claim.holderSessionId}${name}${claim.heldByActor ? " (this session)" : ""}`;
+}
+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}`,
+      `Holder: ${describeClaimHolder(response.claim)}`,
+      `Generation: ${response.claim.generation}`,
+      `Expires: ${formatClaimExpiry(response.claim.expiresAt, nowMs)}`
+    );
+    if (response.claim.note) lines.push(`Note: ${response.claim.note}`);
+  }
+  return `${lines.join("\n")}
+`;
+}
+function renderSessionClaimList(response, nowMs = Date.now()) {
+  const header = `Claims on ${response.branchName} (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 note = claim.note ? `  note: ${claim.note}` : "";
+    return `- ${claim.topic}  holder ${describeClaimHolder(claim)}  generation ${claim.generation}  ${expiry} ${formatClaimExpiry(claim.expiresAt, nowMs)}${note}`;
+  });
+  return `${header}:
+${rows.join("\n")}
+`;
+}
 function assertAuthLoginArgs(args) {
   const valueFlags = /* @__PURE__ */ new Set(["--device-name", "--worker-label"]);
   const booleanFlags = /* @__PURE__ */ new Set(["--no-open", "--no-qr"]);
@@ -2594,16 +2714,26 @@ function parseConversationInspectWorkArgs(args) {
 }
 function parseConversationOverviewArgs(args) {
   let skeleton = false;
-  for (const arg of args) {
-    if (arg !== "--skeleton") {
-      throw new Error(`Unknown conversation overview argument: ${arg}`);
+  let tail;
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+    if (arg === "--tail") {
+      if (tail !== void 0) throw new Error("Use --tail only once");
+      const value = requireValue(args[++index], "Missing value for --tail");
+      if (!/^[1-9][0-9]*$/.test(value) || !Number.isSafeInteger(Number(value)) || Number(value) > 200) {
+        throw new Error("Invalid --tail value: use a whole number from 1 to 200");
+      }
+      tail = Number(value);
+      continue;
     }
-    if (skeleton) {
-      throw new Error("Use --skeleton only once");
+    if (arg === "--skeleton") {
+      if (skeleton) throw new Error("Use --skeleton only once");
+      skeleton = true;
+      continue;
     }
-    skeleton = true;
+    throw new Error(`Unknown conversation overview argument: ${arg}`);
   }
-  return { skeleton };
+  return { skeleton, ...tail !== void 0 ? { tail } : {} };
 }
 function parseConversationForkArgs(args) {
   let name;
@@ -2758,6 +2888,55 @@ async function executeR5dctlCommand(client, json, args) {
 `);
     return;
   }
+  if (first === "session" && second === "claim") {
+    const claim = parseSessionClaimArgs(args.slice(2), {}, {});
+    const scope = claim.sessionId ? { sessionId: claim.sessionId } : {};
+    const nowMs = Date.now();
+    if (claim.action === "acquire") {
+      const result2 = await client.claims.acquire({
+        topic: claim.topic,
+        ...scope,
+        ...claim.ttlSeconds !== void 0 ? { ttlSeconds: claim.ttlSeconds } : {},
+        ...claim.note !== void 0 ? { note: claim.note } : {}
+      });
+      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`);
+      }
+      return;
+    }
+    if (claim.action === "status") {
+      const list = await client.claims.list({ ...scope, topic: claim.topic });
+      write(list, renderSessionClaimList(list, nowMs));
+      return;
+    }
+    let generation = claim.generation;
+    if (generation === void 0) {
+      const list = await client.claims.list({ ...scope, topic: claim.topic });
+      const current = list.claims[0];
+      if (!current) {
+        write({ outcome: "missing", actorSessionId: list.actorSessionId, claim: null }, `No claim on ${claim.topic}.
+`);
+        if (claim.action === "renew") throw new Error(`No claim on ${claim.topic} to renew`);
+        return;
+      }
+      if (!current.heldByActor) {
+        write({ outcome: "not_holder", actorSessionId: list.actorSessionId, claim: current }, renderSessionClaimResponse({ outcome: "not_holder", actorSessionId: list.actorSessionId, claim: current }, nowMs));
+        throw new Error(`Claim ${claim.topic} is held by session ${current.holderSessionId}, not by ${list.actorSessionId}`);
+      }
+      generation = current.generation;
+    }
+    const result = claim.action === "renew" ? await client.claims.renew({ topic: claim.topic, ...scope, generation, ...claim.ttlSeconds !== void 0 ? { ttlSeconds: claim.ttlSeconds } : {} }) : await client.claims.release({ topic: claim.topic, ...scope, generation });
+    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), {}, {}));
+    write(list, renderSessionClaimList(list));
+    return;
+  }
   if (first === "session" && second === "process-log") {
     const selection = parseSessionProcessLogArgs(args.slice(2));
     const log = await client.processes.log(selection.runId, {
@@ -2915,8 +3094,11 @@ Sessions: ${result.sessions.length}
   }
   if (first === "conversation" && second === "overview") {
     const sessionId = requireValue(args[2], "Missing session id");
-    const { skeleton } = parseConversationOverviewArgs(args.slice(3));
-    const read = await client.sessions.conversationOverview(sessionId, skeleton ? { view: "skeleton" } : {});
+    const { skeleton, tail } = parseConversationOverviewArgs(args.slice(3));
+    const read = await client.sessions.conversationOverview(sessionId, {
+      ...skeleton ? { view: "skeleton" } : {},
+      ...tail !== void 0 ? { tail } : {}
+    });
     write(read, renderConversationOverviewResponse(read));
     return;
   }
@@ -3457,6 +3639,25 @@ function resolveCommandExecution(options, rest) {
     };
   }
   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 = [];
+      for (let index = 0; index < commandArgs.slice(1).length; index += 1) {
+        const arg = commandArgs.slice(1)[index];
+        if (arg === "--session") {
+          index += 1;
+          continue;
+        }
+        if (arg.startsWith("--session=")) continue;
+        withoutSessionValue.push(arg);
+      }
+      return {
+        kind: "plugin",
+        pluginArgs: ["session", commandArgs[0], ...withoutSessionValue, ...parsed.sessionId ? [`--session=${parsed.sessionId}`] : []]
+      };
+    }
     if (commandArgs[0] === "process-log") {
       rejectSessionRunGlobalScopes(options, false);
       const selection = parseSessionProcessLogArgs(commandArgs.slice(1));
@@ -3647,6 +3848,7 @@ export {
   parseAnswerQuestionsCommandArgs,
   parseBranchCreateArgs,
   parseBranchDeleteArgs,
+  parseClaimDuration,
   parseConversationForkArgs,
   parseConversationInspectWorkArgs,
   parseConversationOverviewArgs,
@@ -3659,6 +3861,8 @@ export {
   parsePromptArgs,
   parsePsHistoryArgs,
   parsePsListArgs,
+  parseSessionClaimArgs,
+  parseSessionClaimsListArgs,
   parseSessionProcessLogArgs,
   parseSessionRunCommand,
   parseSetEnvArgs,
@@ -3682,6 +3886,8 @@ export {
   renderProcessInspection,
   renderProcessList,
   renderProcessLog,
+  renderSessionClaimList,
+  renderSessionClaimResponse,
   renderSessionList,
   renderSessionRunStart,
   renderSessionRunStatus,

package/dist/mjs/package.json

@@ -1,5 +1,5 @@
 {
   "name": "@ricsam/r5dctl",
-  "version": "0.0.117",
+  "version": "0.0.118",
   "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 R5dctlK8sResourceHistory, type R5dctlK8sUsage, type R5dctlK8sWorkload, type R5dctlProcessInspection, type R5dctlProcessListInput, type R5dctlProcessLog, type R5dctlProcessRun, type R5dctlBranch, type R5dctlBranchDeleteResponse, type R5dctlBranchDescription, type R5dctlBranchOperation, type R5dctlSessionSummary, 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 R5dctlK8sResourceHistory, type R5dctlK8sUsage, type R5dctlK8sWorkload, type R5dctlProcessInspection, type R5dctlProcessListInput, type R5dctlProcessLog, type R5dctlProcessRun, type R5dctlBranch, type R5dctlBranchDeleteResponse, 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";
 export type GlobalOptions = {
     baseUrl?: string;
     json: boolean;
@@ -140,13 +140,36 @@ export declare function branchDeletionConfirmationMessage(branch: R5dctlBranchDe
 export declare function renderBranchDeletion(result: R5dctlBranchDeleteResponse): string;
 /** Operation facts only: no commit hash, because a hash is stale as soon as the branch commits. */
 export declare function renderBranchOperation(operation: R5dctlBranchOperation, projectRef: string): string;
-export declare function parseSessionRunCommand(options: Pick<GlobalOptions, "project" | "branch" | "session">, args: string[]): R5dctlSessionRunCommand;
+export declare function parseSessionRunCommand(options: Pick<GlobalOptions, "project" | "branch" | "session">, args: string[], env?: Record<string, string | undefined>): R5dctlSessionRunCommand;
 export type R5dctlSessionProcessLogArgs = {
     runId: string;
     tail?: number;
     grep?: string;
 };
 export declare function parseSessionProcessLogArgs(args: string[]): R5dctlSessionProcessLogArgs;
+export type R5dctlSessionClaimAction = "acquire" | "status" | "renew" | "release";
+export type R5dctlSessionClaimArgs = {
+    action: R5dctlSessionClaimAction;
+    topic: string;
+    /** The acting session; omitted lets a worker credential act as its own verified session. */
+    sessionId?: string;
+    ttlSeconds?: number;
+    note?: string;
+    /** Claim generation observed by the caller; renew and release are fenced to it. */
+    generation?: number;
+};
+/** `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>): {
+    sessionId?: string;
+};
+export declare function renderSessionClaimResponse(response: {
+    outcome: string;
+    actorSessionId: string;
+    claim: R5dctlSessionClaim | null;
+}, nowMs?: number): string;
+export declare function renderSessionClaimList(response: R5dctlSessionClaimListResponse, nowMs?: number): string;
 export declare function parseGlobalArgs(argv: string[]): {
     options: GlobalOptions;
     rest: string[];
@@ -355,6 +378,7 @@ export type ConversationInspectWorkOptions = {
 export declare function parseConversationInspectWorkArgs(args: string[]): ConversationInspectWorkOptions;
 export declare function parseConversationOverviewArgs(args: string[]): {
     skeleton: boolean;
+    tail?: number;
 };
 export declare function parseConversationForkArgs(args: string[]): string | undefined;
 export declare function renderConversationOverviewResponse(read: R5dctlConversationOverviewResponse): string;

package/package.json

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