chainlesschain 0.162.162 → 0.162.163

package/src/lib/agent-schedule-store.js

@@ -23,9 +23,147 @@ import fs from "fs";
 import os from "os";
 import path from "path";
 import { randomUUID } from "crypto";
+import { isEntryExpired, effectiveFireAt } from "./schedule-planner.js";
+import { SUBAGENT_PERMISSION_MODES } from "./subagent-contract.js";
+import { parseGoalCondition } from "./goal-condition-engine.js";
 
 export const SCHEDULE_KINDS = Object.freeze(["wakeup", "cron", "monitor"]);
 
+/** A valid absolute-epoch-ms expiry, or null (never expires). */
+function normalizeExpiresAt(v) {
+  const n = Number(v);
+  return Number.isFinite(n) && n > 0 ? n : null;
+}
+
+/**
+ * A non-negative integer jitter window (ms), or 0. Stored PER entry so each
+ * task carries its own deterministic spread — the schedule-planner applies a
+ * stable per-id offset within `[0, jitterMs)` so tasks sharing a cron minute
+ * fan out instead of firing as a thundering herd. 0 (the default) = no jitter.
+ */
+function normalizeJitterMs(v) {
+  const n = Math.floor(Number(v));
+  return Number.isFinite(n) && n > 0 ? n : 0;
+}
+
+/**
+ * A per-task execution policy for wakeup/cron entries — how the spawned
+ * `cc agent` run should behave when this entry fires. Each field maps to a real
+ * `cc agent` flag consumed by `cc agenda run`, so a scheduled task can carry its
+ * OWN permission mode, worktree isolation and turn budget instead of inheriting
+ * whatever ambient environment `cc agenda run` happens to run in (the gap's
+ * "每个定时任务独立预算·权限模式·Worktree"). Returns `null` when nothing is set —
+ * the entry then omits `runPolicy` entirely and is byte-identical to before,
+ * so the default (unpolicied) task keeps spawning a plain `cc agent -p`.
+ *
+ *   - permissionMode  → `--permission-mode <mode>` (validated against the single
+ *                        source SUBAGENT_PERMISSION_MODES; invalid → dropped)
+ *   - worktree        → `--worktree` (run the task in a fresh git worktree)
+ *   - maxTurns        → `--max-turns <n>` (cap the agent loop — a real budget)
+ *   - goalCondition   → `--goal-condition <spec>` (re-drive the run to a
+ *                        completion condition; validated via parseGoalCondition,
+ *                        invalid spec → the whole goal set is dropped) with its
+ *                        own token/cost/time/outer-turn budget:
+ *       goalMaxTokens  → `--goal-max-tokens <n>`
+ *       goalMaxCost    → `--goal-max-cost <usd>`
+ *       goalMaxTime    → `--goal-max-time <ms>`
+ *       maxOuterTurns  → `--max-outer-turns <n>`
+ *     (the goal budgets are meaningless without a valid condition, so they are
+ *     only kept when the condition parses.)
+ *
+ * Monitors run a shell command / watch a file rather than spawning an agent, so
+ * a run policy does not apply to them.
+ */
+export function normalizeRunPolicy({
+  permissionMode = null,
+  worktree = false,
+  maxTurns = null,
+  goalCondition = null,
+  goalMaxTokens = null,
+  goalMaxCost = null,
+  goalMaxTime = null,
+  maxOuterTurns = null,
+} = {}) {
+  const policy = {};
+  if (
+    typeof permissionMode === "string" &&
+    SUBAGENT_PERMISSION_MODES.includes(permissionMode)
+  ) {
+    policy.permissionMode = permissionMode;
+  }
+  if (worktree === true) policy.worktree = true;
+  const turns = Math.floor(Number(maxTurns));
+  if (Number.isFinite(turns) && turns > 0) policy.maxTurns = turns;
+
+  // goal-condition + its budgets: run to a completion condition with a per-task
+  // token/cost/time/outer-turn budget. Validate the spec up front so a doomed
+  // condition never gets scheduled; an invalid spec drops the whole goal set.
+  if (typeof goalCondition === "string" && goalCondition.trim()) {
+    let validSpec = false;
+    try {
+      parseGoalCondition(goalCondition);
+      validSpec = true;
+    } catch {
+      // invalid spec → drop goalCondition and its budgets entirely
+    }
+    if (validSpec) {
+      policy.goalCondition = goalCondition.trim();
+      const gTokens = Math.floor(Number(goalMaxTokens));
+      if (Number.isFinite(gTokens) && gTokens > 0)
+        policy.goalMaxTokens = gTokens;
+      const gCost = Number(goalMaxCost);
+      if (Number.isFinite(gCost) && gCost > 0) policy.goalMaxCost = gCost;
+      const gTime = Math.floor(Number(goalMaxTime));
+      if (Number.isFinite(gTime) && gTime > 0) policy.goalMaxTime = gTime;
+      const outer = Math.floor(Number(maxOuterTurns));
+      if (Number.isFinite(outer) && outer > 0) policy.maxOuterTurns = outer;
+    }
+  }
+  return Object.keys(policy).length > 0 ? policy : null;
+}
+
+/**
+ * Resolve an entry's expiry: an explicit absolute `expiresAt` (epoch-ms) wins;
+ * otherwise a positive relative `expiresInMs` is anchored to the store's own
+ * `now` (symmetric with `delayMs` on a wakeup, and deterministic under an
+ * injected clock). No expiry → null.
+ */
+function resolveExpiresAt(expiresAt, expiresInMs, now) {
+  if (expiresAt != null) return normalizeExpiresAt(expiresAt);
+  const rel = Math.floor(Number(expiresInMs));
+  if (Number.isFinite(rel) && rel > 0) return normalizeExpiresAt(now + rel);
+  return null;
+}
+
+/** Is an entry currently in a schedulable (non-terminal) state? */
+function isSchedulableStatus(entry) {
+  return entry.kind === "wakeup"
+    ? entry.status === "pending"
+    : entry.status === "active";
+}
+
+/** Statuses an entry can never leave — safe to prune. */
+export const TERMINAL_STATUSES = Object.freeze([
+  "fired",
+  "matched",
+  "exhausted",
+  "expired",
+]);
+const TERMINAL_SET = new Set(TERMINAL_STATUSES);
+
+/** Best available "this entry reached a terminal state at" timestamp. */
+function terminalAt(entry) {
+  return (
+    entry.firedAt ??
+    entry.matchedAt ??
+    entry.expiredAt ??
+    entry.lastRunAt ??
+    entry.lastCheckAt ??
+    entry.createdAt ??
+    0
+  );
+}
+
 export function agentScheduleDir(homedir = os.homedir()) {
   return path.join(homedir, ".chainlesschain", "agent-schedule");
 }
