chainlesschain 0.162.163 → 0.162.164

package/src/lib/plugin-runtime/hooks.js

@@ -17,9 +17,36 @@
 import fs from "fs";
 import { discoverPlugins } from "./scopes.js";
 import { partitionByTrust, warnUntrustedOnce } from "./trust.js";
+import { componentCapabilityDenial } from "./capabilities.js";
 
 export const _deps = { readFileSync: fs.readFileSync };
 
+// One-time stderr notice when a plugin's hooks are refused at the COMPONENT
+// level because the plugin opted into the capability model but did not declare
+// the `process` capability its shell hooks need. Distinct from the trust gate:
+// these plugins ARE trusted, but their hook component is denied.
+const _capabilityDenied = new Set();
+function warnHookCapabilityDeniedOnce(entries) {
+  if (!entries || entries.length === 0) return;
+  if (_capabilityDenied.has("hook-capability")) return;
+  _capabilityDenied.add("hook-capability");
+  const list = entries.map((e) => `${e.name} (${e.reason})`).join("; ");
+  try {
+    process.stderr.write(
+      `[plugins] refused hook(s) from plugin(s) that declared a permissions ` +
+        `block but did not declare the 'process' capability their hooks need: ${list}\n` +
+        `          add 'process' to the plugin's permissions block to enable them.\n`,
+    );
+  } catch {
+    /* stderr notice is best-effort */
+  }
+}
+
+/** Test hook: reset the one-time capability-denied warning guard. */
+export function _resetHookWarnings() {
+  _capabilityDenied.clear();
+}
+
 /** Accept either `{ hooks: {Event:[...]} }` (plugin wrap) or `{Event:[...]}`. */
 function normalizeHookMap(parsed) {
   if (
@@ -57,10 +84,19 @@ export function collectPluginHooks(opts = {}) {
     "hooks",
   );
   const merged = {};
+  const denied = [];
   for (const p of trusted) {
     if (!p.manifest || p.manifest.ok !== true) continue;
     const h = p.manifest.components?.hooks;
     if (!h) continue;
+    // Component-level capability gate: a plugin that declared a permissions
+    // block but under-declared the `process` capability its shell hooks need
+    // gets its hooks refused here (mirrors the MCP collector's denial).
+    const denial = componentCapabilityDenial(p.manifest, ["process"]);
+    if (denial) {
+      denied.push({ name: p.name, reason: denial.reason });
+      continue;
+    }
     let parsed;
     if (h.absPath) {
       try {
@@ -89,6 +125,7 @@ export function collectPluginHooks(opts = {}) {
       merged[event] = (merged[event] || []).concat(entries);
     }
   }
+  warnHookCapabilityDeniedOnce(denied);
   return merged;
 }
 

package/src/lib/plugin-runtime/lsp.js

@@ -16,9 +16,31 @@ import path from "path";
 import { discoverPlugins } from "./scopes.js";
 import { registerLanguageServer } from "../lsp/lsp-server-registry.js";
 import { partitionByTrust, warnUntrustedOnce } from "./trust.js";
+import { componentCapabilityDenial } from "./capabilities.js";
 
 const _loadedRoots = new Set();
 
+// One-time stderr notice when a plugin's LSP servers are refused at the
+// COMPONENT level because the plugin opted into the capability model but did not
+// declare the `process` capability the servers need. Distinct from the trust
+// gate: these plugins ARE trusted, but their LSP component is denied.
+const _capabilityDenied = new Set();
+function warnLspCapabilityDeniedOnce(entries) {
+  if (!entries || entries.length === 0) return;
+  if (_capabilityDenied.has("lsp-capability")) return;
+  _capabilityDenied.add("lsp-capability");
+  const list = entries.map((e) => `${e.name} (${e.reason})`).join("; ");
+  try {
+    process.stderr.write(
+      `[plugins] refused language server(s) from plugin(s) that declared a ` +
+        `permissions block but did not declare the 'process' capability: ${list}\n` +
+        `          add 'process' to the plugin's permissions block to enable them.\n`,
+    );
+  } catch {
+    /* stderr notice is best-effort */
+  }
+}
+
 /**
  * Register every installed plugin's LSP servers for `cwd` (once per root).
  * Never throws — a broken plugin manifest must not break code navigation.
@@ -49,8 +71,18 @@ export function ensurePluginLspServers(opts = {}) {
     "language servers",
   );
 
+  const denied = [];
   for (const p of trusted) {
     const servers = p.manifest?.components?.lsp || [];
+    if (servers.length === 0) continue;
+    // Component-level capability gate: a plugin that declared a permissions
+    // block but did not declare the `process` capability its language servers
+    // need gets them refused here (mirrors the MCP collector's denial).
+    const denial = componentCapabilityDenial(p.manifest, ["process"]);
+    if (denial) {
+      denied.push({ name: p.name, reason: denial.reason });
+      continue;
+    }
     for (const s of servers) {
       try {
         registerLanguageServer({
@@ -66,6 +98,7 @@ export function ensurePluginLspServers(opts = {}) {
       }
     }
   }
+  warnLspCapabilityDeniedOnce(denied);
   return { registered };
 }
 
@@ -73,3 +106,8 @@ export function ensurePluginLspServers(opts = {}) {
 export function _resetPluginLspLoadState() {
   _loadedRoots.clear();
 }
+
+/** Test hook: reset the one-time capability-denied warning guard. */
+export function _resetLspWarnings() {
+  _capabilityDenied.clear();
+}

package/src/lib/plugin-runtime/mcp.js

@@ -17,9 +17,38 @@
 import fs from "fs";
 import { discoverPlugins } from "./scopes.js";
 import { partitionByTrust, warnUntrustedOnce } from "./trust.js";
+import { componentCapabilityDenial } from "./capabilities.js";
 
 export const _deps = { readFileSync: fs.readFileSync };
 
+// One-time stderr notice when a plugin's MCP server is refused at the COMPONENT
+// level because the plugin opted into the capability model but did not declare
+// the `mcp` capability its server needs. Distinct from the trust gate: these
+// plugins ARE trusted, but their MCP component is denied. (Network is enforced
+// separately at connection time by the egress/network policy, so a local stdio
+// server is not denied for lacking a `network` declaration.)
+const _capabilityDenied = new Set();
+function warnMcpCapabilityDeniedOnce(entries) {
+  if (!entries || entries.length === 0) return;
+  if (_capabilityDenied.has("mcp-capability")) return;
+  _capabilityDenied.add("mcp-capability");
+  const list = entries.map((e) => `${e.name} (${e.reason})`).join("; ");
+  try {
+    process.stderr.write(
+      `[plugins] refused MCP server(s) from plugin(s) that declared a permissions ` +
+        `block but did not declare the 'mcp' capability their server needs: ${list}\n` +
+        `          add 'mcp' to the plugin's permissions block to enable them.\n`,
+    );
+  } catch {
+    /* stderr notice is best-effort */
+  }
+}
+
+/** Test hook: reset the one-time capability-denied warning guard. */
+export function _resetMcpWarnings() {
+  _capabilityDenied.clear();
+}
+
 /** Accept `{ mcpServers: {...} }`, `{ servers: {...} }`, or a bare map. */
 function normalizeServerMap(parsed) {
   if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return {};
@@ -52,10 +81,20 @@ export function collectPluginMcpServers(opts = {}) {
   );
   const servers = {};
   const sources = [];
+  const denied = [];
   for (const p of trusted) {
     if (!p.manifest || p.manifest.ok !== true) continue;
     const m = p.manifest.components?.mcp;
     if (!m) continue;
+    // Component-level capability gate: a plugin that declared a permissions
+    // block but under-declared the `mcp` capability its server needs gets its
+    // MCP component refused here (mirrors the hooks/monitors/bin/lsp denial).
+    // Legacy plugins (no permissions block) are unrestricted and never denied.
+    const denial = componentCapabilityDenial(p.manifest, ["mcp"]);
+    if (denial) {
+      denied.push({ name: p.name, reason: denial.reason });
+      continue;
+    }
     let parsed = null;
     if (m.absPath) {
       try {
@@ -85,5 +124,6 @@ export function collectPluginMcpServers(opts = {}) {
     }
     if (added > 0 && m.absPath) sources.push(m.absPath);
   }
+  warnMcpCapabilityDeniedOnce(denied);
   return { servers, sources };
 }

package/src/lib/plugin-runtime/monitors.js

@@ -21,11 +21,38 @@
 import fs from "fs";
 import { discoverPlugins } from "./scopes.js";
 import { partitionByTrust, warnUntrustedOnce } from "./trust.js";
+import { componentCapabilityDenial } from "./capabilities.js";
 
 export const _deps = { readFileSync: fs.readFileSync };
 
 const VALID_MODES = new Set(["interval", "longRunning"]);
 
+// One-time stderr notice when a plugin's monitors are refused at the COMPONENT
+// level because the plugin opted into the capability model but did not declare
+// the `monitor` capability. Distinct from the trust gate: these plugins ARE
+// trusted, but their monitor component is denied.
+const _capabilityDenied = new Set();
+function warnMonitorCapabilityDeniedOnce(entries) {
+  if (!entries || entries.length === 0) return;
+  if (_capabilityDenied.has("monitor-capability")) return;
+  _capabilityDenied.add("monitor-capability");
+  const list = entries.map((e) => `${e.name} (${e.reason})`).join("; ");
+  try {
+    process.stderr.write(
+      `[plugins] refused monitor(s) from plugin(s) that declared a permissions ` +
+        `block but did not declare the 'monitor' capability: ${list}\n` +
+        `          add 'monitor' to the plugin's permissions block to enable them.\n`,
+    );
+  } catch {
+    /* stderr notice is best-effort */
+  }
+}
+
+/** Test hook: reset the one-time capability-denied warning guard. */
+export function _resetMonitorWarnings() {
+  _capabilityDenied.clear();
+}
+
 /** Normalize one raw monitor entry into a validated descriptor, or null. */
 function normalizeMonitor(plugin, raw) {
   if (!raw || typeof raw !== "object") return null;
@@ -76,10 +103,19 @@ export function collectPluginMonitors(opts = {}) {
     "monitors",
   );
   const out = [];
+  const denied = [];
   for (const p of trusted) {
     if (!p.manifest || p.manifest.ok !== true) continue;
     const m = p.manifest.components?.monitors;
     if (!m) continue;
+    // Component-level capability gate: a plugin that declared a permissions
+    // block but did not declare the `monitor` capability gets its monitors
+    // refused here (mirrors the MCP collector's denial).
+    const denial = componentCapabilityDenial(p.manifest, ["monitor"]);
+    if (denial) {
+      denied.push({ name: p.name, reason: denial.reason });
+      continue;
+    }
     let parsed;
     if (m.absPath) {
       try {
@@ -112,5 +148,6 @@ export function collectPluginMonitors(opts = {}) {
       if (desc) out.push(desc);
     }
   }
+  warnMonitorCapabilityDeniedOnce(denied);
   return out;
 }

package/src/lib/plugin-runtime/plugin-options.js

@@ -0,0 +1,151 @@
+/**
+ * Plugin OPTIONS resolution (Phase 3 gap: typed optionsSchema + sensitive
+ * project-scope gate).
+ *
+ * A plugin declares `optionsSchema` (typed config with `scope` and `sensitive`
+ * in [[capabilities.js]]). Users supply option VALUES at two scopes:
+ *   - USER scope   → user data dir `plugin-options.json` (may hold secrets)
+ *   - PROJECT scope → repo-local `.chainlesschain/plugin-options.json`
+ *     (checked-in-able → MUST NOT hold secrets)
+ *
+ * The security-critical rule (already enforced by `validateOptions`): a
+ * SENSITIVE option can never come from project config. `resolvePluginOptions`
+ * layers defaults < project (non-sensitive only) < user, DROPS + WARNS on any
+ * sensitive/user-only option that appears in project config, and returns the
+ * merged values with a redacted view for logging.
+ *
+ * Store IO is injected (`_deps`) so unit tests never touch the real dirs; the
+ * resolver itself is pure.
+ */
+
+import fs from "fs";
+import path from "path";
+import { getElectronUserDataDir } from "../paths.js";
+import {
+  optionDefaults,
+  validateOptions,
+  redactSensitiveOptions,
+} from "./capabilities.js";
+
+export const _deps = {
+  existsSync: fs.existsSync,
+  readFileSync: fs.readFileSync,
+  writeFileSync: fs.writeFileSync,
+  mkdirSync: fs.mkdirSync,
+  userStorePath: () =>
+    path.join(getElectronUserDataDir(), "plugin-options.json"),
+  projectStorePath: (cwd) =>
+    path.join(cwd || process.cwd(), ".chainlesschain", "plugin-options.json"),
+};
+
+function readJsonObject(p) {
+  try {
+    if (!_deps.existsSync(p)) return {};
+    const data = JSON.parse(_deps.readFileSync(p, "utf8"));
+    return data && typeof data === "object" && !Array.isArray(data) ? data : {};
+  } catch {
+    return {};
+  }
+}
+
+function writeJsonObject(p, obj) {
+  _deps.mkdirSync(path.dirname(p), { recursive: true });
+  _deps.writeFileSync(p, JSON.stringify(obj, null, 2), "utf8");
+}
+
+/** Load a plugin's option VALUES at the given scope (`user` | `project`). */
+export function loadPluginOptionValues(name, scope, { cwd } = {}) {
+  const p =
+    scope === "project" ? _deps.projectStorePath(cwd) : _deps.userStorePath();
+  const store = readJsonObject(p);
+  const v = store[name];
+  return v && typeof v === "object" && !Array.isArray(v) ? v : {};
+}
+
+/** Persist a plugin's option VALUES at a scope (replaces the plugin's entry). */
+export function setPluginOptionValues(name, values, scope, { cwd } = {}) {
+  const p =
+    scope === "project" ? _deps.projectStorePath(cwd) : _deps.userStorePath();
+  const store = readJsonObject(p);
+  store[name] = values && typeof values === "object" ? values : {};
+  writeJsonObject(p, store);
+  return { name, scope, path: p };
+}
+
+/** Provided keys of `values` (that exist in schema) accepted at `scope`. */
+function acceptedKeys(schema, values, scope) {
+  const res = validateOptions(schema, values, { scope });
+  const keys = new Set();
+  for (const key of Object.keys(values || {})) {
+    if (!Object.prototype.hasOwnProperty.call(schema, key)) continue; // unknown → ignored
+    // A provided key was accepted iff no error names it. validateOptions always
+    // quotes the offending key as `"<key>"`, so this is an exact match.
+    if (!res.errors.some((e) => e.includes(`"${key}"`))) keys.add(key);
+  }
+  return { res, keys };
+}
+
+/**
+ * PURE: resolve effective option values from defaults + project + user config.
+ *
+ * Precedence: defaults < project (non-sensitive, non-user-only) < user.
+ * A sensitive or user-only option present in project config is DROPPED and a
+ * warning is recorded — a checked-in project file can never inject a secret.
+ *
+ * @returns {{ options:object, redacted:object, warnings:string[],
+ *             sources:Record<string,'default'|'project'|'user'>,
+ *             droppedFromProject:string[] }}
+ */
+export function resolvePluginOptions(
+  schema,
+  { userValues, projectValues } = {},
+) {
+  const s = schema || {};
+  const options = optionDefaults(s);
+  const sources = {};
+  for (const key of Object.keys(options)) sources[key] = "default";
+
+  const warnings = [];
+  const droppedFromProject = [];
+
+  // Project layer first (lower precedence). validateOptions errors on sensitive/
+  // user-only keys at project scope — those are the drops we surface + refuse.
+  const proj = acceptedKeys(s, projectValues, "project");
+  for (const err of proj.res.errors) {
+    if (/sensitive|user-scoped/.test(err)) {
+      const m = err.match(/"([^"]+)"/);
+      if (m) droppedFromProject.push(m[1]);
+    }
+    warnings.push(`project: ${err}`);
+  }
+  for (const w of proj.res.warnings) warnings.push(`project: ${w}`);
+  for (const key of proj.keys) {
+    options[key] = proj.res.normalized[key];
+    sources[key] = "project";
+  }
+
+  // User layer on top (highest precedence; may carry secrets).
+  const user = acceptedKeys(s, userValues, "user");
+  for (const err of user.res.errors) warnings.push(`user: ${err}`);
+  for (const w of user.res.warnings) warnings.push(`user: ${w}`);
+  for (const key of user.keys) {
+    options[key] = user.res.normalized[key];
+    sources[key] = "user";
+  }
+
+  return {
+    options,
+    redacted: redactSensitiveOptions(s, options),
+    warnings,
+    sources,
+    droppedFromProject: [...new Set(droppedFromProject)],
+  };
+}
+
+/** Load both scopes' values from disk and resolve against a schema. */
+export function getResolvedPluginOptions(name, schema, { cwd } = {}) {
+  return resolvePluginOptions(schema, {
+    userValues: loadPluginOptionValues(name, "user", { cwd }),
+    projectValues: loadPluginOptionValues(name, "project", { cwd }),
+  });
+}

package/src/lib/pr-automation-policy.js

@@ -0,0 +1,224 @@
+/**
+ * PR/CI automation policy — the fail-closed decision engine behind "P1-4 PR/CI
+ * Monitor、Auto-fix 与受控合并" of CLAUDE_CODE_IDE_INCREMENTAL_GAP_ANALYSIS_2026-
+ * 07-13.md.
+ *
+ * Letting an agent iterate on CI failures and merge PRs is useful and dangerous.
+ * The gap doc pins the guardrails precisely: each failing check may be auto-
+ * fixed at most N times within a token/time budget; a fix must read only the
+ * CURRENT commit's logs (never chase a stale failure); auto-merge is OFF by
+ * default and, when on, requires branch protection, all required checks, an
+ * approving review and zero pending approvals — and never pushes a protected
+ * branch directly or bypasses protection.
+ *
+ * This module is those decisions as pure predicates. It holds no state and does
+ * no I/O — a caller feeds the observed PR/CI signals and gets an allow/deny with
+ * a named reason. Everything defaults to DENY: an unknown or missing signal
+ * blocks the automation rather than assuming it is safe.
+ */
+
+/** Canonical CI check states. */
+export const CHECK_STATE = Object.freeze({
+  PASSED: "passed",
+  FAILED: "failed",
+  PENDING: "pending",
+  NEUTRAL: "neutral",
+  ERROR: "error",
+});
+
+const CHECK_ALIASES = new Map([
+  ["passed", CHECK_STATE.PASSED],
+  ["pass", CHECK_STATE.PASSED],
+  ["success", CHECK_STATE.PASSED],
+  ["succeeded", CHECK_STATE.PASSED],
+  ["green", CHECK_STATE.PASSED],
+  ["failed", CHECK_STATE.FAILED],
+  ["fail", CHECK_STATE.FAILED],
+  ["failure", CHECK_STATE.FAILED],
+  ["red", CHECK_STATE.FAILED],
+  ["pending", CHECK_STATE.PENDING],
+  ["queued", CHECK_STATE.PENDING],
+  ["in_progress", CHECK_STATE.PENDING],
+  ["running", CHECK_STATE.PENDING],
+  ["neutral", CHECK_STATE.NEUTRAL],
+  ["skipped", CHECK_STATE.NEUTRAL],
+  ["cancelled", CHECK_STATE.NEUTRAL],
+  ["canceled", CHECK_STATE.NEUTRAL],
+  ["error", CHECK_STATE.ERROR],
+  ["timed_out", CHECK_STATE.ERROR],
+  ["action_required", CHECK_STATE.ERROR],
+]);
+
+/** Normalize any provider's check conclusion/status to a canonical state. */
+export function normalizeCheckState(value) {
+  if (typeof value !== "string") return null;
+  return CHECK_ALIASES.get(value.trim().toLowerCase()) || null;
+}
+
+/** A failing state that auto-fix could act on. */
+function isFailing(state) {
+  return state === CHECK_STATE.FAILED || state === CHECK_STATE.ERROR;
+}
+
+/**
+ * Summarize a set of checks. `allPassed` is true only when there is at least one
+ * check and every one is passed or neutral (a bare PR with no checks is NOT
+ * "all passed" — required checks must actually exist and run).
+ *
+ * @param {Array<{name?:string, state?:string, conclusion?:string, status?:string}>} checks
+ */
+export function summarizeChecks(checks = []) {
+  const list = Array.isArray(checks) ? checks : [];
+  let passed = 0;
+  let failed = 0;
+  let pending = 0;
+  const byName = new Map();
+  for (const c of list) {
+    const state =
+      normalizeCheckState(c?.state) ??
+      normalizeCheckState(c?.conclusion) ??
+      normalizeCheckState(c?.status);
+    if (c?.name != null) byName.set(String(c.name), state);
+    if (state === CHECK_STATE.PASSED || state === CHECK_STATE.NEUTRAL) passed++;
+    else if (isFailing(state)) failed++;
+    else pending++; // pending / unknown → not yet decided
+  }
+  return {
+    total: list.length,
+    passed,
+    failed,
+    pending,
+    anyFailed: failed > 0,
+    allPassed: list.length > 0 && failed === 0 && pending === 0,
+    byName,
+  };
+}
+
+function budgetExhausted(budget) {
+  if (!budget || typeof budget !== "object") return false;
+  const over = (spent, cap) =>
+    cap != null && Number.isFinite(Number(cap)) && Number(spent) >= Number(cap);
+  return (
+    over(budget.tokensSpent, budget.tokenBudget) ||
+    over(budget.timeSpentMs, budget.timeBudgetMs)
+  );
+}
+
+/**
+ * Decide whether an agent may auto-fix ONE failing check right now. Fail-closed:
+ * anything unproven denies.
+ *
+ * @param {object} params
+ * @param {object} params.check           {name, state|conclusion, logCommitSha}
+ * @param {string} params.headCommitSha   the PR head the fix would target
+ * @param {number} params.iteration       fixes already attempted for this check
+ * @param {number} params.maxIterations   cap (default 3)
+ * @param {object} [params.budget]        {tokensSpent, tokenBudget, timeSpentMs, timeBudgetMs}
+ * @returns {{allow:boolean, reason:string}}
+ */
+export function autoFixDecision(params = {}) {
+  const check = params.check || {};
+  const state =
+    normalizeCheckState(check.state) ?? normalizeCheckState(check.conclusion);
+  if (!isFailing(state)) {
+    return { allow: false, reason: "check-not-failing" };
+  }
+
+  const maxIterations = Number.isFinite(Number(params.maxIterations))
+    ? Number(params.maxIterations)
+    : 3;
+  const iteration = Number(params.iteration) || 0;
+  if (iteration >= maxIterations) {
+    return { allow: false, reason: "max-iterations-reached" };
+  }
+
+  // Only fix the CURRENT failure: the log we would read must belong to the head
+  // commit. A missing/older log sha means we cannot prove freshness → deny.
+  const logSha = check.logCommitSha == null ? "" : String(check.logCommitSha);
+  const headSha =
+    params.headCommitSha == null ? "" : String(params.headCommitSha);
+  if (!logSha || !headSha) {
+    return { allow: false, reason: "commit-sha-unverifiable" };
+  }
+  if (logSha !== headSha) {
+    return { allow: false, reason: "stale-failure-log" };
+  }
+
+  if (budgetExhausted(params.budget)) {
+    return { allow: false, reason: "budget-exhausted" };
+  }
+
+  return { allow: true, reason: "ok" };
+}
+
+/**
+ * Decide whether a PR may be auto-merged. Fail-closed and exhaustive: every
+ * unmet requirement is collected, and merge is allowed ONLY when the list is
+ * empty. Auto-merge is off unless `enabled === true`.
+ *
+ * @param {object} params
+ * @param {boolean} params.enabled                  auto-merge explicitly turned on
+ * @param {boolean} params.hasOpenPr                a real PR exists (no direct-to-branch)
+ * @param {boolean} params.branchProtectionSatisfied
+ * @param {boolean} params.reviewApproved
+ * @param {number}  params.pendingApprovals         permission approvals still waiting
+ * @param {string[]} params.requiredChecks          names that must be present AND passed
+ * @param {Array}   params.checks                   observed checks (summarizeChecks input)
+ * @param {string}  [params.targetBranch]
+ * @returns {{allow:boolean, reason:string, unmet:string[]}}
+ */
+export function autoMergeDecision(params = {}) {
+  const unmet = [];
+
+  if (params.enabled !== true) unmet.push("auto-merge-disabled");
+  if (params.hasOpenPr !== true) unmet.push("no-open-pr");
+  if (params.branchProtectionSatisfied !== true) {
+    unmet.push("branch-protection-unsatisfied");
+  }
+  if (params.reviewApproved !== true) unmet.push("review-not-approved");
+  if (Number(params.pendingApprovals) > 0) unmet.push("pending-approvals");
+
+  const summary = summarizeChecks(params.checks);
+  if (summary.anyFailed) unmet.push("checks-failing");
+  if (summary.pending > 0) unmet.push("checks-pending");
+
+  // Every REQUIRED check must be present and passed — a required check that
+  // never ran is a block, not a pass.
+  const required = Array.isArray(params.requiredChecks)
+    ? params.requiredChecks
+    : [];
+  for (const name of required) {
+    const state = summary.byName.get(String(name));
+    if (state !== CHECK_STATE.PASSED && state !== CHECK_STATE.NEUTRAL) {
+      unmet.push(`required-check-missing:${name}`);
+    }
+  }
+
+  return {
+    allow: unmet.length === 0,
+    reason: unmet.length === 0 ? "ok" : unmet[0],
+    unmet,
+  };
+}
+
+/**
+ * A compact, log-safe status line for the PR status bar (P1-4 "Session 顶部提供
+ * PR 状态条"). Carries only coordinates + a checks tally, never a token.
+ *
+ * @param {object} params {branch, prNumber, checks, reviewApproved, mergeable}
+ * @returns {string}
+ */
+export function describePrStatusBar(params = {}) {
+  const parts = [];
+  if (params.branch) parts.push(`branch:${params.branch}`);
+  if (params.prNumber != null) parts.push(`PR#${params.prNumber}`);
+  const s = summarizeChecks(params.checks);
+  parts.push(`checks:${s.passed}/${s.total}${s.anyFailed ? " ✗" : ""}`);
+  parts.push(
+    `review:${params.reviewApproved === true ? "approved" : "pending"}`,
+  );
+  if (params.mergeable != null) {
+    parts.push(`merge:${params.mergeable ? "ready" : "blocked"}`);
+  }
+  return parts.join(" · ");
+}