@rallycry/conveyor-agent 11.0.42 → 11.0.44

package/dist/{chunk-7RC5YJDF.js → chunk-42YPRICN.js}

@@ -82,6 +82,7 @@ import {
   isCapabilityServableMime,
   isCodexReasoningEffort,
   isPlaceholderLocator,
+  loadAndAnnotateDiscoveredPorts,
   locatorMatchesContent,
   parseMentions,
   pushToOrigin,
@@ -97,7 +98,7 @@ import {
   statWorkspacePath,
   updateRemoteToken,
   verifyGitCredential
-} from "./chunk-CG7AHC25.js";
+} from "./chunk-KMBMW3J3.js";
 import {
   registerBootMilestoneSocketFallback,
   reportBootMilestone
@@ -9088,9 +9089,14 @@ var gcpFields = {
   limit: LIMIT,
   pageToken: f.optional(
     f.string({ desc: "Opaque token from a previous response to fetch the next page" })
+  ),
+  full: f.optional(
+    f.boolean({
+      desc: 'Render each entry in full: message and structured payload untruncated, multi-line. Pair with a narrow search or filter (e.g. insertId="\u2026"); full mode returns at most 10 entries.'
+    })
   )
 };
-var GCP_SHARED_DESC = "Envs: 'prod' and 'dev' are the project's Cloud Run apps + Cloud SQL databases (scoped by default to the resources linked in project settings); 'claudespace' is the project's GKE agent-pod namespace. Start broad (severity=ERROR, sinceMinutes=60), then narrow with services/search. Returns compact lines: '<time> <SEVERITY> [<source>] <message> | key=value \u2026' (the key=value tail is the entry's structured payload \u2014 error details, service/method, actor and entity ids). When the response ends with a pageToken line, pass that token back as pageToken for the next page.";
+var GCP_SHARED_DESC = "Envs: 'prod' and 'dev' are the project's Cloud Run apps + Cloud SQL databases (scoped by default to the resources linked in project settings); 'claudespace' is the project's GKE agent-pod namespace. Start broad (severity=ERROR, sinceMinutes=60), then narrow with services/search. Returns compact lines: '<time> <SEVERITY> [<source>] <message> | key=value \u2026' (the key=value tail is the entry's structured payload \u2014 error details, service/method, actor and entity ids). When the response ends with a pageToken line, pass that token back as pageToken for the next page. To read a whole entry (long message, full payload), re-query narrowly with full=true.";
 var queryGcpLogsContract = defineToolContract({
   name: "query_gcp_logs",
   agent: {
@@ -12362,6 +12368,7 @@ function handleRateLimitEvent(event, host) {
   const resetsAt = epochSecondsToISO(rate_limit_info.resetsAt);
   const utilization = rate_limit_info.utilization ?? (status === "rejected" ? 1 : void 0);
   if (utilization !== void 0 && rate_limit_info.rateLimitType) {
+    const codingAgentKeyId = process.env.CONVEYOR_CODING_AGENT_KEY_ID;
     host.connection.sendEvent({
       type: "rate_limit_update",
       rateLimitType: rate_limit_info.rateLimitType,
@@ -12370,7 +12377,8 @@ function handleRateLimitEvent(event, host) {
       // The server parses this into the key's sessionResetsAt / weeklyResetsAt;
       // Codex reports a reset instant with every gauge, so allowed events carry
       // it too, not only rejections.
-      ...resetsAt ? { resetsAt } : {}
+      ...resetsAt ? { resetsAt } : {},
+      ...codingAgentKeyId ? { codingAgentKeyId } : {}
     });
   }
   if (status === "rejected") {
@@ -15062,6 +15070,7 @@ var SessionRunner = class _SessionRunner {
     const portVisibility = new CodespacePortVisibility();
     this.portDiscovery = deps.portDiscovery ?? new PortDiscovery({
       report: (ports) => this.connection.reportDiscoveredPorts(ports),
+      annotate: (ports) => loadAndAnnotateDiscoveredPorts(config.workspaceDir, ports),
       onReported: (ports) => portVisibility.ensureVisible(ports.map(({ port }) => port))
     });
     const initialMode = config.agentMode ?? (config.runnerMode === "pm" ? config.isAuto ? "auto" : "discovery" : "building");

package/dist/{chunk-G2CE3NFY.js → chunk-4H75HQVM.js}

@@ -8,7 +8,7 @@ import {
   readWorkspaceBytes,
   statWorkspacePath,
   workspacePathExists
-} from "./chunk-CG7AHC25.js";
+} from "./chunk-KMBMW3J3.js";
 import {
   reportBootMilestone
 } from "./chunk-Q4FQOJ7D.js";

package/dist/{chunk-CG7AHC25.js → chunk-KMBMW3J3.js}

@@ -1267,12 +1267,20 @@ var AgentConnection = class _AgentConnection {
    * limited and hand back the best remaining key's credential env (or a
    * requeue confirmation when none is left). Awaited: the caller swaps
    * credentials and resumes on success, so it needs the real response.
+   *
+   * Names the key this pod is running so the server stamps THAT key: the
+   * session's own attribution can lag the credential a wake handed out, and
+   * stamping it blindly is how one key's cap landed on another. Read from the
+   * env at call time on purpose — `applyCycledKeyEnv` rewrites the var after a
+   * successful cycle, so a second cap names the replacement.
    */
   async cycleCodingAgentKey(rateLimitType, resetsAt) {
+    const codingAgentKeyId = process.env.CONVEYOR_CODING_AGENT_KEY_ID;
     return await this.call("cycleCodingAgentKey", {
       sessionId: this.config.sessionId,
       rateLimitType,
-      ...resetsAt ? { resetsAt } : {}
+      ...resetsAt ? { resetsAt } : {},
+      ...codingAgentKeyId ? { codingAgentKeyId } : {}
     });
   }
   // ── Question handling ──────────────────────────────────────────────
@@ -1530,7 +1538,7 @@ ${q.question}${q.options.length ? "\n" + q.options.map((o) => `- ${o.label}: ${o
   }
 };
 
-// ../shared/dist/chunk-BH4SLNGU.js
+// ../shared/dist/chunk-VSUBG7GR.js
 import { z } from "zod";
 import { z as z2 } from "zod";
 var DEFAULT_SONNET_MODEL = "claude-sonnet-5-5";
@@ -1684,6 +1692,7 @@ var SEVERITY_ENUM = [
 ];
 var MAX_LINE_CHARS = 400;
 var DEFAULT_SINCE_MINUTES = 60;
+var FULL_MODE_MAX_ENTRIES = 10;
 function truncateLine(text) {
   const oneLine = text.replace(/\s*\n\s*/g, " \u23CE ");
   if (oneLine.length <= MAX_LINE_CHARS) return oneLine;
@@ -1719,7 +1728,8 @@ function formatPayloadSuffix(payloadJson) {
   try {
     parsed = JSON.parse(payloadJson);
   } catch {
-    return "";
+    const flat = payloadJson.replace(/\s+/g, " ");
+    return ` | payload=${flat.slice(0, PAYLOAD_VALUE_MAX_CHARS)}\u2026[truncated, use full]`;
   }
   if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return "";
   const obj = parsed;
@@ -1730,14 +1740,50 @@ function formatPayloadSuffix(payloadJson) {
   const parts = Object.keys(obj).filter((k) => !PAYLOAD_SKIP_KEYS.has(k) && obj[k] !== void 0 && obj[k] !== null).sort((a, b) => rank(a) - rank(b) || a.localeCompare(b)).map((k) => `${k}=${compactPayloadValue(obj[k])}`);
   return parts.length > 0 ? ` | ${parts.join(" ")}` : "";
 }
+function httpPrefixOf(entry) {
+  return entry.httpRequest?.status ? `http ${entry.httpRequest.status} ${entry.httpRequest.method ?? ""} ${entry.httpRequest.url ?? ""}`.trim() + " \u2014 " : "";
+}
 function formatLogEntryLine(entry) {
-  const httpPrefix = entry.httpRequest?.status ? `http ${entry.httpRequest.status} ${entry.httpRequest.method ?? ""} ${entry.httpRequest.url ?? ""}`.trim() + " \u2014 " : "";
+  const httpPrefix = httpPrefixOf(entry);
   return `${entry.timestamp} ${entry.severity.padEnd(7)} [${entrySource(entry)}] ${truncateLine(
     `${httpPrefix}${entry.message}${formatPayloadSuffix(entry.payload)}`
   )}`;
 }
+function formatPayloadFull(payloadJson) {
+  let parsed;
+  try {
+    parsed = JSON.parse(payloadJson);
+  } catch {
+    return payloadJson;
+  }
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+    return JSON.stringify(parsed, null, 2);
+  }
+  const obj = Object.fromEntries(
+    Object.entries(parsed).filter(([k]) => !PAYLOAD_SKIP_KEYS.has(k))
+  );
+  return Object.keys(obj).length > 0 ? JSON.stringify(obj, null, 2) : "";
+}
+function formatLogEntryFull(entry) {
+  const head = `${entry.timestamp} ${entry.severity} [${entrySource(entry)}]${entry.insertId ? ` insertId=${entry.insertId}` : ""}`;
+  const payload = entry.payload ? formatPayloadFull(entry.payload) : "";
+  return [
+    head,
+    `${httpPrefixOf(entry)}${entry.message}`,
+    ...payload ? [payload] : [],
+    ...entry.payloadTruncated ? ["\u2026[payload truncated server-side]"] : []
+  ].join("\n");
+}
+function fullModeLimit(limit) {
+  return Math.min(limit ?? FULL_MODE_MAX_ENTRIES, FULL_MODE_MAX_ENTRIES);
+}
+function formatFullEntries(entries) {
+  return entries.map((entry, i) => (i === 0 ? "" : "\n") + formatLogEntryFull(entry));
+}
 async function runQueryGcpLogs(port, params, now = Date.now) {
   const startTime = params.startTime ?? new Date(now() - (params.sinceMinutes ?? DEFAULT_SINCE_MINUTES) * 6e4).toISOString();
+  const full = params.full === true;
+  const limit = full ? fullModeLimit(params.limit) : params.limit;
   const result = await port.queryGcpLogs({
     projectId: params.projectId,
     env: params.env,
@@ -1749,8 +1795,9 @@ async function runQueryGcpLogs(port, params, now = Date.now) {
     filter: params.filter,
     startTime,
     endTime: params.endTime,
-    limit: params.limit,
-    pageToken: params.pageToken
+    limit,
+    pageToken: params.pageToken,
+    ...full ? { full: true } : {}
   });
   if (result.error) return result.error;
   const header = [
@@ -1758,9 +1805,10 @@ async function runQueryGcpLogs(port, params, now = Date.now) {
     `window=${startTime}\u2192${params.endTime ?? "now"}`,
     ...params.severity ? [`minSeverity=${params.severity}`] : [],
     `scope=${result.scopedServices ? `[${result.scopedServices.join(", ")}]` : "all"}`,
-    `entries=${result.entries.length}`
+    `entries=${result.entries.length}`,
+    ...full ? ["full=true"] : []
   ].join(" ");
-  const lines = result.entries.map(formatLogEntryLine);
+  const lines = full ? formatFullEntries(result.entries) : result.entries.map(formatLogEntryLine);
   const footer = result.nextPageToken ? [`-- more available: pass pageToken="${result.nextPageToken}" to continue`] : [];
   if (lines.length === 0) {
     return [
@@ -2364,7 +2412,8 @@ var DiscoveredPortSchema = z4.object({
   port: z4.number().int().min(1).max(65535),
   label: z4.string().min(1).max(64).optional(),
   protocol: z4.enum(["http", "tcp"]).optional(),
-  detectedAt: z4.string()
+  detectedAt: z4.string(),
+  hidden: z4.boolean().optional()
 });
 var ReportDiscoveredPortsRequestSchema = z4.object({
   sessionId: z4.string(),
@@ -2511,7 +2560,11 @@ var SubmitCodeReviewResultRequestSchema = z4.object({
 var CycleCodingAgentKeyRequestSchema = z4.object({
   sessionId: z4.string(),
   rateLimitType: z4.string(),
-  resetsAt: z4.string().optional()
+  resetsAt: z4.string().optional(),
+  // The key the pod is actually running (CONVEYOR_CODING_AGENT_KEY_ID). Wins
+  // over the session's attribution stamp after owner validation; optional so
+  // older agents keep the session fallback.
+  codingAgentKeyId: z4.string().optional()
 });
 var PostChildChatMessageRequestSchema = z4.object({
   sessionId: z4.string(),
@@ -2925,11 +2978,12 @@ var QueryProjectGcpLogsRequestSchema = z6.object({
   sqlInstances: z6.array(z6.string().min(1).max(200)).max(25).optional(),
   allServices: z6.boolean().optional(),
   search: z6.string().max(256).optional(),
-  filter: z6.string().max(1e3).optional(),
+  filter: z6.string().max(2e3).optional(),
   startTime: z6.string().optional(),
   endTime: z6.string().optional(),
   limit: z6.number().int().min(1).max(200).optional().default(50),
-  pageToken: z6.string().max(4096).optional()
+  pageToken: z6.string().max(4096).optional(),
+  full: z6.boolean().optional()
 });
 var QueryProjectGrafanaLogsRequestSchema = z6.object({
   projectId: z6.string(),
@@ -4831,6 +4885,20 @@ async function workspacePathExists(path) {
 // src/setup/config.ts
 var DEVCONTAINER_PATH = ".devcontainer/conveyor/devcontainer.json";
 var DEVCONTAINER_PORT_DENY_LIST = /* @__PURE__ */ new Set([5432, 6379, 9200]);
+var MAX_DISCOVERED_LABEL_LENGTH = 64;
+var EXACT_PORT_KEY = /^\d+$/;
+var RANGE_PORT_KEY = /^(\d+)-(\d+)$/;
+function parsePortAttributes(value) {
+  if (!value || typeof value !== "object") return null;
+  const raw = value;
+  const entry = {};
+  if (typeof raw.label === "string") entry.label = raw.label;
+  if (raw.visibility === "public" || raw.visibility === "private") {
+    entry.visibility = raw.visibility;
+  }
+  if (typeof raw.onAutoForward === "string") entry.hidden = raw.onAutoForward === "ignore";
+  return entry;
+}
 async function loadForwardPorts(workspaceDir) {
   try {
     const raw = await readWorkspaceFile(join(workspaceDir, DEVCONTAINER_PATH));
@@ -4840,37 +4908,84 @@ async function loadForwardPorts(workspaceDir) {
     );
     const attributes = {};
     for (const [key, value] of Object.entries(parsed.portsAttributes ?? {})) {
-      if (!value || typeof value !== "object") continue;
-      const entry = {};
-      if (typeof value.label === "string") entry.label = value.label;
-      if (value.visibility === "public" || value.visibility === "private") {
-        entry.visibility = value.visibility;
-      }
-      if (value.onAutoForward === "ignore") entry.hidden = true;
-      attributes[key] = entry;
+      const entry = parsePortAttributes(value);
+      if (entry) attributes[key] = entry;
     }
+    const otherAttributes = parsePortAttributes(parsed.otherPortsAttributes);
     const links = sanitizeSessionPreviewLinks(parsed.customizations?.conveyor?.previewLinks);
-    return { ports, attributes, links };
+    return { ports, attributes, ...otherAttributes ? { otherAttributes } : {}, links };
   } catch {
     return { ports: [], attributes: {}, links: [] };
   }
 }
+function matchingRanges(attributes, port) {
+  const matches = [];
+  for (const [key, attr] of Object.entries(attributes)) {
+    const range = RANGE_PORT_KEY.exec(key);
+    if (!range) continue;
+    const start = Number(range[1]);
+    const end = Number(range[2]);
+    if (start <= port && port <= end) matches.push({ start, attr });
+  }
+  return matches.sort((a, b) => a.start - b.start).map(({ attr }) => attr);
+}
+function exactAttributes(attributes, port) {
+  const match = Object.entries(attributes).find(
+    ([key]) => EXACT_PORT_KEY.test(key) && Number(key) === port
+  );
+  return match?.[1];
+}
+function resolvePortAttributes(result, port) {
+  const exact = exactAttributes(result.attributes, port);
+  const ranges = matchingRanges(result.attributes, port);
+  const layers = [];
+  if (exact) layers.push(["exact", exact]);
+  for (const range of ranges) layers.push(["range", range]);
+  const declared = layers.length > 0 || result.ports.includes(port);
+  if (!declared && result.otherAttributes) layers.push(["other", result.otherAttributes]);
+  const attrs = {};
+  let labelSource = null;
+  for (const [source, layer] of layers) {
+    if (attrs.label === void 0 && layer.label !== void 0) {
+      attrs.label = layer.label;
+      labelSource = source;
+    }
+    attrs.visibility ??= layer.visibility;
+    attrs.hidden ??= layer.hidden;
+  }
+  if (attrs.visibility === void 0) delete attrs.visibility;
+  if (attrs.hidden === void 0) delete attrs.hidden;
+  return { attrs, labelSource };
+}
 function buildSessionPreviewPorts(result) {
   const toEntry = (port) => {
-    const attr = result.attributes[String(port)];
+    const { attrs } = resolvePortAttributes(result, port);
     const entry = { port };
-    if (attr?.label) entry.label = attr.label;
-    if (attr?.visibility) entry.visibility = attr.visibility;
-    if (attr?.hidden) entry.hidden = true;
+    if (attrs.label) entry.label = attrs.label;
+    if (attrs.visibility) entry.visibility = attrs.visibility;
+    if (attrs.hidden) entry.hidden = true;
     return entry;
   };
   const forwarded = result.ports.filter((port) => !DEVCONTAINER_PORT_DENY_LIST.has(port));
   const listed = new Set(forwarded);
-  const hiddenOnly = Object.entries(result.attributes).filter(([, attr]) => attr.hidden).map(([key]) => Number(key)).filter(
+  const hiddenOnly = Object.entries(result.attributes).filter(([key, attr]) => attr.hidden && EXACT_PORT_KEY.test(key)).map(([key]) => Number(key)).filter(
     (port) => Number.isInteger(port) && port >= 1 && port <= 65535 && !listed.has(port) && !DEVCONTAINER_PORT_DENY_LIST.has(port)
   );
   return [...forwarded, ...hiddenOnly].map(toEntry);
 }
+function annotateDiscoveredPorts(result, ports) {
+  return ports.map((entry) => {
+    const { attrs, labelSource } = resolvePortAttributes(result, entry.port);
+    const annotated = { ...entry };
+    if (attrs.hidden) annotated.hidden = true;
+    const label = attrs.label?.trim().slice(0, MAX_DISCOVERED_LABEL_LENGTH);
+    if (label && (labelSource === "range" || labelSource === "other")) annotated.label = label;
+    return annotated;
+  });
+}
+async function loadAndAnnotateDiscoveredPorts(workspaceDir, ports) {
+  return annotateDiscoveredPorts(await loadForwardPorts(workspaceDir), ports);
+}
 function loadConveyorConfig() {
   const envStart = process.env.CONVEYOR_START_COMMAND;
   if (envStart) {
@@ -5329,9 +5444,18 @@ var PortDiscovery = class {
   confirmedKey() {
     return this.confirmedPorts().map(({ port }) => port).join(",");
   }
+  async annotateSafe(ports) {
+    if (!this.opts.annotate) return ports;
+    try {
+      return await this.opts.annotate(ports);
+    } catch {
+      return ports;
+    }
+  }
   async flushReport() {
-    const ports = this.confirmedPorts();
-    const key = ports.map(({ port }) => port).join(",");
+    const confirmed = this.confirmedPorts();
+    const key = confirmed.map(({ port }) => port).join(",");
+    const ports = await this.annotateSafe(confirmed);
     try {
       await this.opts.report(ports);
       this.lastReportedKey = key;
@@ -5481,9 +5605,10 @@ export {
   pushToOrigin,
   flushAllPendingWork,
   awaitGitReady,
-  PortDiscovery,
-  CodespacePortVisibility,
   loadForwardPorts,
   buildSessionPreviewPorts,
-  loadConveyorConfig
+  loadAndAnnotateDiscoveredPorts,
+  loadConveyorConfig,
+  PortDiscovery,
+  CodespacePortVisibility
 };

package/dist/cli.js

@@ -7,7 +7,7 @@ import {
   WorkspaceCommandSupervisor,
   startWorkspaceCommandsAfterConnect,
   stopWorkspaceCommands
-} from "./chunk-G2CE3NFY.js";
+} from "./chunk-4H75HQVM.js";
 import {
   PtyHarness,
   SessionRunner,
@@ -27,7 +27,7 @@ import {
   runUsageProbe,
   sampleKeyUsage,
   usesNativeUsageReporting
-} from "./chunk-7RC5YJDF.js";
+} from "./chunk-42YPRICN.js";
 import "./chunk-37J5MMQT.js";
 import {
   inheritedEnv,
@@ -45,8 +45,9 @@ import {
   applyBootstrapToEnv,
   createServiceLogger,
   fetchBootstrap,
+  loadAndAnnotateDiscoveredPorts,
   loadConveyorConfig
-} from "./chunk-CG7AHC25.js";
+} from "./chunk-KMBMW3J3.js";
 import "./chunk-Q4FQOJ7D.js";
 import "./chunk-W4LZ7R6Z.js";
 import "./chunk-372R6E4C.js";
@@ -417,6 +418,7 @@ var AdhocSessionRunner = class {
     const portVisibility = new CodespacePortVisibility();
     this.portDiscovery = deps?.portDiscovery ?? new PortDiscovery({
       report: (ports) => this.connection.reportDiscoveredPorts(ports),
+      annotate: (ports) => loadAndAnnotateDiscoveredPorts(config.workspaceDir, ports),
       onReported: (ports) => portVisibility.ensureVisible(ports.map(({ port }) => port))
     });
     this.commandSupervisor = deps?.commandSupervisor ?? new WorkspaceCommandSupervisor({
@@ -1468,7 +1470,7 @@ if (!RUNNER_MODES.includes(CONVEYOR_MODE)) {
   process.exit(1);
 }
 if (CONVEYOR_MODE === "serving") {
-  const { runServingSession } = await import("./serve-boot-YARBQBSA.js");
+  const { runServingSession } = await import("./serve-boot-TZZ45CJR.js");
   exitContext.runnerMode = "serving";
   exitContext.sessionId = process.env.CONVEYOR_SESSION_ID ?? exitContext.sessionId;
   const outcome = await runServingSession({

package/dist/index.d.ts

@@ -374,6 +374,12 @@ declare class AgentConnection {
      * limited and hand back the best remaining key's credential env (or a
      * requeue confirmation when none is left). Awaited: the caller swaps
      * credentials and resumes on success, so it needs the real response.
+     *
+     * Names the key this pod is running so the server stamps THAT key: the
+     * session's own attribution can lag the credential a wake handed out, and
+     * stamping it blindly is how one key's cap landed on another. Read from the
+     * env at call time on purpose — `applyCycledKeyEnv` rewrites the var after a
+     * successful cycle, so a second cap names the replacement.
      */
     cycleCodingAgentKey(rateLimitType: string, resetsAt?: string): Promise<{
         cycled: true;
@@ -1315,6 +1321,9 @@ declare function removeWorktree(projectDir: string, taskId: string): Promise<voi
 interface ConveyorConfig {
     startCommand?: string;
 }
+/** `hidden` is tri-state: `true` for `onAutoForward: "ignore"`, `false` for
+ *  any other `onAutoForward` value (so an exact `"notify"` can override a
+ *  range `"ignore"`), absent when the entry does not set it. */
 type PortAttributes = {
     label?: string;
     visibility?: "public" | "private";
@@ -1323,6 +1332,8 @@ type PortAttributes = {
 interface ForwardPortsResult {
     ports: number[];
     attributes: Record<string, PortAttributes>;
+    /** `otherPortsAttributes` — applies only to ports nothing else declares. */
+    otherAttributes?: PortAttributes;
     /** `customizations.conveyor.previewLinks`, sanitized. */
     links: SessionPreviewLink[];
 }

package/dist/index.js

@@ -1,7 +1,7 @@
 import {
   SessionRunner,
   unshallowRepo
-} from "./chunk-7RC5YJDF.js";
+} from "./chunk-42YPRICN.js";
 import "./chunk-37J5MMQT.js";
 import "./chunk-EKTPDG3G.js";
 import {
@@ -17,7 +17,7 @@ import {
   stageAndCommit,
   updateRemoteToken,
   workspacePathExists
-} from "./chunk-CG7AHC25.js";
+} from "./chunk-KMBMW3J3.js";
 import "./chunk-Q4FQOJ7D.js";
 import {
   runAuthTokenCommand,

package/dist/{serve-boot-YARBQBSA.js → serve-boot-TZZ45CJR.js}

@@ -1,6 +1,6 @@
 import {
   WorkspaceCommandSupervisor
-} from "./chunk-G2CE3NFY.js";
+} from "./chunk-4H75HQVM.js";
 import {
   AgentConnection,
   CodespacePortVisibility,
@@ -10,8 +10,9 @@ import {
   awaitGitReady,
   createServiceLogger,
   ensureOnTaskBranch,
+  loadAndAnnotateDiscoveredPorts,
   loadConveyorConfig
-} from "./chunk-CG7AHC25.js";
+} from "./chunk-KMBMW3J3.js";
 import "./chunk-Q4FQOJ7D.js";
 import "./chunk-W4LZ7R6Z.js";
 import "./chunk-IA45XHOA.js";
@@ -38,6 +39,7 @@ var ServeSessionRunner = class {
     const portVisibility = new CodespacePortVisibility();
     this.portDiscovery = deps?.portDiscovery ?? new PortDiscovery({
       report: (ports) => this.connection.reportDiscoveredPorts(ports),
+      annotate: (ports) => loadAndAnnotateDiscoveredPorts(config.workspaceDir, ports),
       onReported: (ports) => portVisibility.ensureVisible(ports.map(({ port }) => port))
     });
     this.commandSupervisor = deps?.commandSupervisor ?? new WorkspaceCommandSupervisor({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rallycry/conveyor-agent",
-  "version": "11.0.42",
+  "version": "11.0.44",
   "description": "Conveyor Agent Runner v10 - PTY harness for the task chat (SDK harness for audit/project-chat). Agent-as-User architecture with BaseService patterns. Works locally too.",
   "keywords": [
     "agent",

package/skills/conveyor-build/SKILL.md

@@ -102,6 +102,12 @@ task binding and no user account.
   stack) is the entire value of local execution, and worktrees have none of it.
   A dirty `git status` before any branch switch is a hard stop: report and let
   the user commit or stash. Do not solve it with a second checkout.
+- **Take turns on the checkout.** Another local session can share this
+  checkout, and a clean tree does not prove it is idle. Hold the checkout
+  claim from before the card claim until the finish line, and never switch
+  branches while another session holds it — the protocol, commands, and what
+  each result means are in
+  [references/checkout-claim.md](references/checkout-claim.md). A pod skips it.
 - The dev database and dev-server ports are shared with the user's own
   sessions. No destructive experiments, never reset the dev DB, and reuse a
   running dev stack rather than fighting over ports.
@@ -149,10 +155,13 @@ say why.
 
 ## Claim
 
-Re-confirm the card is still claimable, then `mcp__conveyor__update_task` →
+Re-confirm the card is still claimable. **Locally**, take the checkout claim
+first (`checkout acquire --card <slug>`,
+[references/checkout-claim.md](references/checkout-claim.md)); `held` means
+flag and wait, not claim. Then `mcp__conveyor__update_task` →
 `status: "InProgress"`, then `mcp__conveyor__post_to_chat` with a claim marker
 naming where you are running. Status changed under you → someone else took it;
-stop.
+release the checkout claim and stop.
 
 **A pack parent is claimed differently** — see the pack path. The parent stays
 parked and the chat marker IS the claim.
@@ -285,7 +294,10 @@ Refresh against the card's base first, then gate, then open — in that order, s
 nothing invalidates the verification you just did:
 
 1. `git fetch origin <base> && git merge origin/<base> --no-edit`
-2. One verification pass, scoped to the diff.
+2. One verification pass, scoped to the diff. **Locally**, run
+   `checkout verify --card <slug>` before the pass, each commit and push, and
+   the PR call; anything but `ok` means stop (see
+   [references/checkout-claim.md](references/checkout-claim.md)).
 3. `mcp__conveyor__create_pull_request`, naming the base branch **explicitly**.
    **The two surfaces spell these differently and unknown keys are silently
    dropped, not rejected** — locally it is `head:` / `base:`; in a pod it is
@@ -298,6 +310,8 @@ nothing invalidates the verification you just did:
    should look at, and anything you did NOT do.
 
 Then confirm CI actually started (read-only `gh pr checks`). Do not wait on it.
+**Locally**, that is the finish line for the checkout too:
+`checkout release --card <slug>`.
 
 **Do not re-merge the base and do not re-run a gate that already passed.** If
 the base moved while the gates ran, open the PR anyway — CI validates against
@@ -332,8 +346,9 @@ After two genuinely different failed approaches, or on a decision only the user
 can make: post the reason AND the specific question to chat, set the card back
 to `"Open"`, restore the tree (locally, `git checkout dev` — leaving a shared
 checkout parked on an abandoned feature branch is how the next session starts
-from the wrong base), and stop. A vague "this is hard" is not a handoff; the
-question is what makes it one.
+from the wrong base), release the checkout claim locally
+(`checkout release --card <slug>`), and stop. A vague "this is hard" is not a
+handoff; the question is what makes it one.
 
 **A thin plan is a different case, and it does not stop a pack.** A card whose
 plan fails the context-free-reader bar: post what is missing to its chat and

package/skills/conveyor-build/references/checkout-claim.md

@@ -0,0 +1,98 @@
+# Checkout claim — local sessions take turns on one checkout
+
+The protocol behind every "hold the checkout claim" line in
+[conveyor-build](../SKILL.md), its [task path](task-path.md) and
+[pack path](pack-path.md), [conveyor-local-loop](../../conveyor-local-loop/SKILL.md),
+and local fixes in [conveyor-review](../../conveyor-review/SKILL.md).
+
+**Why.** The card claim (`InProgress` plus a chat marker) stops two sessions
+working ONE card. It does nothing about two sessions working two cards in ONE
+checkout. A clean tree passes the "dirty `git status` → stop" rule even while
+another session is mid-task, so `git checkout -B <branch>` succeeds and switches
+the branch underneath it. The checkout claim closes that gap: one session holds
+the working tree at a time, and every other session waits.
+
+**Scope: local only.** A pod has its own checkout and never runs this. Skip
+every checkout-claim step when you are in a pod.
+
+## How to call it
+
+The helper is the `checkout` subcommand of the `conveyor-skills` bin. Pick the
+form once per session:
+
+```bash
+[ -x node_modules/.bin/conveyor-skills ] && echo local || echo npx
+```
+
+- `local` → `node_modules/.bin/conveyor-skills checkout <command> …`
+- `npx` → `npx -y -p @rallycry/conveyor-skills@latest conveyor-skills checkout <command> …`
+- The local bin answers `unknown command 'checkout'` (an older branch or an old
+  install) → use the `npx` form.
+
+Write the chosen form out literally in every call. Never store it in a shell
+variable and run `$VAR checkout …`: zsh does not word-split it.
+
+`--card` is the card you are working. Inside a pack it is ALWAYS the pack
+parent's slug, for the whole run. Identity comes from `CONVEYOR_SESSION_ID`, then
+`CLAUDE_CODE_SESSION_ID`. A runtime that sets neither passes a stable
+`--session <id>` on every call; without it the identity falls back to
+`card:<slug>`, which still works but frees a dead holder only after the TTL.
+
+The claim is one file, `<git dir>/conveyor-checkout-claim.json`. It is never
+committed and never shows in `git status`. Each command prints ONE line of
+JSON on stdout (`{"command","state","head","dirty",…}`) and a hint on stderr.
+
+## When
+
+| Moment | Command |
+| --- | --- |
+| Before the first git write or card status write (before the claiming `update_task`) | `acquire --card <slug>` |
+| After every branch create or switch | `acquire --card <slug> --branch <branch>` |
+| Before each gate, commit, push, and `create_pull_request`; at the start of every wake while you hold the claim | `verify --card <slug>` (also refreshes the heartbeat) |
+| Finish line reached (PR open, CI started), parked, blocked, or the card claim lost — after restoring the tree | `release --card <slug>` |
+
+## What each result means
+
+| Command | State (exit) | Do this |
+| --- | --- | --- |
+| `acquire` | `acquired`, `refreshed` (0) | Carry on. |
+| `acquire` | `took-over` (0) | The previous holder was dead or stale. If `dirty` is true, the tree holds that claim's unfinished work for THIS card: audit it before you continue. |
+| `acquire` | `held` (3) | Another session holds the checkout. Touch nothing — no checkout, no status write, no commit. Flag it (below), then wait. |
+| `acquire` | `dirty` (5) | The tree is dirty and no live claim covers it. Hard stop: report it. The user commits or stashes, never you. |
+| `verify` | `ok` (0) | Carry on. |
+| `verify` | `branch-moved` (4) | HEAD is not the claimed branch — someone switched it, or your own checkout failed and left you on the previous branch. Do not commit or push. Report it and stop. |
+| `verify` | `lost` (3) | You no longer hold the claim. Stop touching the tree and `acquire` again, then follow that result. |
+| `release` | `released`, `none` (0) | Done. |
+| `release` | `held` (3) | The claim is not yours. Leave it. |
+| any | `error` (1) | Usage error or not a git repo. Read the stderr line. |
+
+**Flag, then wait.** On `held`, tell the user which card, branch and host hold
+the checkout (the `holder` field has all three). A standalone build also posts
+one line to its card's chat, for example
+`[build] waiting — checkout held by <card> on <branch>`. Then wait:
+
+```bash
+node_modules/.bin/conveyor-skills checkout wait --timeout 1740   # or the npx form
+```
+
+In Claude Code, launch it with Bash `run_in_background: true` and end the
+turn. Its completion notification is the wake. In Codex, hold the command
+session open until it returns. The result is advisory, like `conveyor-wait`:
+`free`, `stale`, or `own` → run `acquire` again; `timeout` → arm ONE new wait.
+Never arm a second wait while one is running.
+
+## Rules that go with the claim
+
+- **Stage by path, never `git add -A`.** In a shared checkout an untracked file
+  can belong to another session.
+- **No claim, dirty tree → refuse.** `acquire` enforces the old "dirty tree is
+  a hard stop" rule deterministically. It also covers ad-hoc sessions that
+  never take a claim.
+- **A stale claim is taken over only on a clean tree, or when it names the
+  same card.** A holder is stale when its pid is dead on this host, when the
+  same pid now runs a different session (a `/clear`), or when its heartbeat is
+  older than the TTL (7200s; `CONVEYOR_CHECKOUT_CLAIM_TTL_SECONDS` or `--ttl`
+  overrides it).
+- **Human override.** `checkout status` shows the holder and never changes
+  anything. `checkout release --force` drops someone else's claim, or a claim
+  file that does not parse. Run it only when the user tells you to.

package/skills/conveyor-build/references/pack-path.md

@@ -24,6 +24,13 @@ alternative is where pack incidents come from.
    IMMEDIATELY record it: `mcp__conveyor__update_task` with
    `githubBranch: <branch>`.
 
+   **Locally, take the checkout claim before any of this** —
+   `checkout acquire --card <parent-slug>` before you cut or check out the
+   pack branch, then `acquire --card <parent-slug> --branch <pack>` once you
+   are on it ([checkout-claim.md](checkout-claim.md)). The pack holds the
+   claim for the WHOLE run: `--card` stays the parent's slug through every
+   child, and `--branch` follows each child-branch and pack-branch switch.
+
    That write is load-bearing, not bookkeeping. Identification mints a
    competing `conveyor/*` branch name onto any branchless card it processes,
    and every pack-child merge handler keys on the card's recorded branch
@@ -121,6 +128,10 @@ state and is a no-op. This is NOT the "insurance wakeup" the pod prompt
 forbids: that rule is about a background job's own completion notification,
 which does fire. Nothing at all notifies a pack between children, so the
 heartbeat is the only guaranteed wake a Claude pack has. Do not delete it.
+Locally, every wake — heartbeat or not — starts with
+`checkout verify --card <parent-slug>` before it touches the tree, and a
+result other than `ok` stops the pack (see
+[checkout-claim.md](checkout-claim.md)).
 
 **Codex CLI.** There is no `ScheduleWakeup` and no `/loop`. The thread goal
 created per the SKILL.md *Goal and finish line* section is the continuation:
@@ -153,7 +164,10 @@ parent chat, skip that child, and take the next ready one.
 Then follow [task-path.md](task-path.md), with one substitution: the child
 branches from the **pack branch**, not `dev`, and its PR's base is the pack
 branch. Name that base explicitly — the default is `dev`, and the two surfaces
-spell the argument differently (`base:` locally, `baseBranch:` in a pod).
+spell the argument differently (`base:` locally, `baseBranch:` in a pod). The
+pack already holds the checkout claim, so the task path's claim steps become
+`acquire --card <parent-slug> --branch <child-branch>` after you cut the child
+branch, and there is no release at the child's finish line.
 
 > **Environment — a pod has no child branches and no child PRs.** Everything
 > above describes the LOCAL model, where each child gets its own branch and its
@@ -261,7 +275,8 @@ leave the branch pushed, and stop.
    `base:` `dev`. The parent moves to ReviewPR. Post the pack summary: what
    shipped per child, how it was verified, what reviewers should look at.
 4. Confirm CI started. **Never approve or merge this PR** — it is the one that
-   gets independent review.
+   gets independent review. Locally, release the checkout:
+   `checkout release --card <parent-slug>`.
 
 ## Parked protocol
 
@@ -269,4 +284,6 @@ After two genuinely different failed approaches on a child, or a decision only
 the user can make: post the reason and the specific question to the child AND
 parent chats, set the child back to `Open`, restore the tree, and take the next
 child whose dependency chain does not run through the parked one. Everything
-remaining blocked → report and stop; the user's reply is the un-park signal.
+remaining blocked → restore the tree, release the checkout claim locally
+(`checkout release --card <parent-slug>`), report, and stop; the user's reply
+is the un-park signal, and the resumed run acquires again.

package/skills/conveyor-build/references/task-path.md

@@ -13,11 +13,14 @@ Re-confirm via `mcp__conveyor__get_task` that the card is still claimable —
 `Open` (or whatever status the user explicitly overrode), no assignee you do
 not expect, no active session. Then:
 
-1. `mcp__conveyor__update_task` → `status: "InProgress"`
-2. `mcp__conveyor__post_to_chat` → `[build] claimed — <where you are running>`
+1. **Locally only:** `checkout acquire --card <slug>` — the checkout claim from
+   [checkout-claim.md](checkout-claim.md). `held` → touch nothing, flag it, and
+   wait; `dirty` → hard stop. A pod skips this step.
+2. `mcp__conveyor__update_task` → `status: "InProgress"`
+3. `mcp__conveyor__post_to_chat` → `[build] claimed — <where you are running>`
 
 If the status changed under you between the read and the write, someone else
-took it. Stop rather than compete.
+took it. Release the checkout claim and stop rather than compete.
 
 ## 2. Branch from the card's base — never blindly `dev`
 
@@ -29,6 +32,10 @@ git fetch origin <base>
 git checkout -B <feat|fix|chore>/<slug> origin/<base>
 ```
 
+Locally, record the branch on the checkout claim straight after the checkout:
+`checkout acquire --card <slug> --branch <feat|fix|chore>/<slug>`. Do the
+same after any later branch switch.
+
 Two cases that are not a fresh branch:
 
 - **The card already has a `githubBranch` with commits on origin.** Resume THAT
@@ -39,7 +46,8 @@ Two cases that are not a fresh branch:
   absent even though the branch exists on the remote. Fetch it explicitly
   (`git fetch origin <branch>`) rather than concluding the branch is missing —
   and note that a failed `checkout` leaves you on your PREVIOUS branch, where a
-  follow-up `git push` will push the wrong thing.
+  follow-up `git push` will push the wrong thing. Locally, `checkout verify`
+  reports exactly that as `branch-moved`.
 
 Reinstall dependencies if the lockfile changed.
 
@@ -62,6 +70,8 @@ Chat at milestones, not per step.
 These are identical to the SKILL.md sections of the same names. In particular:
 sync the base BEFORE the verification pass, pass `base:` explicitly to
 `mcp__conveyor__create_pull_request`, and confirm CI started without waiting on
-it.
+it. Locally, `checkout verify --card <slug>` before the gate, each commit and
+push, and the PR call.
 
 Finish line: the card in ReviewPR with CI started. You do not merge it.
+Locally, `checkout release --card <slug>` once CI has started.

package/skills/conveyor-local-loop/SKILL.md

@@ -47,12 +47,27 @@ adds only selection, claiming, cadence, and local-machine hygiene.
   Clean tree before any branch switch is still a hard rule: dirty
   `git status` at iteration start → touch nothing, report, and idle — the
   resolution is the user committing or stashing, not a second checkout.
+- **Hold the checkout claim while you use the tree.** WIP = 1 is per loop,
+  not per checkout: two loops, or a loop plus an interactive session, can
+  share this checkout, and a clean tree does not prove it is idle. Every tier
+  that touches git takes the claim first and gives it back at the finish line —
+  protocol in [conveyor-build's checkout-claim reference](../conveyor-build/references/checkout-claim.md).
 - **Push early.** There is no pod WIP-autosync locally; committed-and-pushed is
   the only durable state. Push the branch (`-u origin`) as soon as it exists.
 
 ## Iteration order
 
-Each invocation does the FIRST of these that produces work, then paces:
+Each invocation does the FIRST of these that produces work, then paces.
+
+**Checkout first.** Start every iteration with `checkout status`. `live` or
+`corrupt` means another session holds this checkout: skip Recover, Babysit
+fixes, and Claim (all three touch the tree), arm ONE background
+`checkout wait` (see *Waking on board events*), and pace. Otherwise, each tier
+below runs `checkout acquire --card <slug>` for its card before its first git
+command or status write; `held` → stop that tier and arm the wait. The chat
+marker names only the host, so a second loop on this host also matches
+"my" marker in Recover — the checkout claim is what keeps it off a card another
+live loop is still working.
 
 1. **Recover** — a card with my `[local-loop] claimed` chat marker still
    InProgress without a PR? Resume it. The branch may already exist locally or
@@ -89,13 +104,14 @@ Each invocation does the FIRST of these that produces work, then paces:
    Skip `followParentStatus` mirror children. A blocker counts as met only
    when merged-or-beyond (ReviewDev/ReviewLive/Complete) or Cancelled — a
    blocker sitting in ReviewPR is NOT met until its PR merges.
-2. Claim: re-confirm via `get_task` it is still Open, then
-   `mcp__conveyor__update_task` → `status: "InProgress"`, then
+2. Claim: re-confirm via `get_task` it is still Open, take the checkout claim
+   (`checkout acquire --card <slug>`; `held` → do not claim, arm the wait),
+   then `mcp__conveyor__update_task` → `status: "InProgress"`, then
    `mcp__conveyor__post_to_chat`: `[local-loop] claimed — working locally on
    <hostname>`. Claiming a PACK is different — never set the parent
    InProgress: leave it Open and post the pack claim marker instead (see Pack
-   mode). Status changed under you → someone else took it; next
-   candidate.
+   mode). Status changed under you → someone else took it; release the
+   checkout claim and take the next candidate.
 3. Plan missing or failing the context-free-reader bar → don't wing it: post
    what's missing to chat, leave the card Open, skip it.
 
@@ -115,15 +131,18 @@ This section adds only what the LOOP changes:
   re-check the parent's status; if it went InProgress or ReviewPR, post
   `[local-loop] parked: pack coordinator active — yielding`, leave the branch
   pushed, and let the coordinator take over.
-- **Do not wait on CI.** Confirm it started (read-only `gh pr checks`) and end
-  the iteration — the Babysit tier owns it from there. This is the loop's one
-  real departure from a standalone build, which stays with its PR.
+- **Do not wait on CI.** Confirm it started (read-only `gh pr checks`),
+  `checkout release --card <slug>`, and end the iteration — the Babysit tier
+  owns it from there. This is the loop's one real departure from a standalone
+  build, which stays with its PR. A Babysit fix re-acquires with that card and
+  releases again once the fix is pushed. A pack child's PR is the exception:
+  the pack keeps the claim until its finale PR opens.
 
 **Parked protocol** — after 2 genuinely different failed approaches, or on a
 decision only the user can make: post `[local-loop] parked: <reason + the
 specific question>`, set status back to `"Open"`, restore the tree
-(`git checkout dev`), move on. The user's next chat reply is the un-park
-signal.
+(`git checkout dev`), `checkout release --card <slug>`, move on. The user's
+next chat reply is the un-park signal.
 
 ## Pack mode
 
@@ -136,9 +155,9 @@ dev→pack sync after every merge, cross-reference, then the finale parent PR
 into dev. That reference is the source of truth for the procedure; this section
 only defines how it embeds in the loop:
 
-- The pack occupies the loop's single WIP slot from claim until the finale PR
-  opens. Do not interleave unrelated cards mid-pack — that thrashes branch
-  state.
+- The pack occupies the loop's single WIP slot — and holds the checkout
+  claim under the parent's slug — from claim until the finale PR opens. Do not
+  interleave unrelated cards mid-pack — that thrashes branch state.
 - Claim marker goes to the PARENT chat: `[local-loop] claimed — driving this
   pack locally on <hostname>, pack branch <branch>`. The parent's status
   stays Open (parked); the marker is the claim.
@@ -208,9 +227,12 @@ On wake, run a normal iteration and re-enumerate with
 `mcp__conveyor__list_tasks`. By then the card may be claimed, cancelled, or
 blocked by a dependency — never claim straight from the wait payload.
 
-**Never arm a second wait.** On a wake where a wait process is still in flight
-and the queue is still empty, re-arm the fallback `ScheduleWakeup` and end the
-turn.
+**Never arm a second wait.** At most ONE background wait of either kind —
+`conveyor-wait` or `checkout wait` — runs at a time. On a wake where a wait
+process is still in flight and nothing else changed, re-arm the fallback
+`ScheduleWakeup` and end the turn. When the checkout is held, the
+`checkout wait` is the one to arm: the board wait cannot tell you when the
+checkout frees up.
 
 ## Pacing (dynamic /loop only)
 
@@ -219,7 +241,7 @@ Under `/loop` with no interval, end EVERY iteration with exactly one
 
 | State | Delay | Reason should say |
 |-------|-------|-------------------|
-| A background gate/agent/conveyor-wait is in flight — its completion notification is the real wake | 1200–1800s fallback | "fallback while <gate> runs — its notification wakes me sooner" |
+| A background gate/agent/conveyor-wait/checkout wait is in flight — its completion notification is the real wake | 1200–1800s fallback | "fallback while <gate> runs — its notification wakes me sooner" |
 | ANY actionable work exists: claimable cards or packs, a pack child to implement/merge, a PR still to open, red/pending CI, review comments | 60–90s | queue depth / which item is next |
 | Queue enumerated as empty THIS iteration, all loop PRs green and quiet | 1200–1800s | queue empty; conveyor-wait armed, so this is only the fallback |
 | Loop-fatal: MCP dead after 2 tries, dirty tree, broken repo | notify the user (PushNotification if available), then 1800s — or `stop: true` if continuing is unsafe | what is wrong |
@@ -249,7 +271,8 @@ depth each iteration so the user can offload manually.
 - Not a pod: no sandbox, no WIP snapshots, and the dev DB + dev-server ports
   are shared with the user's interactive sessions — no destructive
   experiments, never reset the dev DB, reuse a running dev stack rather than
-  fighting over ports.
+  fighting over ports. The git checkout is shared the same way, which is why
+  the loop takes turns on it through the checkout claim.
 - Not a parallel executor: one card (or one pack) at a time is the point (the
   full machine per gate). Backlogged? That is what claudespaces — or the
   offload valve — are for.

package/skills/conveyor-release-review/SKILL.md

@@ -25,10 +25,11 @@ most two packs.
 **Finish line:** the report — verdict on its first line — posted to the
 conversation, and to the release card's chat when a release card exists.
 
-**A turn may end only when:** (a) the finish line is true, or (b) an
-`AskUserQuestion` is pending because the release scope is genuinely ambiguous.
-Anything else — a ledger with blank rows, findings listed but not filed, packs
-created with no report — is a stalled run, not a paused one.
+**A turn may end only when:** (a) the finish line is true, (b) an
+`AskUserQuestion` is pending because the release scope is genuinely ambiguous,
+or (c) agents you launched are still running; their completion notices resume
+the run. Anything else — a ledger with blank rows, findings listed but not
+filed, packs created with no report — is a stalled run, not a paused one.
 
 **Runtime:** *Codex CLI* — before step 0, create a thread goal with your goal
 tool: "Post a release verdict for <release> with every change evaluated and
@@ -63,6 +64,9 @@ the finish line above is the loop.
   access and any release checklist live in the host repo's CLAUDE.md. A wrapper
   skill may add dimensions (see the end of this file); it cannot lower the
   evidence bar.
+- **The fan-out rules are not project policy.** They follow from how the
+  harness behaves and from account limits, so no project can relax them. A
+  wrapper may LOWER the concurrency cap; it may never raise it or lift a rule.
 
 ## 0 — Discover the project
 
@@ -131,9 +135,21 @@ Anchor to a concrete diff before reading any code.
 5. **Build the coverage ledger** — one row per PR or card, one row per
    dimension in step 2. Every row ends `clean`, `finding`, or
    `not reviewable (why)`. "Evaluate everything" means the ledger has no blank
-   rows when you finish. On a large release, fan subagents out per area and
-   give each the ground rules and the evidence bar verbatim; the ledger is
-   still the completeness check, and it stays with you.
+   rows when you finish.
+
+**Fanning out.** On a large release, split the ledger across subagents per
+area. Give each the ground rules and the evidence bar verbatim. Three rules
+hold, and the mechanics are in [references/fan-out.md](references/fan-out.md):
+
+1. **The hand-back is the only report channel.** The harness refuses report
+   files written by subagents. Each agent's final message is its report, and
+   you save each one to the run directory the moment it arrives.
+2. **Only you spawn agents.** Every agent prompt forbids the Agent, Task and
+   Workflow tools. Nested agents share your session limit.
+3. **At most four agents in flight**, the adversarial agent included. Launch
+   the next slice when one hands back, never in fixed waves.
+
+The ledger is still the completeness check, and it stays with you.
 
 ## 2 — Review every dimension
 
@@ -206,9 +222,12 @@ in it that mattered.
 ## 5 — The adversarial pass
 
 Every candidate that reached step 4, **together with the fix you would
-propose**, now faces a reviewer whose only job is to strike it. Use a fresh
-subagent given the finding, its evidence and the tests below, told to argue
-for striking. Where subagents are unavailable, switch stance explicitly and
+propose**, now faces a reviewer whose only job is to strike it. Use one fresh
+subagent for all candidates, under the fan-out rules. Write the candidates,
+with their evidence, priority and proposed fix, to `candidates.md` in the run
+directory; with no fan-out, put them in the prompt instead. The agent argues
+for striking each against the tests below and hands back one verdict per
+candidate. Where subagents are unavailable, switch stance explicitly and
 write the case against each finding before deciding.
 
 Strike when:
@@ -344,6 +363,10 @@ moves.
   already happened.
 - Diagnosing an incident here. An incident the release implicates is
   evidence; its root cause belongs to `/conveyor-triage`.
+- Telling subagents to write findings files. The harness refuses them. The
+  hand-back is the report, and saving it is your job.
+- Letting a reviewer fan out. Its agents share your session limit, and a limit
+  hit kills every agent in flight with its unsaved work.
 
 ## Wrapping this skill for one project
 
@@ -364,6 +387,10 @@ evidence bar and adversarial pass.
   re-check before concluding.
 - The log tools appear only for a project with the matching integration. If
   they are absent, the project has none; say so instead of hunting.
+- `You've hit your session limit · resets <time>` (HTTP 429) is the account's
+  five-hour usage window, shared by every agent and by you. Nothing runs until
+  the reset, so do not retry. Resume per
+  [references/fan-out.md](references/fan-out.md).
 
 ## Improve This Skill
 

package/skills/conveyor-release-review/references/dimensions.md

@@ -287,3 +287,9 @@ Evidence tools:
 
 A wrapper may add dimensions and name tools. It may not lower the evidence
 bar, skip the adversarial pass, or change what the priority levels mean.
+
+A wrapper also may not relax the fan-out rules in
+[fan-out.md](fan-out.md): subagents hand back text and write no report files,
+only the orchestrator spawns agents, and at most four run at once. These
+follow from how the harness behaves and from account limits, not from project
+policy. A wrapper may LOWER the cap; it may never raise it or lift a rule.

package/skills/conveyor-release-review/references/fan-out.md

@@ -0,0 +1,130 @@
+# Fanning out — the mechanics
+
+How the orchestrator of a [release review](../SKILL.md) splits the ledger
+across subagents without losing their work. SKILL.md states the three rules;
+this file is how to follow them.
+
+## Why
+
+Two limits broke earlier runs. Neither is project policy. Both come from how
+the harness and the account behave, so a wrapper skill may lower the cap
+below but never raise it or lift a rule.
+
+1. **The harness refuses report files from subagents.** Claude Code's Write
+   tool refuses a subagent `.md` whose name starts with REPORT, SUMMARY,
+   FINDINGS or ANALYSIS:
+
+   ```
+   Subagents should return findings as text, not write report files.
+   ```
+
+   This guard is deliberate. Do not route around it with another file name or
+   a Bash heredoc. The subagent's final message is the report.
+
+2. **Every agent draws on one account session limit.** The limit is a single
+   five-hour usage window. Every subagent and the orchestrator share it. When
+   it runs out, every call fails at once:
+
+   ```
+   You've hit your session limit · resets 9:20pm
+   ```
+
+   (HTTP 429, `rateLimitType: "five_hour"`). Every agent in flight dies, and
+   its unsaved work dies with it. The orchestrator is down too, until the
+   reset. A run with 13 agents in flight lost 10; a run with about 10 in flight
+   (one reviewer spawned 3 of its own) lost 5. Runs at 7 and at 4 lost none.
+
+No cap makes a run safe, because the limit is account-wide. The cap bounds
+what one hit destroys. The no-nesting rule and the tool-call budget cut what a
+run spends.
+
+## The run directory
+
+`/tmp/conveyor-release-review/<label-slug>/`, where `<label-slug>` is the
+release label in kebab case (`release-2026-09-30`, `pre-release-2026-09-30`).
+Create it before the first launch. It holds:
+
+- `brief.md` — the shared part of every agent prompt: the brief block below,
+  the ground rules and the evidence bar, verbatim.
+- `ledger.md` — the coverage ledger. Its first line names the run directory,
+  so a resumed or compacted session finds it again.
+- `<slice>.md` — one file per agent, holding that agent's hand-back.
+
+**On each completion notice, in this order:**
+
+1. Write the hand-back verbatim to `<slice>.md`. Do this before you read it
+   closely, and before anything else can fail.
+2. Mark the ledger rows the hand-back covers.
+3. Launch the next slice, if one is waiting.
+
+The saved files are the durable record. They survive compaction and a resume,
+and the adversarial agent reads findings from them by path.
+
+## The brief block
+
+Paste this verbatim into every agent prompt, area and adversarial alike:
+
+```markdown
+1. Your final message is your report. Do not write report, summary or
+   findings files, and do not route a refused write through Bash or another
+   file name. The orchestrator saves your final message.
+2. Do not spawn agents or run workflows (no Agent, Task or Workflow tool).
+   The orchestrator owns all fan-out.
+3. Budget: about 150 tool calls. At the budget, stop and return what you
+   have, listing what you did not reach as "not reviewed".
+4. Already settled, do not re-derive: <list, or "nothing yet">.
+```
+
+Then give the hand-back format:
+
+- **Coverage** — one row per PR or card: `clean`, `finding`, or
+  `not reviewable (why)`.
+- **Findings** — each with its priority, the PR that introduced it, the
+  evidence grade, the exact command and its result, the smallest fix, and the
+  strongest case for striking it.
+- **Unverified** — each with the query that would settle it.
+- **Struck** — each with its reason.
+- **Deploy-checklist items.**
+
+## Scheduling
+
+- **At most 4 agents in flight**, the adversarial agent included.
+- **Launch as slots free up**, not in fixed waves. When one agent hands back
+  and its file is saved, launch the next slice.
+- **One adversarial agent.** Launch it only after every area file exists and
+  you have finished steps 3 and 4. First write `candidates.md`: every
+  candidate that reached step 4, with its evidence, its priority and the fix
+  you would propose. The area files hold raw hand-backs, so they miss your own
+  candidates, your grading and your fixes. The agent reads `candidates.md`,
+  opens the area files only for detail, argues for striking each candidate,
+  and hands back one verdict per candidate. Save its hand-back to
+  `adversarial.md`.
+- While agents run, end the turn. Their completion notices resume the run.
+
+## When an agent dies
+
+**A session limit** (`session limit · resets <time>`):
+
+1. You are down too. Nothing runs until the reset, and an immediate retry
+   fails. Do not retry.
+2. After the reset, reread the run directory and the ledger.
+3. Relaunch only the slices with no `<slice>.md`. Narrow each one if you can,
+   and give each an already-settled list built from the saved files.
+4. Never relaunch above the cap that hit the limit. If 4 in flight hit it,
+   relaunch at 3 or fewer.
+
+**Any other error** (overloaded, or a rate limit with no reset time):
+
+1. Wait a minute or two, then relaunch that one slice once.
+2. If it fails again, review the slice yourself, or mark its ledger rows
+   `not reviewable (agent failed twice: <error>)`.
+
+**Always:**
+
+- Never relaunch a slice whose file exists.
+- Never relaunch a whole wave.
+
+## If you were spawned as a subagent yourself
+
+You are not the orchestrator. Do not fan out. Work the ledger yourself, and
+return your report as your final message.

package/skills/conveyor-review/SKILL.md

@@ -110,6 +110,12 @@ You have write access. Use it in proportion:
 
 - **Small and unambiguous** → fix it, commit, push, then re-review your own
   change as part of the diff. After pushing, wait for CI before approving.
+  **Locally**, a fix checks out the PR branch in a checkout other sessions may
+  share. Run `checkout acquire --card <slug>` before the checkout (`held` →
+  flag the fix instead of making it), `checkout acquire --card <slug> --branch
+  <pr-branch>` after it, and `checkout release --card <slug>` once the fix is
+  pushed and the tree is restored — protocol in
+  [conveyor-build's checkout-claim reference](../conveyor-build/references/checkout-claim.md).
 - **Larger, or a judgment call the author should make** → flag it in the
   verdict with the file, the line, what is wrong, and a suggested direction.
 

package/skills/conveyor-workflows/SKILL.md

@@ -215,6 +215,13 @@ sync-spawned duplicate.
   origin <branch>` and `git merge-base --is-ancestor` before rebuilding
   anything locally — platform autosync may have already pushed for you, and a
   dirty tree may belong to a concurrent session.
+- **Local sessions take turns on one checkout.** `conveyor-build`,
+  `conveyor-local-loop` and local `conveyor-review` fixes hold a checkout
+  claim, so a second session waits instead of switching branches underneath
+  the first. `conveyor-skills checkout status` shows who holds it (card,
+  branch, host, heartbeat age). `conveyor-skills checkout release --force` is
+  the human override for a wedged claim — an agent runs it only when the user
+  says so. Protocol: `conveyor-build/references/checkout-claim.md`.
 
 ## Improve This Skill