@@ -154,11 +292,23 @@ export class AgentScheduleStore {
 
   // ── create ──────────────────────────────────────────────────────────────
 
-  scheduleWakeup({ prompt, delayMs = 0, dueAt = null, label = null } = {}) {
+  scheduleWakeup(options = {}) {
+    const {
+      prompt,
+      delayMs = 0,
+      dueAt = null,
+      label = null,
+      expiresAt = null,
+      expiresInMs = null,
+      jitterMs = 0,
+    } = options;
     if (!prompt || typeof prompt !== "string") {
       throw new Error("wakeup requires a prompt");
     }
     const now = this._now();
+    // The full options object is passed to normalizeRunPolicy, which reads only
+    // the policy fields it knows — new policy knobs need no signature change here.
+    const runPolicy = normalizeRunPolicy(options);
     const entry = {
       id: randomUUID(),
       kind: "wakeup",
@@ -166,6 +316,9 @@ export class AgentScheduleStore {
       label: label || null,
       dueAt:
         dueAt != null ? Number(dueAt) : now + Math.max(0, Number(delayMs) || 0),
+      expiresAt: resolveExpiresAt(expiresAt, expiresInMs, now),
+      jitterMs: normalizeJitterMs(jitterMs),
+      ...(runPolicy ? { runPolicy } : {}),
       createdAt: now,
       status: "pending",
     };
@@ -175,7 +328,15 @@ export class AgentScheduleStore {
     return entry;
   }
 
-  createCron({ prompt, cron, label = null } = {}) {
+  createCron(options = {}) {
+    const {
+      prompt,
+      cron,
+      label = null,
+      expiresAt = null,
+      expiresInMs = null,
+      jitterMs = 0,
+    } = options;
     if (!prompt || typeof prompt !== "string") {
       throw new Error("cron requires a prompt");
     }
@@ -184,6 +345,8 @@ export class AgentScheduleStore {
     if (nextAt == null) {
       throw new Error(`cron "${cron}" has no upcoming match`);
     }
+    // Full options → normalizeRunPolicy (reads only known policy fields).
+    const runPolicy = normalizeRunPolicy(options);
     const entry = {
       id: randomUUID(),
       kind: "cron",
@@ -191,6 +354,9 @@ export class AgentScheduleStore {
       cron,
       label: label || null,
       nextAt,
+      expiresAt: resolveExpiresAt(expiresAt, expiresInMs, now),
+      jitterMs: normalizeJitterMs(jitterMs),
+      ...(runPolicy ? { runPolicy } : {}),
       createdAt: now,
       lastRunAt: null,
       runs: 0,
@@ -204,14 +370,56 @@ export class AgentScheduleStore {
 
   createMonitor({
     command,
+    watchFile = null,
+    watchUrl = null,
+    watchChange = false,
     intervalMs,
     stopWhen = null,
     notify = null,
     maxChecks = null,
     label = null,
+    expiresAt = null,
+    expiresInMs = null,
+    jitterMs = 0,
   } = {}) {
-    if (!command || typeof command !== "string") {
-      throw new Error("monitor requires a command");
+    // A monitor watches exactly one source:
+    //   - a shell `command`  → match its stdout/stderr
+    //   - a `watchFile`      → match its content, or fire when the file appears
+    //   - a `watchUrl`       → GET it and match the response body, or fire on 2xx
+    const hasCommand = typeof command === "string" && command.length > 0;
+    const hasFile = typeof watchFile === "string" && watchFile.length > 0;
+    const hasUrl = typeof watchUrl === "string" && watchUrl.length > 0;
+    const sourceCount = Number(hasCommand) + Number(hasFile) + Number(hasUrl);
+    if (sourceCount !== 1) {
+      throw new Error(
+        "monitor requires exactly one of `command`, `watchFile`, or `watchUrl`",
+      );
+    }
+    if (hasUrl) {
+      // Only http(s) endpoints — reject file:// and other schemes up-front so a
+      // bad URL errors at creation, not silently at the first poll.
+      let parsed;
+      try {
+        parsed = new URL(watchUrl);
+      } catch {
+        throw new Error(`monitor watchUrl is not a valid URL: ${watchUrl}`);
+      }
+      if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+        throw new Error(
+          `monitor watchUrl must be http(s), got: ${parsed.protocol}`,
+        );
+      }
+    }
+    if (watchChange) {
+      // `watchChange` is a file-only mode — fire when the file's mtime advances.
+      // It carries its own signal, so it cannot be combined with a stopWhen
+      // content pattern (that would be an ambiguous double condition).
+      if (!hasFile) {
+        throw new Error("monitor watchChange requires a watchFile");
+      }
+      if (stopWhen != null) {
+        throw new Error("monitor watchChange cannot be combined with stopWhen");
+      }
     }
     const interval = Math.max(1000, Number(intervalMs) || 60000);
     if (stopWhen != null) {
@@ -221,16 +429,24 @@ export class AgentScheduleStore {
       new RegExp(stopWhen);
     }
     const now = this._now();
+    const source = hasFile ? "file" : hasUrl ? "http" : "command";
     const entry = {
       id: randomUUID(),
       kind: "monitor",
-      command,
+      source,
+      command: hasCommand ? command : null,
+      watchFile: hasFile ? watchFile : null,
+      watchUrl: hasUrl ? watchUrl : null,
+      watchChange: hasFile ? Boolean(watchChange) : false,
+      lastMtimeMs: null,
       intervalMs: interval,
       stopWhen: stopWhen || null,
       notify: notify || null,
       maxChecks: maxChecks != null ? Number(maxChecks) : null,
       label: label || null,
       nextAt: now + interval,
+      expiresAt: resolveExpiresAt(expiresAt, expiresInMs, now),
+      jitterMs: normalizeJitterMs(jitterMs),
       createdAt: now,
       checks: 0,
       status: "active",
@@ -254,13 +470,45 @@ export class AgentScheduleStore {
   due(kind = null, atMs = null) {
     const now = atMs != null ? atMs : this._now();
     return this.list(kind).filter((entry) => {
-      if (entry.kind === "wakeup") {
-        return entry.status === "pending" && entry.dueAt <= now;
-      }
-      return entry.status === "active" && entry.nextAt <= now;
+      // An entry past its expiry never fires — even if it is not yet retired
+      // (defense-in-depth: retireExpired need not have run first).
+      if (isEntryExpired(entry, now)) return false;
+      if (!isSchedulableStatus(entry)) return false;
+      // The effective fire time applies the entry's OWN deterministic jitter
+      // (`entry.jitterMs`, default 0 → base fire time, byte-identical to the
+      // prior `dueAt`/`nextAt` comparison). A jittered entry fires slightly
+      // later, spreading tasks that share a cron minute.
+      const fireAt = effectiveFireAt(entry);
+      return fireAt != null && fireAt <= now;
     });
   }
 
+  /**
+   * Retire every schedulable entry whose `expiresAt` has passed (status →
+   * "expired", stamping `expiredAt`), across all kinds, so it never fires again.
+   * A daemon / `cc agenda run` calls this before firing due entries — mirroring
+   * the schedule-planner's "retire expired BEFORE due" semantics. Returns the
+   * list of retired entries.
+   */
+  retireExpired(atMs = null) {
+    const now = atMs != null ? atMs : this._now();
+    const retired = [];
+    for (const kind of SCHEDULE_KINDS) {
+      const entries = this._readAll(kind);
+      let changed = false;
+      for (const entry of entries) {
+        if (isSchedulableStatus(entry) && isEntryExpired(entry, now)) {
+          entry.status = "expired";
+          entry.expiredAt = now;
+          retired.push(entry);
+          changed = true;
+        }
+      }
+      if (changed) this._writeAll(kind, entries);
+    }
+    return retired;
+  }
+
   cancel(id) {
     for (const kind of SCHEDULE_KINDS) {
       const entries = this._readAll(kind);
@@ -274,6 +522,28 @@ export class AgentScheduleStore {
     return null;
   }
 
+  /**
+   * Remove terminal entries (fired / matched / exhausted / expired) whose
+   * terminal timestamp is at or before `before` (default: all terminal
+   * entries), across all kinds. Keeps the append-only JSONL store from growing
+   * without bound once entries finish. Returns the removed entries; only a kind
+   * that actually changed is rewritten.
+   */
+  pruneTerminal({ before = Infinity } = {}) {
+    const removed = [];
+    for (const kind of SCHEDULE_KINDS) {
+      const entries = this._readAll(kind);
+      const keep = entries.filter((entry) => {
+        const prunable =
+          TERMINAL_SET.has(entry.status) && terminalAt(entry) <= before;
+        if (prunable) removed.push(entry);
+        return !prunable;
+      });
+      if (keep.length !== entries.length) this._writeAll(kind, keep);
+    }
+    return removed;
+  }
+
   // ── lifecycle mutations (used by `cc agenda run`) ──────────────────────────
 
   /** Mark a one-shot wakeup fired (keeps history; due() skips it). */
@@ -303,11 +573,20 @@ export class AgentScheduleStore {
    * Record a monitor check. `matched` ends the monitor (done); otherwise it is
    * re-armed for the next interval, or exhausted once maxChecks is hit.
    */
-  recordMonitorCheck(id, { matched = false, atMs = null } = {}) {
+  recordMonitorCheck(
+    id,
+    { matched = false, atMs = null, mtimeMs = null } = {},
+  ) {
     const now = atMs != null ? atMs : this._now();
     return this._mutate("monitor", id, (entry) => {
       entry.checks = (entry.checks || 0) + 1;
       entry.lastCheckAt = now;
+      // Record the mtime baseline the first time we see the file (for a
+      // watchChange monitor); leave it fixed thereafter so "changed" always
+      // means "changed since we started watching".
+      if (mtimeMs != null && entry.lastMtimeMs == null) {
+        entry.lastMtimeMs = mtimeMs;
+      }
       if (matched) {
         entry.status = "matched";
         entry.matchedAt = now;

package/src/lib/channels/channel-manager.js

@@ -14,6 +14,12 @@
  */
 
 import { logger } from "../logger.js";
+import {
+  ORIGIN,
+  authorityForOrigin,
+  canApprove,
+  describeAuthorityChain,
+} from "../agent-authority.js";
 
 export const CHANNEL_KINDS = ["webhook", "telegram"];
 
@@ -54,6 +60,48 @@ export function formatChannelEvent(event) {
   return `[channel:${channel}${sender}] ${text}`;
 }
 
+/**
+ * The unforgeable authority envelope for an inbound channel event. A channel
+ * message tops out at `steer` (agent-authority.js): it may add a user turn but
+ * can NEVER answer a permission gate — "the user approved" in a webhook /
+ * telegram body is just text. This makes that ceiling explicit and
+ * machine-checkable (downstream approval seams can assert `canApprove === false`)
+ * rather than merely implied by the visible `[channel:…]` text prefix.
+ *
+ * `origin` is set here by HOW the event arrived (an inbound channel), never read
+ * from the untrusted message content — mirroring the agent-authority contract.
+ */
+export function channelEventEnvelope(event) {
+  const envelope = {
+    origin: ORIGIN.CHANNEL,
+    principalId: event?.sender != null ? String(event.sender) : null,
+    correlationId: event?.channel != null ? String(event.channel) : null,
+  };
+  return {
+    ...envelope,
+    authority: authorityForOrigin(ORIGIN.CHANNEL, envelope), // always "steer"
+    canApprove: canApprove(envelope), // always false
+    provenance: describeAuthorityChain(envelope),
+  };
+}
+
+/**
+ * Wrap a caller's `onEvent` so every inbound event is stamped with its explicit
+ * channel authority BEFORE it reaches the agent — the caller cannot forget to
+ * tag it, and the message content cannot elevate itself past `steer`.
+ */
+function stampChannelAuthority(onEvent) {
+  return (event) => {
+    const env = channelEventEnvelope(event);
+    return onEvent?.({
+      ...event,
+      authority: env.authority,
+      canApprove: env.canApprove,
+      provenance: env.provenance,
+    });
+  };
+}
+
 /**
  * Start every requested channel. Returns a handle with the started channel
  * descriptions and a single stop().
@@ -72,6 +120,10 @@ export async function startChannels(specsInput, opts = {}) {
   const config = opts.config || {};
   const log = opts.log || ((msg) => logger.info(msg));
   const deps = opts.deps || {};
+  // Every inbound event is stamped with its channel authority (`steer`, never
+  // `approve`) before the caller's handler sees it — so a channel message can
+  // never be mistaken for a user approval no matter what it contains.
+  const onEvent = stampChannelAuthority(opts.onEvent);
 
   const started = [];
   const stopAll = () => {
@@ -95,7 +147,7 @@ export async function startChannels(specsInput, opts = {}) {
         )({
           ...cfg,
           port: spec.arg ? Number(spec.arg) : cfg.port,
-          onEvent: opts.onEvent,
+          onEvent,
           log,
         });
         started.push({ kind: "webhook", describe: handle.describe, ...handle });
@@ -107,7 +159,7 @@ export async function startChannels(specsInput, opts = {}) {
           deps.telegram?.startTelegramChannel || startTelegramChannel
         )({
           ...cfg,
-          onEvent: opts.onEvent,
+          onEvent,
           log,
         });
         started.push({

package/src/lib/cli-context-engineering.js

@@ -46,11 +46,17 @@ export class CLIContextEngineering {
    * @param {string} [options.scope.taskId] - Task/sub-agent ID
    * @param {string} [options.scope.role] - Sub-agent role
    * @param {string} [options.scope.parentObjective] - Parent task objective
+   * @param {boolean} [options.memoryEnabled=true] - When false, hierarchical
+   *   memory recall is suppressed even if a `db` is present. The subagent
+   *   contract's `memory` boolean drives this for spawned children so a child
+   *   denied memory physically cannot recall it (defense-in-depth beyond the
+   *   spawn simply withholding the db).
    */
-  constructor({ db, permanentMemory, scope } = {}) {
+  constructor({ db, permanentMemory, scope, memoryEnabled = true } = {}) {
     this.db = db || null;
     this.permanentMemory = permanentMemory || null;
     this.scope = scope || null;
+    this.memoryEnabled = memoryEnabled !== false;
     this.errorHistory = [];
     this.taskContext = null;
     this._bm25 = null;
@@ -121,7 +127,8 @@ export class CLIContextEngineering {
     }
 
     // 3. Memory injection (scoped: higher threshold, namespace-aware)
-    if (this.db && userQuery) {
+    // Suppressed when memoryEnabled is false (subagent contract memory:false).
+    if (this.memoryEnabled && this.db && userQuery) {
       try {
         const memoryQuery = this.scope
           ? `[${this.scope.role}] ${userQuery}`

package/src/lib/context-breakdown.js

@@ -0,0 +1,116 @@
+/**
+ * Per-source token attribution for `cc context --sources` — the P1
+ * large-monorepo "/context 按来源分解" lever. The base `cc context` view buckets
+ * a session's stored messages by ROLE; this adds a BY-SOURCE view that also
+ * attributes the project-memory instruction files (cc.md / CLAUDE.md / rules /
+ * @imports) that would be loaded for the current working directory, each with
+ * its own token cost and provenance — so a user can see WHICH instruction file
+ * (or message class) fills the context window.
+ *
+ * Pure: token counting for instruction files is delegated to the injected
+ * estimator (the same CJK-aware `estimateTokens` the window sizing uses);
+ * message-role buckets already arrive pre-counted. No I/O.
+ *
+ * Scope note: skills and MCP tool schemas are runtime tool definitions loaded
+ * when an agent actually runs — they are NOT part of a persisted transcript nor
+ * of the project-instruction set, so they are intentionally not attributed here.
+ */
+
+import path from "path";
+
+/**
+ * Display path for an instruction source: relative-to-cwd when the file lives
+ * inside cwd, else the absolute path (a `~/.claude/…` user-scope file, or an
+ * @import that escaped the tree, is clearer shown in full).
+ */
+export function relativizeInstructionPath(absPath, cwd) {
+  if (!absPath) return "";
+  if (!cwd) return absPath;
+  try {
+    const rel = path.relative(cwd, absPath);
+    if (!rel || rel.startsWith("..") || path.isAbsolute(rel)) return absPath;
+    return rel.split(path.sep).join("/");
+  } catch {
+    return absPath;
+  }
+}
+
+/**
+ * Per-file instruction sources from `loadProjectInstructions().files`.
+ *
+ * @param {Array<{path,scope,content,truncated}>} files
+ * @param {(t:string)=>number} estimateTokens
+ * @param {string} [cwd]
+ * @returns {{ sources: Array<{scope,source,path,tokens,truncated}>, total:number }}
+ */
+export function breakdownInstructionSources(files, estimateTokens, cwd) {
+  const est = typeof estimateTokens === "function" ? estimateTokens : () => 0;
+  const list = Array.isArray(files) ? files : [];
+  const sources = list.map((f) => ({
+    scope: f?.scope || "project",
+    source: relativizeInstructionPath(f?.path, cwd),
+    path: f?.path || "",
+    tokens: est(typeof f?.content === "string" ? f.content : ""),
+    truncated: Boolean(f?.truncated),
+  }));
+  const total = sources.reduce((s, x) => s + x.tokens, 0);
+  return { sources, total };
+}
+
+// role bucket key → { label, kind } for the ranked source list.
+const MESSAGE_SOURCE_ROWS = [
+  ["system", "system messages", "message"],
+  ["user", "user messages", "message"],
+  ["assistant", "assistant messages", "message"],
+  ["tool", "tool results", "message"],
+  ["toolCalls", "tool calls", "tool_calls"],
+];
+
+/**
+ * Merge the project-memory instruction total with the per-role message buckets
+ * into ONE ranked source list (largest first) with each source's share of the
+ * combined by-source total. The message buckets are the same ones
+ * `categorizeContext` produces; instructions are folded in as a single group so
+ * the ranked view stays readable (per-file detail lives in the instructions
+ * breakdown).
+ *
+ * @param {object} args
+ * @param {number} [args.instructionTotal=0]  Σ instruction-file tokens
+ * @param {object} [args.buckets={}]           categorizeContext buckets
+ * @param {object} [args.counts={}]            categorizeContext counts
+ * @returns {{ sources: Array<{kind,source,tokens,count,share}>, total:number }}
+ */
+export function rankContextSources({
+  instructionTotal = 0,
+  buckets = {},
+  counts = {},
+} = {}) {
+  const rows = [];
+  if (instructionTotal > 0) {
+    rows.push({
+      kind: "instructions",
+      source: "project memory (instructions)",
+      tokens: instructionTotal,
+      count: null,
+    });
+  }
+  for (const [key, label, kind] of MESSAGE_SOURCE_ROWS) {
+    const tok = buckets[key] || 0;
+    if (tok > 0) {
+      rows.push({
+        kind,
+        source: label,
+        tokens: tok,
+        count: counts[key] ?? null,
+      });
+    }
+  }
+  const total = rows.reduce((s, x) => s + x.tokens, 0);
+  // Stable sort: tokens desc, then source name for deterministic ties.
+  rows.sort((a, b) => b.tokens - a.tokens || a.source.localeCompare(b.source));
+  const sources = rows.map((r) => ({
+    ...r,
+    share: total ? r.tokens / total : 0,
+  }));
+  return { sources, total };
+}

package/src/lib/doctor-checkup.js

@@ -315,6 +315,58 @@ async function pluginSection(opts, _deps2) {
   } catch (err) {
     checks.push(failedCheck("plugins", "Installed plugins", err));
   }
+
+  // Broken manifests + un-consented capabilities (Phase 3 capability gap).
+  // Distinct from the signature-lock check above: re-discover to get each
+  // plugin's parsed manifest (listInstalled drops it) so we can flag an invalid
+  // manifest and any DECLARED capability set the user has not consented to.
+  try {
+    const { discoverPlugins } = await import("./plugin-runtime/scopes.js");
+    const { isPluginCapabilityConsented } =
+      await import("./plugin-runtime/capability-consent.js");
+    const { checkPluginsAndLsp } = await import("./runtime-checkup.js");
+    const discovered =
+      discoverPlugins({ cwd: opts.cwd || process.cwd(), skipPolicy: true }) ||
+      [];
+    // Broken manifests → warn (shared runtime-checkup evaluator).
+    for (const f of checkPluginsAndLsp(
+      discovered.map((p) => ({
+        id: p.name,
+        healthy: p.manifest?.ok !== false,
+        kind: "plugin",
+      })),
+    )) {
+      checks.push(
+        check(
+          f.id,
+          `plugin ${f.ref}`,
+          CHECK_LEVELS.WARN,
+          `${f.message} — ${f.remediation}`,
+        ),
+      );
+    }
+    // Declared capabilities not yet consented → warn.
+    for (const p of discovered) {
+      if (!p.manifest?.capabilitiesDeclared) continue;
+      const consented = isPluginCapabilityConsented(
+        { name: p.name, scope: p.scope, version: p.version },
+        p.manifest.capabilities,
+      );
+      if (!consented) {
+        checks.push(
+          check(
+            "plugin-capability-unconsented",
+            `plugin ${p.name}`,
+            CHECK_LEVELS.WARN,
+            `declares capabilities not yet consented — run \`cc plugin consent ${p.name}\``,
+          ),
+        );
+      }
+    }
+  } catch (err) {
+    checks.push(failedCheck("plugin-capabilities", "plugin capabilities", err));
+  }
+
   return { id: "plugins", title: "Plugin trust", checks };
 }