chainlesschain 0.162.160 → 0.162.162

package/src/lib/capability-negotiation.js

@@ -0,0 +1,212 @@
+/**
+ * Bidirectional capability negotiation with N / N-1 downgrade for Agent
+ * Protocol (agent-sdk docs/PROTOCOL.md §1.3).
+ *
+ * The CLI advertises what it can speak one-directionally (buildAgentCapabilities
+ * → `cc agent --capabilities`, and the `system/init` line's protocol_version).
+ * That is not negotiation: a client (VS Code / JetBrains panel) had no way to
+ * announce what IT understands, and the CLI had no rule to pick a common level
+ * or step DOWN when the two disagree. When the protocol later grows a v2 line
+ * shape, a v1-only client would silently mis-parse it.
+ *
+ * This module is the missing algorithm. A client MAY send a `hello` as its
+ * first stream-json input line:
+ *   {"type":"hello","protocol_version":2,"min_protocol_version":1,
+ *    "features":["event_seq","trace_id"]}
+ * The CLI negotiates it against its own offer and echoes the agreed level as a
+ * `system/negotiated` line, then honors it for the rest of the run.
+ *
+ * Rules:
+ *   - agreedVersion = min(server.max, client.max)  — never above what either
+ *     can parse.
+ *   - Incompatible when agreedVersion < max(server.min, client.min): the two
+ *     version ranges don't overlap. ok:false — the caller keeps a safe baseline
+ *     or errors out; it never speaks a version the peer can't read.
+ *   - effective features = the server-offered features the client also accepts
+ *     (intersection), minus any whose minimum protocol version is above the
+ *     agreed version (an N-only field is dropped for an N-1 session).
+ *   - No client offer at all → legacy client that predates negotiation. The
+ *     additive fields are defined "consumers MUST tolerate absence AND
+ *     presence" (docs/PROTOCOL.md §1.2.1), so we keep FULL behavior unchanged
+ *     (byte-for-byte) and mark clientAware:false. Negotiation only ever
+ *     RESTRICTS when a client explicitly narrows the set.
+ *
+ * Pure: no fs / process / clock. The same algorithm is mirrored in the Java
+ * twin (jetbrains-plugin CapabilityNegotiation.java); both read the shared
+ * fixture __tests__/fixtures/capability-negotiation-cases.json.
+ */
+
+/** The current protocol version the CLI speaks (mirror of PROTOCOL_VERSION). */
+export const PROTOCOL_VERSION = 1;
+
+/**
+ * The oldest protocol version the CLI can still speak end-to-end (the N-1 in
+ * "N / N-1"). At v1 there is no older line shape, so min === current; once v2
+ * ships this drops to 1 so a v1-only client negotiates a v1 session.
+ */
+export const PROTOCOL_MIN_VERSION = 1;
+
+/**
+ * The wire-protocol features subject to negotiation — the additive per-line
+ * fields a client may or may not understand. Runtime capabilities (bare,
+ * worktree, mcp, …) are NOT negotiated: they change what the CLI can do, not
+ * the shape of a line the client must parse.
+ */
+export const PROTOCOL_FEATURES = ["event_seq", "tool_use_id", "trace_id"];
+
+/**
+ * Minimum protocol version a feature requires. Empty today (every current
+ * feature is a v1 additive field). When a v2 field lands, add it here so an
+ * N-1 (v1) session drops it automatically.
+ * @type {Record<string, number>}
+ */
+export const FEATURE_MIN_VERSION = {};
+
+function intOr(value, fallback) {
+  const n = Number(value);
+  return Number.isInteger(n) && n > 0 ? n : fallback;
+}
+
+/**
+ * Coerce a features declaration into a sorted, de-duplicated array of keys.
+ * Accepts an array of strings, or an object whose truthy keys are the features
+ * (the nested manifest shape). Anything else → [].
+ * @returns {string[]}
+ */
+export function normalizeFeatureList(input) {
+  let keys;
+  if (Array.isArray(input)) {
+    keys = input.filter((k) => typeof k === "string" && k);
+  } else if (input && typeof input === "object") {
+    keys = Object.keys(input).filter((k) => input[k]);
+  } else {
+    return [];
+  }
+  return [...new Set(keys)].sort();
+}
+
+/**
+ * Extract the server's negotiation offer from a `cc agent --capabilities`
+ * manifest (buildAgentCapabilities output). Only the negotiable wire features
+ * the manifest advertises truthy are offered.
+ * @param {object} manifest
+ * @returns {{protocolVersion:number, minProtocolVersion:number, features:string[]}}
+ */
+export function buildServerOffer(manifest = {}) {
+  const protocolVersion = intOr(manifest.protocol_version, PROTOCOL_VERSION);
+  const minProtocolVersion = intOr(
+    manifest.min_protocol_version,
+    Math.min(PROTOCOL_MIN_VERSION, protocolVersion),
+  );
+  const advertised = normalizeFeatureList(manifest.features);
+  const features = PROTOCOL_FEATURES.filter((f) => advertised.includes(f));
+  return { protocolVersion, minProtocolVersion, features };
+}
+
+/**
+ * Negotiate the effective protocol version + feature set between a server offer
+ * and a client offer.
+ *
+ * @param {{protocolVersion:number, minProtocolVersion?:number, features:string[]}} server
+ * @param {null|{protocolVersion?:number, minProtocolVersion?:number, features?:string[]}} clientOffer
+ * @param {object} [opts]
+ * @param {Record<string,number>} [opts.featureMinVersion=FEATURE_MIN_VERSION]
+ * @returns {{
+ *   ok:boolean, agreedVersion:(number|null), features:string[],
+ *   downgraded:boolean, disabledFeatures:string[], clientAware:boolean,
+ *   reason:(string|null)
+ * }}
+ */
+export function negotiateProtocol(server = {}, clientOffer = null, opts = {}) {
+  const featureMinVersion = opts.featureMinVersion || FEATURE_MIN_VERSION;
+  const serverMax = intOr(server.protocolVersion, PROTOCOL_VERSION);
+  const serverMin = intOr(server.minProtocolVersion, serverMax);
+  const serverFeatures = normalizeFeatureList(server.features);
+
+  const versionOk = (f, v) => (featureMinVersion[f] || 0) <= v;
+
+  // No client offer → legacy peer. Keep full behavior (only version-gate the
+  // server's own features against its own max), byte-for-byte unchanged.
+  if (clientOffer == null) {
+    return {
+      ok: true,
+      agreedVersion: serverMax,
+      features: serverFeatures.filter((f) => versionOk(f, serverMax)),
+      downgraded: false,
+      disabledFeatures: [],
+      clientAware: false,
+      reason: null,
+    };
+  }
+
+  const clientMax = intOr(clientOffer.protocolVersion, serverMax);
+  const clientMin = intOr(clientOffer.minProtocolVersion, clientMax);
+  const agreedVersion = Math.min(serverMax, clientMax);
+  const floor = Math.max(serverMin, clientMin);
+
+  if (agreedVersion < floor) {
+    return {
+      ok: false,
+      agreedVersion: null,
+      features: [],
+      downgraded: true,
+      disabledFeatures: [...serverFeatures].sort(),
+      clientAware: true,
+      reason:
+        `no common protocol version (server ${serverMin}-${serverMax}, ` +
+        `client ${clientMin}-${clientMax})`,
+    };
+  }
+
+  // A client that omits `features` accepts whatever the agreed version offers;
+  // a client that sends the array narrows to the intersection.
+  const clientFeatures =
+    clientOffer.features === undefined
+      ? null
+      : new Set(normalizeFeatureList(clientOffer.features));
+
+  const enabled = [];
+  const disabled = [];
+  for (const f of serverFeatures) {
+    const okVersion = versionOk(f, agreedVersion);
+    const okClient = clientFeatures == null || clientFeatures.has(f);
+    if (okVersion && okClient) enabled.push(f);
+    else disabled.push(f);
+  }
+
+  return {
+    ok: true,
+    agreedVersion,
+    features: enabled.sort(),
+    downgraded: agreedVersion < serverMax || disabled.length > 0,
+    disabledFeatures: disabled.sort(),
+    clientAware: true,
+    reason: null,
+  };
+}
+
+/** Feature key → the stream line field it gates. */
+const FEATURE_TO_FIELD = {
+  event_seq: "seq",
+  trace_id: "trace_id",
+  tool_use_id: "tool_use_id",
+};
+
+/**
+ * Fold a negotiation result into a live field-gate the emitter reads per line:
+ * a field stays stamped only if its feature survived negotiation. On an
+ * incompatible (ok:false) result nothing is changed (the caller keeps its safe
+ * baseline). Mutates `gate` in place and returns it.
+ *
+ * @param {{features:string[], ok:boolean}} result
+ * @param {{seq?:boolean, trace_id?:boolean, tool_use_id?:boolean}} gate
+ */
+export function applyNegotiationToGate(result, gate = {}) {
+  if (!result || result.ok === false) return gate;
+  const enabled = new Set(result.features || []);
+  for (const feature of PROTOCOL_FEATURES) {
+    const field = FEATURE_TO_FIELD[feature];
+    if (field) gate[field] = enabled.has(feature);
+  }
+  return gate;
+}

