sentinelayer-cli 0.46.4 → 0.48.0

package/src/mcp/session-stdio-server.js

@@ -4,11 +4,24 @@ import { setTimeout as sleep } from "node:timers/promises";
 
 import { createAgentEvent } from "../events/schema.js";
 import {
+  approvedSelfProvisioningMcpCall,
   buildCliCommandMcpTools,
   createCliCommandMcpToolHandlers,
+  selfProvisioningMcpInputSchema,
 } from "./cli-command-tools.js";
 import { appendToStream, readStream } from "../session/stream.js";
+import { formatAttachmentSummary, withAttachmentSummary } from "../session/attachment-summary.js";
+import { formatEditSummary, withEditSummary } from "../session/edit-summary.js";
 import { listFileLocks, lockFile, unlockFile } from "../session/file-locks.js";
+import {
+  DEFAULT_ROOM_FILES_LIMIT,
+  DEFAULT_ROOM_FILES_MAX_PAGES,
+  MAX_ROOM_FILES_LIMIT,
+  MAX_ROOM_FILES_MAX_PAGES,
+  RoomFileError,
+  downloadRoomFile,
+  listRoomFiles,
+} from "../session/room-files.js";
 import { resolveSessionDir } from "../session/paths.js";
 import { eventMatchesAgent } from "../session/listener.js";
 import { isSessionControlEvent } from "../session/control-events.js";
@@ -18,6 +31,7 @@ import {
   AdmissionCredentialRefused,
   assertCanonicalAgentId,
   canonicalAgentId,
+  currentAdmittedAgent,
   withAgentAdmission,
 } from "../session/admission-auth.js";
 import { hasStoredAdmissionCredentials, storedAdmissionAgentsForSession } from "../session/admission.js";
@@ -32,14 +46,21 @@ import {
   listSessionMessageActions,
   pollSessionEvents,
   pollSessionEventsBefore,
+  postJudgeVerdictToApi,
   syncSessionEventToApi,
   updateSessionReadCursor,
 } from "../session/sync.js";
+import { extractJudgeVerdictBlock, renderJudgeVerdictMessage, validateJudgeVerdict } from "../judge/verdict.js";
 
 export const SESSION_MCP_SERVER_NAME = "sentinelayer-session-mcp";
 export const SESSION_MCP_PROTOCOL_VERSION = "2025-06-18";
 
 const MAX_MESSAGE_CHARS = 16_000;
+// A judge verdict carries a machine-readable block; cutting it would corrupt the verdict, so the
+// judge tool posts whole messages up to this bound (below the server's message limit) or refuses.
+const JUDGE_MESSAGE_MAX_CHARS = 100_000;
+// A 404 with one of these codes is a real "not here"; any other 404 means the route is absent.
+const JUDGE_NOT_FOUND_CODES = new Set(["SESSION_NOT_FOUND", "TARGET_NOT_FOUND"]);
 const MAX_TOOL_LIMIT = 200;
 const DEFAULT_TOOL_LIMIT = 50;
 const SESSION_MCP_CONFIRM_ATTEMPTS = 3;
@@ -172,11 +193,17 @@ function eventAgentId(event = {}) {
   return normalizeAgentId(event?.agent?.id || event?.agentId || event?.agent_id, "");
 }
 
+// A judge verdict is read whole by the coder: the numbered comments and the block are the point.
+function carriesJudgeVerdict(payload) {
+  return isPlainObject(payload.judgeVerdict) || extractJudgeVerdictBlock(payload.message).status !== "none";
+}
+
 function safePayload(payload = {}) {
   if (!isPlainObject(payload)) return {};
   const next = { ...payload };
   if (typeof next.message === "string") {
-    const truncated = truncateText(next.message, MAX_MESSAGE_CHARS);
+    const limit = carriesJudgeVerdict(next) ? JUDGE_MESSAGE_MAX_CHARS : MAX_MESSAGE_CHARS;
+    const truncated = truncateText(next.message, limit);
     next.message = truncated.text;
     if (truncated.truncated) next.truncated = true;
   }
@@ -200,6 +227,8 @@ function summarizeSessionEvent(event = {}) {
         })
       : undefined,
     payload: safePayload(event.payload),