package/src/lib/credential-guard.js

@@ -213,6 +213,17 @@ const PRINT_COMMANDS = new Set([
 const SECRET_VAR_RE =
   /(?:^|_)(KEY|KEYS|TOKEN|SECRET|SECRETS|PASSWORD|PASSWD|PASSPHRASE|CREDENTIAL|CREDENTIALS|PRIVATE|APIKEY|ACCESSKEY)(?:_|$)/i;
 
+/**
+ * True when an environment-variable NAME looks like it holds a secret
+ * (ANTHROPIC_API_KEY, GITHUB_TOKEN, DB_PASSWORD, …). Shared single source of
+ * truth so the credential READ guard and the credential PROXY
+ * ([[credential-proxy.js]] — which keeps secrets out of subprocess envs)
+ * classify identically. `MONKEY`/`KEYBOARD`/`TOKENIZER` do NOT match.
+ */
+export function isSecretEnvName(name) {
+  return typeof name === "string" && SECRET_VAR_RE.test(name);
+}
+
 // Ways a secret var is referenced inside a shell segment.
 const SECRET_REF_PATTERNS = [
   /\$env:([A-Za-z_][A-Za-z0-9_]*)/gi, // PowerShell  $env:NAME

package/src/lib/credential-proxy.js

@@ -0,0 +1,182 @@
+/**
+ * Credential proxy — keep the agent's real, long-lived credentials out of the
+ * environment that run_shell / run_code / hook / plugin subprocesses inherit
+ * (P0 §"跨平台沙箱与凭据代理").
+ *
+ * By default a spawned command inherits the WHOLE parent environment — including
+ * the agent's ANTHROPIC_API_KEY, cloud keys and tokens. A compromised or
+ * careless command can then echo, log, or exfiltrate them. This module replaces
+ * credential-named vars with an opaque SENTINEL before the child starts and
+ * keeps the real values in a parent-held vault, to be injected only for an
+ * approved host (via the egress proxy) — never handed to the child wholesale.
+ * The audit log only ever sees redacted values, never a restored secret.
+ *
+ * Pairs with credential-guard.js: that guard stops the AGENT reading secrets
+ * into model context; this stops the SUBPROCESS inheriting them. Both classify
+ * secret var names through the same `isSecretEnvName` so they never drift.
+ *
+ * Opt-in for now (`CC_CREDENTIAL_PROXY=1` or `config.credentialProxy.enabled`)
+ * so existing workflows that legitimately read a token from env keep working;
+ * default-on is the eventual goal once per-host injection is wired everywhere.
+ * Pure + dependency-light so every spawn seam can share it.
+ */
+
+import { isSecretEnvName } from "./credential-guard.js";
+
+/** Opaque replacement a masked credential var carries into the child env. */
+export const CREDENTIAL_SENTINEL_PREFIX = "cc-cred-redacted:";
+
+/**
+ * Well-known credential vars whose NAME does not obviously match the generic
+ * KEY/TOKEN/SECRET/PASSWORD pattern. Most real ones already match; this is a
+ * small safety net, extendable per-project via `deny`.
+ */
+const EXTRA_CREDENTIAL_NAMES = new Set([
+  "AWS_SESSION_TOKEN", // matches TOKEN, kept explicit
+  "GOOGLE_APPLICATION_CREDENTIALS", // path to a key file
+  "CLOUDSDK_AUTH_ACCESS_TOKEN",
+  "DIGITALOCEAN_ACCESS_TOKEN",
+]);
+
+function toSet(value) {
+  if (value instanceof Set) return value;
+  return new Set(Array.isArray(value) ? value : value ? [value] : []);
+}
+
+/**
+ * Classify an env var NAME as credential-bearing. `opts.allow` forces
+ * pass-through (never masked); `opts.deny` forces masking; otherwise the shared
+ * secret-name classifier + the curated extra set decide.
+ */
+export function isCredentialEnvName(name, opts = {}) {
+  if (typeof name !== "string" || !name) return false;
+  if (toSet(opts.allow).has(name)) return false;
+  if (toSet(opts.deny).has(name)) return true;
+  return isSecretEnvName(name) || EXTRA_CREDENTIAL_NAMES.has(name);
+}
+
+/** The sentinel a child sees in place of a credential's real value. */
+export function makeSentinel(name) {
+  return CREDENTIAL_SENTINEL_PREFIX + String(name ?? "");
+}
+
+/** True when a value is a proxy sentinel (carries no secret). */
+export function isSentinel(value) {
+  return (
+    typeof value === "string" && value.startsWith(CREDENTIAL_SENTINEL_PREFIX)
+  );
+}
+
+/**
+ * Mask credential-named vars in `env`. Returns a NEW object (never mutates the
+ * input):
+ *   - `env`    — credential vars replaced with a sentinel (mode "mask", the
+ *                default) or removed entirely (mode "deny"); everything else
+ *                copied through verbatim.
+ *   - `masked` — sorted list of the var names that were masked/removed.
+ *   - `vault`  — Map<name, realValue> the PARENT keeps for approved injection;
+ *                the child never receives it.
+ * Values that are already sentinels, null, or undefined are left as-is (a
+ * sentinel is never double-masked; an absent var is not invented).
+ */
+export function maskCredentialEnv(env = {}, opts = {}) {
+  const mode = opts.mode === "deny" ? "deny" : "mask";
+  const out = {};
+  const masked = [];
+  const vault = new Map();
+  for (const [name, value] of Object.entries(env || {})) {
+    if (
+      value != null &&
+      !isSentinel(value) &&
+      isCredentialEnvName(name, opts)
+    ) {
+      masked.push(name);
+      vault.set(name, String(value));
+      if (mode === "mask") out[name] = makeSentinel(name);
+      // mode "deny": drop the var so the child does not even see a sentinel
+    } else {
+      out[name] = value;
+    }
+  }
+  masked.sort();
+  return { env: out, masked, vault };
+}
+
+/** Replace a secret value with a fixed marker — never the real value. */
+export function redactSecretValue(value) {
+  if (value == null) return value;
+  return String(value) ? "***" : "";
+}
+
+/**
+ * A log-safe projection of an env for the audit trail: credential values →
+ * "***", sentinels kept verbatim (they hold no secret), everything else
+ * untouched. NEVER emits a restored/real credential value.
+ */
+export function redactEnvForAudit(env = {}, opts = {}) {
+  const out = {};
+  for (const [name, value] of Object.entries(env || {})) {
+    if (isSentinel(value)) out[name] = value;
+    else if (isCredentialEnvName(name, opts))
+      out[name] = redactSecretValue(value);
+    else out[name] = value;
+  }
+  return out;
+}
+
+/**
+ * Resolve the real value for a masked credential — but ONLY when the target
+ * host is on the approved list. The whole point of the proxy is that the child
+ * never gets the raw secret; the parent injects it just-in-time for an approved
+ * destination (e.g. the egress proxy adding Authorization for an allowed API
+ * host). Returns null (fail closed) for an unknown var, an empty host, or a
+ * non-approved host.
+ */
+export function resolveApprovedInjection(vault, name, opts = {}) {
+  if (!(vault instanceof Map) || !vault.has(name)) return null;
+  const host = String(opts.host || "").toLowerCase();
+  if (!host) return null;
+  const approved = (opts.approvedHosts || []).map((h) =>
+    String(h || "").toLowerCase(),
+  );
+  return approved.includes(host) ? vault.get(name) : null;
+}
+
+/**
+ * Resolve whether the credential proxy is enabled. Env var wins so a spawn
+ * seam without config access can still honor it; otherwise the config flag.
+ */
+export function credentialProxyEnabled(config = {}, env = process.env) {
+  const raw = env && env.CC_CREDENTIAL_PROXY;
+  if (raw != null) {
+    const v = String(raw).toLowerCase();
+    return v === "1" || v === "true" || v === "on" || v === "yes";
+  }
+  return config?.credentialProxy?.enabled === true;
+}
+
+/**
+ * Apply the credential proxy to a child env when enabled; otherwise return the
+ * env UNCHANGED (same reference — the default path stays byte-identical). The
+ * returned `vault` lets the caller inject approved creds later.
+ *
+ * @returns {{env:object, masked:string[], vault:Map, enabled:boolean}}
+ */
+export function applyCredentialProxy(env, options = {}) {
+  const procEnv = options.env || process.env;
+  const config = options.config || {};
+  if (!credentialProxyEnabled(config, procEnv)) {
+    return { env, masked: [], vault: new Map(), enabled: false };
+  }
+  const allow = new Set([
+    ...toSet(options.allow),
+    ...(config?.credentialProxy?.allow || []),
+  ]);
+  const deny = new Set([
+    ...toSet(options.deny),
+    ...(config?.credentialProxy?.deny || []),
+  ]);
+  const mode = options.mode || config?.credentialProxy?.mode || "mask";
+  const result = maskCredentialEnv(env, { allow, deny, mode });
+  return { ...result, enabled: true };
+}

package/src/lib/docs-drift.js

@@ -0,0 +1,166 @@
+/**
+ * Auto-generated CLI reference + doc-drift detection (P2 "文档").
+ *
+ * The gap: commands, agent tools, flags, exit codes, and protocol fields are
+ * documented by hand and silently drift from the code. `command-manifest.json`
+ * (regenerated + CI-guarded) and the `AGENT_TOOLS` registry are the authoritative
+ * data sources; nothing turns them into a reference doc or checks a hand-written
+ * doc against them.
+ *
+ * This is the PURE core: build a canonical reference from the manifest + tool
+ * list, render it, and diff a documentation surface against the authoritative
+ * sets to catch drift in BOTH directions (documented-but-gone / present-but-
+ * undocumented). No I/O — the caller reads the manifest, tool names, and doc text.
+ */
+
+/** Normalize the command-manifest.json commands into a stable reference list. */
+export function extractCommands(manifest = {}) {
+  const commands = Array.isArray(manifest.commands) ? manifest.commands : [];
+  return commands
+    .map((c) => ({
+      name: String(c?.name || "").trim(),
+      aliases: Array.isArray(c?.aliases)
+        ? c.aliases.map((a) => String(a).trim()).filter(Boolean)
+        : [],
+      summary: String(c?.summary || "").trim(),
+    }))
+    .filter((c) => c.name)
+    .sort((a, b) => a.name.localeCompare(b.name));
+}
+
+/**
+ * Normalize the AGENT_TOOLS registry into a sorted, de-duped name list. Accepts
+ * plain strings, `{ name }` contracts, and OpenAI-style `{ function: { name } }`
+ * function-tool definitions.
+ */
+export function extractToolNames(tools = []) {
+  const names = (Array.isArray(tools) ? tools : [])
+    .map((t) => {
+      if (typeof t === "string") return t.trim();
+      const n = t?.name ?? t?.function?.name;
+      return String(n || "").trim();
+    })
+    .filter(Boolean);
+  return [...new Set(names)].sort();
+}
+
+/** Every command token a user can invoke: primary names + aliases. */
+export function commandTokens(commands) {
+  const set = new Set();
+  for (const c of commands) {
+    set.add(c.name);
+    for (const a of c.aliases) set.add(a);
+  }
+  return set;
+}
+
+/**
+ * Build the canonical reference object from the authoritative sources. This is
+ * the data a generator serializes; `renderReferenceMarkdown` renders it.
+ */
+export function buildCliReference({ manifest = {}, tools = [] } = {}) {
+  const commands = extractCommands(manifest);
+  const toolNames = extractToolNames(tools);
+  return {
+    commandCount: commands.length,
+    toolCount: toolNames.length,
+    commands,
+    tools: toolNames,
+  };
+}
+
+/** Deterministic markdown render of the reference (stable output for diffing). */
+export function renderReferenceMarkdown(reference) {
+  const lines = [];
+  lines.push("# CLI Reference (generated)");
+  lines.push("");
+  lines.push(
+    "<!-- Generated from command-manifest.json + AGENT_TOOLS. Do not edit by hand. -->",
+  );
+  lines.push("");
+  lines.push(`## Commands (${reference.commandCount})`);
+  lines.push("");
+  for (const c of reference.commands) {
+    const alias = c.aliases.length ? ` (aliases: ${c.aliases.join(", ")})` : "";
+    lines.push(`- \`${c.name}\`${alias}${c.summary ? ` — ${c.summary}` : ""}`);
+  }
+  lines.push("");
+  lines.push(`## Agent tools (${reference.toolCount})`);
+  lines.push("");
+  for (const name of reference.tools) lines.push(`- \`${name}\``);
+  lines.push("");
+  return lines.join("\n");
+}
+
+/**
+ * Which authoritative command/tool tokens appear as literal `cc <token>` /
+ * backticked `<token>` mentions in the doc text. We look for word-boundary
+ * mentions; a token is "documented" if it appears anywhere in the doc.
+ */
+function isMentioned(doc, token) {
+  if (!token) return false;
+  const esc = token.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  return new RegExp(`(^|[^\\w-])${esc}([^\\w-]|$)`).test(doc);
+}
+
+/**
+ * Diff a documentation surface against the authoritative sets. Reports drift both
+ * ways so neither a NEW undocumented command nor a REMOVED-but-still-documented
+ * one slips through.
+ *
+ * @param {object} args
+ *   manifest — command-manifest.json object
+ *   tools    — AGENT_TOOLS array
+ *   doc      — the documentation text to check
+ *   knownTokens — optional extra tokens to treat as authoritative (e.g. flags,
+ *                 exit codes, protocol fields) to catch their drift too
+ * @returns {{ undocumentedCommands, undocumentedTools, staleCommandMentions,
+ *             ok, counts }}
+ */
+export function detectDocDrift({
+  manifest = {},
+  tools = [],
+  doc = "",
+  knownTokens = [],
+} = {}) {
+  const commands = extractCommands(manifest);
+  const toolNames = extractToolNames(tools);
+  const text = String(doc || "");
+
+  const undocumentedCommands = commands
+    .filter((c) => !isMentioned(text, c.name))
+    .map((c) => c.name);
+  const undocumentedTools = toolNames.filter((n) => !isMentioned(text, n));
+
+  // Tokens the doc claims as commands (in a `cc <token>` construct) that are not
+  // in the manifest → stale references to removed/renamed commands.
+  const known = commandTokens(commands);
+  for (const t of knownTokens) known.add(String(t));
+  const staleCommandMentions = [];
+  const seen = new Set();
+  const ccRe = /\bcc\s+([a-z][a-z0-9-]*)\b/g;
+  let m;
+  while ((m = ccRe.exec(text)) !== null) {
+    const tok = m[1];
+    if (!known.has(tok) && !seen.has(tok)) {
+      seen.add(tok);
+      staleCommandMentions.push(tok);
+    }
+  }
+
+  const counts = {
+    undocumentedCommands: undocumentedCommands.length,
+    undocumentedTools: undocumentedTools.length,
+    staleCommandMentions: staleCommandMentions.length,
+  };
+  return {
+    undocumentedCommands,
+    undocumentedTools,
+    staleCommandMentions,
+    counts,
+    ok:
+      counts.undocumentedCommands === 0 &&
+      counts.undocumentedTools === 0 &&
+      counts.staleCommandMentions === 0,
+  };
+}

package/src/lib/doctor-checkup.js

@@ -26,6 +26,7 @@ import {
 import { execSync } from "node:child_process";
 import { join, basename } from "node:path";
 import { getHomeDir, getConfigPath } from "./paths.js";
+import { checkAgenda, checkInstructionFiles } from "./runtime-checkup.js";
 
 export const CHECK_LEVELS = Object.freeze({
   OK: "ok",
@@ -540,6 +541,80 @@ async function worktreeSection(opts, deps) {
   return { id: "worktrees", title: "Git worktrees", checks };
 }
 
+// ── runtime checkup: agenda expiry + verbose instruction files ──────────────
+// Only the gaps the OTHER sections don't already cover. Stale sessions,
+// worktrees, orphan processes and lost background agents are handled by
+// transcriptSection / worktreeSection / backgroundSection — surfacing them here
+// too would double-report, so this section deliberately covers just the agenda
+// schedule store and the instruction files (cc.md / AGENTS.md / CLAUDE.md).
+const SEVERITY_TO_LEVEL = {
+  error: CHECK_LEVELS.ERR,
+  warn: CHECK_LEVELS.WARN,
+  info: CHECK_LEVELS.INFO,
+};
+
+async function runtimeSection(opts, deps) {
+  const checks = [];
+  const now = deps.now();
+
+  // Agenda schedule store — overdue/never-fired wakeups, retirable leftovers.
+  try {
+    const { AgentScheduleStore } = await import("./agent-schedule-store.js");
+    const store = new AgentScheduleStore();
+    const entries = store.list().map((e) => ({
+      id: e.id,
+      dueAt: e.kind === "wakeup" ? e.dueAt : e.nextAt,
+      recurring: e.kind !== "wakeup",
+    }));
+    for (const f of checkAgenda(entries, now)) {
+      checks.push(
+        check(
+          f.id,
+          `agenda ${f.ref}`,
+          SEVERITY_TO_LEVEL[f.severity] || CHECK_LEVELS.INFO,
+          `${f.message} — ${f.remediation}`,
+        ),
+      );
+    }
+  } catch (err) {
+    checks.push(failedCheck("agenda", "agenda schedule store", err));
+  }
+
+  // Instruction files — flag verbose ones (byte size only; a derivability
+  // heuristic would need code analysis and isn't computed here).
+  try {
+    const cwd = opts.cwd || process.cwd();
+    const files = [];
+    for (const name of ["cc.md", "AGENTS.md", "CLAUDE.md"]) {
+      const p = join(cwd, name);
+      if (deps.existsSync(p)) {
+        try {
+          files.push({ path: name, bytes: deps.statSync(p).size });
+        } catch {
+          // raced/unreadable — skip
+        }
+      }
+    }
+    for (const f of checkInstructionFiles(files)) {
+      checks.push(
+        check(
+          f.id,
+          f.ref,
+          SEVERITY_TO_LEVEL[f.severity] || CHECK_LEVELS.INFO,
+          `${f.message} — ${f.remediation}`,
+        ),
+      );
+    }
+  } catch (err) {
+    checks.push(failedCheck("instructions", "instruction files", err));
+  }
+
+  if (checks.length === 0) {
+    checks.push(check("runtime-clean", "runtime hygiene", CHECK_LEVELS.OK, ""));
+  }
+  return { id: "runtime", title: "Runtime checkup", checks };
+}
+
 /**
  * Collect all checkup sections. Never throws — a failing subsystem becomes an
  * `err` check inside its section.
@@ -557,6 +632,7 @@ export async function collectCheckupSections(opts = {}) {
     transcriptSection,
     backgroundSection,
     worktreeSection,
+    runtimeSection,
   ]) {
     try {
       sections.push(await build(opts, deps));