+    attachmentSummary: formatAttachmentSummary(event) || undefined,
+    editSummary: formatEditSummary(event) || undefined,
     eventId: normalizeString(event.eventId),
     idempotencyToken: normalizeString(event.idempotencyToken),
   });
@@ -680,8 +709,9 @@ function buildSessionMessageEvent({
   nowIso = new Date().toISOString(),
   uuid = randomUUID,
   extraPayload = {},
+  maxChars = MAX_MESSAGE_CHARS,
 } = {}) {
-  const messageShape = truncateText(message);
+  const messageShape = truncateText(message, maxChars);
   if (!messageShape.text) {
     throw new Error("message is required.");
   }
@@ -927,7 +957,7 @@ export async function isAgentContext({ env = process.env } = {}) {
  */
 export async function runInSessionToolContext(name, input = {}, run, { env = process.env } = {}) {
   const routeClass = sessionRouteClass(`mcp:${name}`);
-  if (routeClass === "exempt-local") return run(input);
+  if (routeClass === "exempt-local" || routeClass === "self-provisioning") return run(input);
   if (!(await isAgentContext({ env }))) return run(input);
   if (routeClass === "owner") refuseOutsideAdmission("owner actions are not available to agents");
   const sessionId = normalizeString(input.sessionId || input.session_id || input.session);
@@ -968,7 +998,11 @@ export function createSessionMcpToolHandlers({
   lockFileFn = lockFile,
   unlockFileFn = unlockFile,
   listFileLocksFn = listFileLocks,
+  listRoomFilesFn = listRoomFiles,
+  downloadRoomFileFn = downloadRoomFile,
   syncSessionEventToApiFn = syncSessionEventToApi,
+  postJudgeVerdictToApiFn = postJudgeVerdictToApi,
+  currentAdmittedAgentFn = currentAdmittedAgent,
   appendToStreamFn = appendToStream,
   sleepFn = sleep,
   uuidFn = randomUUID,
@@ -1070,7 +1104,7 @@ export function createSessionMcpToolHandlers({
               count: Array.isArray(actionResult.actions) ? actionResult.actions.length : 0,
             }
           : null,
-        events: includeRaw ? events : events.map((event) => summarizeSessionEvent(event)),
+        events: events.map((event) => includeRaw ? withEditSummary(withAttachmentSummary(event)) : summarizeSessionEvent(event)),
       };
     },
 
@@ -1163,7 +1197,7 @@ export function createSessionMcpToolHandlers({
               count: Array.isArray(actionResult.actions) ? actionResult.actions.length : 0,
             }
           : null,
-        events: includeRaw ? events : events.map((event) => summarizeSessionEvent(event)),
+        events: events.map((event) => includeRaw ? withEditSummary(withAttachmentSummary(event)) : summarizeSessionEvent(event)),
       };
     },
 
@@ -1195,6 +1229,105 @@ export function createSessionMcpToolHandlers({
       });
     },
 
+    async judge_verdict(input = {}) {
+      const sessionId = requireSessionId(input, { targetPath });
+      const agentId = requireAgentId(input);
+      const via = normalizeString(input.via || "auto").toLowerCase();
+      if (!["auto", "api", "room"].includes(via)) {
+        throw new Error('via must be "auto", "api" or "room".');
+      }
+      const checked = validateJudgeVerdict(input.verdict);
+      if (!checked.ok) {
+        return { ok: false, reason: "invalid_verdict", errors: checked.errors, sessionId, agentId };
+      }
+      const verdict = checked.verdict;
+      if (normalizeAgentId(verdict.coder, "") === agentId) {
+        return { ok: false, reason: "self_judgement", sessionId, agentId, coder: verdict.coder };
+      }
+      const escalateTo = normalizeRecipients(input.escalateTo || input.escalate_to);
+      // The API route mentions the room owner on escalation; naming other people needs the room message,
+      // which carries their mentions. So an escalation to named handles never goes through the route.
+      const namedEscalation = verdict.escalate && escalateTo.length > 0;
+      if (namedEscalation && via === "api") {
+        return { ok: false, reason: "escalate_to_needs_room_transport", sessionId, agentId, escalateTo };
+      }
+      // The route records whoever the credential is. Only this agent's own admission makes that the agent;
+      // under the person's token the route would record the person. The room message is checked against the
+      // agent's grant instead, so without the admission the verdict goes as a room message.
+      const admitted = currentAdmittedAgentFn();
+      const agentCredential = Boolean(admitted && admitted.sessionId === sessionId &&
+        normalizeAgentId(admitted.agentId, "") === agentId);
+      if (via === "api" && !agentCredential) {
+        return { ok: false, reason: "api_needs_agent_credential", sessionId, agentId };
+      }
+      const message = renderJudgeVerdictMessage(verdict, { escalateTo });
+      if (message.length > JUDGE_MESSAGE_MAX_CHARS) {
+        return { ok: false, reason: "verdict_message_too_long", sessionId, agentId, limit: JUDGE_MESSAGE_MAX_CHARS };
+      }
+      const dryRun = Boolean(input.dryRun || input.dry_run);
+      if (dryRun) {
+        return { ok: true, dryRun: true, sessionId, agentId, via, verdict, message };
+      }
+
+      let api = null;
+      if (via !== "room" && !namedEscalation && agentCredential) {
+        api = await postJudgeVerdictToApiFn(sessionId, verdict, { targetPath });
+        const apiSummary = { status: api?.status || 0, code: api?.code || "", reason: api?.reason || "" };
+        if (api?.ok) {
+          return { ok: true, transport: "api", sessionId, agentId, verdict, api: { ...apiSummary, body: api.body } };
+        }
+        // Fall back to the room post only when the route itself is absent (an older server, or
+        // the judge loop switched off there): a refusal or a lost response is reported as is.
+        const routeAbsent = api?.status === 404 && !JUDGE_NOT_FOUND_CODES.has(api.code);
+        if (via === "api" || !routeAbsent) {
+          return {
+            ok: false,
+            transport: "api",
+            reason: apiSummary.code || apiSummary.reason || "api_failed",
+            sessionId,
+            agentId,
+            api: { ...apiSummary, body: api?.body || null },
+          };
+        }
+      }
+
+      const agent = buildAgentEnvelope(agentId, { ...input, role: normalizeString(input.role) || "reviewer" });
+      const idempotencyKey = normalizeString(input.idempotencyKey || input.idempotency_key) ||
+        `judge-${shortSha256(JSON.stringify([sessionId, agentId, verdict.target.type, verdict.target.ref, verdict.round]))}`;
+      const event = buildSessionMessageEvent({
+        event: "session_message",
+        sessionId,
+        agent,
+        message,
+        recipients: [normalizeAgentId(verdict.coder, verdict.coder)],
+        idempotencyKey,
+        nowIso: now(),
+        uuid: uuidFn,
+        maxChars: JUDGE_MESSAGE_MAX_CHARS,
+      });
+      const posted = await persistSessionEvent({
+        sessionId,
+        event,
+        targetPath,
+        dryRun: false,
+        syncSessionEventToApiFn,
+        pollSessionEventsBeforeFn,
+        pollSessionEventsFn,
+        appendToStreamFn,
+        sleepFn,
+      });
+      return {
+        ...posted,
+        transport: "room",
+        ...(api ? { fellBackFrom: "api_route_absent" } : {}),
+        ...(via === "auto" && namedEscalation ? { roomBecause: "escalate_to_named_handles" } : {}),
+        ...(via === "auto" && !namedEscalation && !agentCredential ? { roomBecause: "no_agent_credential" } : {}),
+        sessionId,
+        agentId,
+        verdict,
+      };
+    },
+
     async session_action(input = {}) {
       return runSessionAction({
         input,
@@ -1307,6 +1440,57 @@ export function createSessionMcpToolHandlers({
       };
     },
 
+    async session_files_list(input = {}) {
+      const sessionId = requireSessionId(input, { targetPath });
+      const result = await listRoomFilesFn(sessionId, {
+        targetPath,
+        limit: input.limit,
+        maxPages: input.maxPages ?? input.max_pages,
+      });
+      return {
+        ok: Boolean(result?.ok),
+        reason: normalizeString(result?.reason),
+        sessionId,
+        count: Number(result?.count) || 0,
+        complete: Boolean(result?.complete),
+        pages: Number(result?.pages) || 0,
+        scannedEvents: Number(result?.scannedEvents) || 0,
+        files: Array.isArray(result?.files) ? result.files : [],
+      };
+    },
+
+    // Writes the file into this server's workspace and returns where; never the bytes.
+    async session_file_get(input = {}) {
+      const sessionId = requireSessionId(input, { targetPath });
+      const attachmentId = normalizeString(input.attachmentId || input.attachment_id);
+      try {
+        const result = await downloadRoomFileFn(sessionId, attachmentId, {
+          targetPath,
+          out: normalizeString(input.out),
+          force: Boolean(input.force),
+          workspaceOnly: true,
+        });
+        return {
+          ok: true,
+          reason: "",
+          sessionId,
+          attachmentId,
+          path: result.path,
+          bytes: result.bytes,
+          sha256: result.sha256,
+          verified: Boolean(result.verified),
+          overwritten: Boolean(result.overwritten),
+          linkRefetched: Boolean(result.linkRefetched),
+          attachment: result.attachment,
+        };
+      } catch (error) {
+        if (error instanceof RoomFileError) {
+          return { ok: false, reason: error.code, message: error.message, sessionId, attachmentId };
+        }
+        throw error;
+      }
+    },
+
     async attention_request(input = {}) {
       const sessionId = requireSessionId(input, { targetPath });
       const agentId = requireAgentId(input);
@@ -1516,6 +1700,34 @@ export const SESSION_MCP_TOOLS = Object.freeze([
       },
     },
   },
+  {
+    name: "judge_verdict",
+    title: "Post Judge Verdict",
+    description:
+      "Send a judge-verdict back to the coding agent: ACCEPT, or CHANGES with numbered file:line comments (severity P0-P3, one-line fix). Validates the verdict first. When the agent acts under its own admission for the room and the server has the judge-verdicts route, the route records it; otherwise it posts a room message that mentions the coder and carries the verdict block (the server checks the agent's grant on that post). via=room always posts the message; dryRun returns the rendered message.",
+    inputSchema: {
+      type: "object",
+      additionalProperties: false,
+      required: ["sessionId", "agentId", "verdict"],
+      properties: {
+        sessionId: { type: "string", minLength: 1 },
+        agentId: { type: "string", minLength: 1 },
+        verdict: { type: "object" },
+        via: { type: "string", enum: ["auto", "api", "room"], default: "auto" },
+        escalateTo: {
+          anyOf: [
+            { type: "string" },
+            { type: "array", items: { type: "string" } },
+          ],
+        },
+        model: { type: "string" },
+        role: { type: "string" },
+        displayName: { type: "string" },
+        idempotencyKey: { type: "string" },
+        dryRun: { type: "boolean", default: false },
+      },
+    },
+  },
   {
     name: "session_action",
     title: "Record Senti Session Action",
@@ -1667,6 +1879,50 @@ export const SESSION_MCP_TOOLS = Object.freeze([
       },
     },
   },
+  {
+    name: "session_files_list",
+    title: "List Senti Room Files",
+    description:
+      "List the files published in a session room, newest first: file name, size, content type, uploader, upload time, the message that published it, and the attachmentId that session_file_get downloads.",
+    inputSchema: {
+      type: "object",
+      additionalProperties: false,
+      required: ["sessionId"],
+      properties: {
+        sessionId: { type: "string", minLength: 1 },
+        agentId: { type: "string", minLength: 1 },
+        limit: { type: "integer", minimum: 1, maximum: MAX_ROOM_FILES_LIMIT, default: DEFAULT_ROOM_FILES_LIMIT },
+        maxPages: {
+          type: "integer",
+          minimum: 1,
+          maximum: MAX_ROOM_FILES_MAX_PAGES,
+          default: DEFAULT_ROOM_FILES_MAX_PAGES,
+          description: "Most pages of room history to read, 200 events each.",
+        },
+      },
+    },
+  },
+  {
+    name: "session_file_get",
+    title: "Download Senti Room File",
+    description:
+      "Download one published room file into the workspace: streamed to disk, checked against the server's sha256, and written atomically. Returns the saved path and the file's metadata, never its bytes. Refuses to overwrite an existing file unless force is true, and refuses an out path outside the workspace. workspaceOnly checks the destination folder when the call starts; it does not protect against another local process renaming or relinking folders inside the workspace during the download.",
+    inputSchema: {
+      type: "object",
+      additionalProperties: false,
+      required: ["sessionId", "attachmentId"],
+      properties: {
+        sessionId: { type: "string", minLength: 1 },
+        agentId: { type: "string", minLength: 1 },
+        attachmentId: { type: "string", pattern: "^[A-Za-z0-9._:-]{8,120}$" },
+        out: {
+          type: "string",
+          description: "File or directory inside the workspace; default: the server's file name in the workspace root.",
+        },
+        force: { type: "boolean", default: false },
+      },
+    },
+  },
   {
     name: "attention_request",
     title: "Request Senti Attention",
@@ -1698,15 +1954,26 @@ export const SESSION_MCP_TOOLS = Object.freeze([
   },
 ]);
 
-function toMcpTool(tool) {
+function toMcpTool(tool, { selfProvisioning = false } = {}) {
+  const security = selfProvisioning
+    ? { ...tool.security, requires_human_approval: false, runtime_blocked: false }
+    : tool.security;
+  if (selfProvisioning) delete security.runtime_block_reason;
+  const selfProvisioningDetail = tool.name === "sl.session.join"
+    ? "A goal requests room-owner admission approval; use wait:false to return the pending URL. Cancellation affects only this agent's pending request."
+    : "It unregisters only this agent.";
   return cleanObject({
     name: tool.name,
     title: tool.title,
-    description: tool.description,
-    inputSchema: tool.inputSchema,
+    description: selfProvisioning
+      ? `${tool.description} Only the host's caller agent may use this tool. ${selfProvisioningDetail}`
+      : tool.description,
+    inputSchema: selfProvisioning ? selfProvisioningMcpInputSchema(tool) : tool.inputSchema,
     annotations: tool.annotations,
-    security: tool.security,
-    metadata: tool.metadata,
+    security,
+    metadata: selfProvisioning
+      ? { ...tool.metadata, approvalRequired: false, approvalPolicy: "caller_bound_self_provisioning" }
+      : tool.metadata,
   });
 }
 
@@ -1744,14 +2011,15 @@ function jsonRpcError(id, code, message, data = undefined) {
   });
 }
 
-// The dispatcher enforces each tool's published policy before its handler runs. A tool that
-// requires human approval is refused: approval would have to be server-validated and bound to the
-// call's arguments, and no such approval exists yet. A runtime-blocked tool is refused too. Refused
-// tools are not advertised by tools/list, and a call to one gets a specific JSON-RPC error.
+// The dispatcher enforces each tool's published policy before its handler runs. Ordinary CLI
+// tools still require human approval, which the bridge cannot validate. The two self-provisioning
+// commands have a narrowly validated caller-bound policy; every call checks its actual arguments.
+// Refused tools are not advertised by tools/list, and a call gets a specific JSON-RPC error.
 export const MCP_HUMAN_APPROVAL_REQUIRED = Object.freeze({ code: -32001, reason: "human_approval_required" });
 export const MCP_TOOL_BLOCKED = Object.freeze({ code: -32002, reason: "tool_blocked" });
 
-function toolRefusal(tool) {
+function toolRefusal(tool, input, { env = process.env, forListing = false } = {}) {
+  if (approvedSelfProvisioningMcpCall(tool, input, { env, forListing })) return "";
   const security = isPlainObject(tool?.security) ? tool.security : {};
   if (security.requires_human_approval === true) return MCP_HUMAN_APPROVAL_REQUIRED.reason;
   if (tool?.metadata?.bridge === "cli-command" && security.requires_human_approval !== false) {
@@ -1789,6 +2057,7 @@ export async function handleMcpJsonRpcMessage(
     targetPath = process.cwd(),
     handlers = createSessionMcpToolHandlers({ targetPath }),
     tools = SESSION_MCP_TOOLS,
+    env = process.env,
   } = {}
 ) {
   if (!isPlainObject(message)) {
@@ -1821,7 +2090,7 @@ export async function handleMcpJsonRpcMessage(
         version: "0.20.0",
       },
       instructions:
-        "Use native Senti tools for coordination actions and generated sl.* bridge tools for the rest of SentinelLayer CLI. Use poll_inbox for addressed wake-style delivery, read_history for recent/older transcript grounding, session_action/session_react/session_reply/session_lock/session_unlock/session_locks for low-noise session work, send_message for durable posts, and generated command tools such as sl.auth.status or sl.review.scan for ordinary CLI commands.",
+        "Use native Senti tools for coordination actions and generated sl.* bridge tools for the rest of SentinelLayer CLI. Use poll_inbox for addressed wake-style delivery, read_history for recent/older transcript grounding, session_action/session_react/session_reply/session_lock/session_unlock/session_locks for low-noise session work, send_message for durable posts, judge_verdict to send a review verdict back to a coding agent, and generated command tools such as sl.auth.status or sl.review.scan for ordinary CLI commands.",
     });
   }
 
@@ -1832,7 +2101,10 @@ export async function handleMcpJsonRpcMessage(
   if (method === "tools/list") {
     if (isNotification) return null;
     return jsonRpcSuccess(id, {
-      tools: tools.filter((tool) => !toolRefusal(tool)).map((tool) => toMcpTool(tool)),
+      tools: tools.filter((tool) => !toolRefusal(tool, undefined, { env, forListing: true }))
+        .map((tool) => toMcpTool(tool, {
+          selfProvisioning: approvedSelfProvisioningMcpCall(tool, undefined, { env, forListing: true }),
+        })),
     });
   }
 
@@ -1842,7 +2114,7 @@ export async function handleMcpJsonRpcMessage(
     const args = isPlainObject(message.params?.arguments) ? message.params.arguments : {};
     const handler = handlers[toolName];
     const tool = (Array.isArray(tools) ? tools : []).find((candidate) => normalizeString(candidate?.name) === toolName);
-    const refusal = typeof handler === "function" && tool ? toolRefusal(tool) : "";
+    const refusal = typeof handler === "function" && tool ? toolRefusal(tool, args, { env }) : "";
     if (refusal) {
       return refusalError(id, toolName, tool, refusal);
     }
@@ -1889,6 +2161,7 @@ export async function handleMcpJsonRpcMessage(
 
 export async function createSessionMcpRuntime({
   targetPath = process.cwd(),
+  env = process.env,
   sessionHandlers = createSessionMcpToolHandlers({ targetPath }),
   sessionTools = SESSION_MCP_TOOLS,
   buildCliCommandMcpToolsFn = buildCliCommandMcpTools,
@@ -1899,9 +2172,14 @@ export async function createSessionMcpRuntime({
     tools: [...sessionTools, ...commandTools],
     handlers: {
       ...sessionHandlers,
-      ...createCliCommandMcpToolHandlersFn(commandTools, { targetPath }),
+      ...createCliCommandMcpToolHandlersFn(commandTools, {
+        targetPath,
+        env,
+        approve: (tool, input) => approvedSelfProvisioningMcpCall(tool, input, { env }),
+      }),
     },
     commandToolCount: commandTools.length,
+    env,
   };
 }
 

package/src/memory/blackboard.js

@@ -1,4 +1,4 @@
-import fsp from "node:fs/promises";
+import { requireOutputFileSystem } from "../config/output-filesystem.js";
 import path from "node:path";
 
 function normalizeString(value) {
@@ -274,13 +274,14 @@ export function summarizeBlackboard(blackboard) {
   };
 }
 
-export async function writeBlackboardArtifact(blackboard, { outputRoot = "" } = {}) {
+export async function writeBlackboardArtifact(blackboard, { outputRoot = "", outputFs } = {}) {
+  requireOutputFileSystem(outputFs);
   if (!blackboard || !Array.isArray(blackboard.entries)) {
     throw new Error("Invalid blackboard state.");
   }
   const resolvedOutputRoot = path.resolve(String(outputRoot || "."));
   const memoryDirectory = path.join(resolvedOutputRoot, "memory");
-  await fsp.mkdir(memoryDirectory, { recursive: true });
+  await outputFs.mkdir(memoryDirectory, { recursive: true });
   const runId = normalizeString(blackboard.runId) || "run";
   const artifactPath = path.join(memoryDirectory, `blackboard-${runId}.json`);
   const summary = summarizeBlackboard(blackboard);
@@ -293,7 +294,7 @@ export async function writeBlackboardArtifact(blackboard, { outputRoot = "" } =
     entries: blackboard.entries,
     queryEvents: blackboard.queryEvents,
   };
-  await fsp.writeFile(artifactPath, `${JSON.stringify(payload, null, 2)}\n`, "utf-8");
+  await outputFs.writeFile(artifactPath, `${JSON.stringify(payload, null, 2)}\n`, "utf-8");
   return {
     artifactPath,
     summary,

package/src/net/gh-api-path.js

@@ -4,11 +4,12 @@
 // (repos/<owner>/<repo>/...) and passes --repo values that gh turns into paths of its own, so each
 // value is checked for its role before any gh process starts:
 //
-//   ghRepoSlug     exactly "owner/repo". The owner starts with a letter or digit, then letters,
-//                  digits, "-" or "_" (Enterprise Managed User names end in "_shortcode"), at most
-//                  39 characters. The repository is letters, digits, ".", "_" or "-", at most 100
-//                  characters, and not "." or "..".
-//   ghCommitSha    7 to 40 hexadecimal characters.
+//   ghRepoSlug     exactly "owner/repo" for gh's --repo option. The owner starts with a letter or
+//                  digit, then letters, digits, "-" or "_" (Enterprise Managed User names end in
+//                  "_shortcode"), at most 39 characters. The repository is letters, digits, ".",
+//                  "_" or "-", at most 100 characters, and not "." or "..".
+//   ghRepoApiPath  the structural repos/<owner>/<repo> path, with owner and repo encoded separately.
+//   ghCommitSha    7 to 64 hexadecimal characters, encoded as one path segment (SHA-1 or SHA-256).
 //   ghRefSegment   a git branch, tag or ref name under git's ref-name rules, not starting with "-",
 //                  percent-encoded as ONE path segment. A branch name may contain "/", and git also
 //                  allows "#", "%", "{" and other characters that mean something in a URL or to gh;
@@ -21,10 +22,18 @@
 
 const OWNER = /^[A-Za-z0-9][A-Za-z0-9_-]{0,38}$/;
 const REPO = /^[A-Za-z0-9._-]{1,100}$/;
-const COMMIT_SHA = /^[0-9A-Fa-f]{7,40}$/;
+const COMMIT_SHA = /^[0-9A-Fa-f]{7,64}$/;
 // Control characters, space, and the other characters git does not allow in a ref name.
 const REF_FORBIDDEN = /[\u0000-\u0020\u007f-\u009f~^:?*[\\]/;
 
+// encodeURIComponent intentionally leaves five RFC 3986 reserved characters alone.
+// Encode those too so a validated value is always an opaque path segment.
+function encodeGhPathSegment(value) {
+  return encodeURIComponent(value).replace(/[!'()*]/g, (character) =>
+    `%${character.charCodeAt(0).toString(16).toUpperCase()}`,
+  );
+}
+
 /** True when `value` is exactly "owner/repo" as GitHub names them. */
 export function isGhRepoSlug(value) {
   if (typeof value !== "string") return false;
@@ -51,12 +60,18 @@ export function ghRepoSlug(value, { label = "repo" } = {}) {
   return value;
 }
 
+/** A `repos/<owner>/<repo>` API path with only its structural separators left raw. */
+export function ghRepoApiPath(value, { label = "repo" } = {}) {
+  const [owner, repo] = ghRepoSlug(value, { label }).split("/");
+  return `repos/${encodeGhPathSegment(owner)}/${encodeGhPathSegment(repo)}`;
+}
+
 /** `value` as a commit SHA path segment, or throws. */
 export function ghCommitSha(value, { label = "sha" } = {}) {
   if (typeof value !== "string" || !COMMIT_SHA.test(value)) {
-    throw new Error(`${label} must be a commit SHA of 7 to 40 hexadecimal characters.`);
+    throw new Error(`${label} must be a commit SHA of 7 to 64 hexadecimal characters.`);
   }
-  return value;
+  return encodeGhPathSegment(value);
 }
 
 /** `value` (a git branch, tag or ref name) percent-encoded as one path segment, or throws. */
@@ -64,5 +79,16 @@ export function ghRefSegment(value, { label = "ref" } = {}) {
   if (!isGitRefName(value)) {
     throw new Error(`${label} must be a valid git branch, tag or ref name.`);
   }
-  return encodeURIComponent(value);
+  return encodeGhPathSegment(value);
+}
+
+/** GitHub compare endpoint with a raw structural `...` between encoded base and head values. */
+export function ghCompareApiPath({ repo, branch, sha }) {
+  const basehead = `${ghRefSegment(branch, { label: "branch" })}...${ghCommitSha(sha)}`;
+  return `${ghRepoApiPath(repo)}/compare/${basehead}`;
+}
+
+/** GitHub check-runs endpoint with `ref` encoded as exactly one path segment. */
+export function ghCheckRunsApiPath({ repo, ref }) {
+  return `${ghRepoApiPath(repo)}/commits/${ghRefSegment(ref)}/check-runs`;
 }

package/src/net/test-egress-guard.js

@@ -103,8 +103,20 @@ export function installTestEgressGuard({ env = process.env, force = false } = {}
   if (typeof nativeFetch !== "function" || typeof NativeRequest !== "function") return false;
   if (nativeFetch[GUARD_MARKER]) return true; // idempotent
 
-  async function followChecked(thisArg, request, hops) {
-    const response = await nativeFetch.call(thisArg, new NativeRequest(request, { redirect: "manual" }));
+  const requestOwners = new WeakMap();
+  async function dispatch(thisArg, request, ancestors = []) {
+    const response = await nativeFetch.call(thisArg, request);
+    // Undici follows cloned Requests through weak AbortController references. Keep
+    // the owners alive through body consumption, including after headers arrive.
+    const owners = [...ancestors, request];
+    requestOwners.set(response, owners);
+    if (response.body) requestOwners.set(response.body, owners);
+    return response;
+  }
+
+  async function followChecked(thisArg, request, hops, ancestors = []) {
+    const owners = [...ancestors, request];
+    const response = await dispatch(thisArg, new NativeRequest(request, { redirect: "manual" }), owners);
     const location = response.headers.get("location");
     if (!REDIRECT_STATUSES.has(response.status) || location === null) return response;
     let next;
@@ -134,7 +146,7 @@ export function installTestEgressGuard({ env = process.env, force = false } = {}
       signal: request.signal,
       redirect: "manual",
     });
-    return followChecked(thisArg, nextRequest, hops + 1);
+    return followChecked(thisArg, nextRequest, hops + 1, owners);
   }
 
   const guarded = function guardedTestFetch(input, init) {
@@ -145,7 +157,7 @@ export function installTestEgressGuard({ env = process.env, force = false } = {}
       return Promise.reject(error); // the same TypeError native fetch would raise
     }
     if (!isAllowedTestDestination(request.url)) return Promise.reject(block(request.url));
-    if (request.redirect !== "follow") return nativeFetch.call(this, request);
+    if (request.redirect !== "follow") return dispatch(this, request);
     return followChecked(this, request, 0);
   };
   Object.defineProperty(guarded, GUARD_MARKER, { value: true });