@pellux/goodvibes-tui 1.13.0 → 1.14.0

package/src/input/commands/ci-runtime.ts

@@ -0,0 +1,207 @@
+/**
+ * ci-runtime.ts
+ *
+ * `/ci` — the CI-watch surface: a one-shot per-job status check (`ci.status`)
+ * and standing watches (`ci.watches.*`) over the operator wire (see
+ * operator-rpc.ts for why this goes over HTTP rather than the in-process
+ * OperatorClient facade). The doctrine, verbatim from the operator contract's
+ * `ci.status` description: "the overall verdict is derived from the per-job
+ * conclusions (never a rollup); continue-on-error jobs are surfaced as
+ * violations and force the verdict off 'passed'." `platform/ci-watch` (the
+ * module implementing that doctrine server-side) is not in this SDK's public
+ * export map yet, so the per-job rendering below is a thin, doctrine-faithful
+ * mirror of the contract's own `ci.status`/`ci.watches.run` output — every job
+ * name and conclusion listed individually, never summarized.
+ */
+import type { CommandRegistry } from '../command-registry.ts';
+import { describeOperatorRpcError, getOperatorRpc } from './operator-rpc.ts';
+import type { OperatorMethodOutput } from '@pellux/goodvibes-sdk';
+
+export type CiReport = OperatorMethodOutput<'ci.status'>['report'];
+export type CiWatchSubscription = OperatorMethodOutput<'ci.watches.list'>['watches'][number];
+
+interface CiTarget {
+  readonly repo: string;
+  readonly ref?: string;
+  readonly prNumber?: number;
+}
+
+/**
+ * Parse a combined "repo-or-pr" token: `owner/repo`, `owner/repo#123` (PR),
+ * or `owner/repo@ref` (branch/tag/sha). Returns null when the repo segment
+ * is missing so callers can print a usage hint instead of a confusing error.
+ */
+export function parseCiTarget(token: string): CiTarget | null {
+  const trimmed = token.trim();
+  if (!trimmed) return null;
+  const prMatch = trimmed.match(/^([^#@]+)#(\d+)$/);
+  if (prMatch) {
+    const [, repo, prNumber] = prMatch;
+    if (!repo) return null;
+    return { repo, prNumber: Number(prNumber) };
+  }
+  const refMatch = trimmed.match(/^([^#@]+)@(.+)$/);
+  if (refMatch) {
+    const [, repo, ref] = refMatch;
+    if (!repo || !ref) return null;
+    return { repo, ref };
+  }
+  return { repo: trimmed };
+}
+
+export function formatTarget(target: { readonly repo: string; readonly ref?: string | undefined; readonly prNumber?: number | undefined }): string {
+  if (target.prNumber) return `${target.repo}#${target.prNumber}`;
+  if (target.ref) return `${target.repo}@${target.ref}`;
+  return target.repo;
+}
+
+/** Per-job listing, doctrine-faithful: every job and its conclusion, never a rollup. */
+export function renderReport(report: CiReport): string {
+  const failing = report.jobs
+    .filter((job) => job.status === 'completed' && job.conclusion !== 'success')
+    .map((job) => job.name);
+  const lines: string[] = [];
+  if (report.overall !== 'passed' && failing.length > 0) lines.push(`FAILING: ${failing.join(', ')}`);
+  lines.push(`CI ${report.overall.toUpperCase()} for ${formatTarget(report)}`);
+  for (const job of report.jobs) {
+    lines.push(`  - ${job.name}: ${job.status === 'completed' ? (job.conclusion ?? 'no-conclusion') : job.status}${job.continueOnError ? ' [continue-on-error]' : ''}`);
+  }
+  for (const violation of report.violations) lines.push(`  ! ${violation}`);
+  return lines.join('\n');
+}
+
+export function renderWatch(watch: CiWatchSubscription): string {
+  const parts = [
+    `  ${watch.id}  ${formatTarget(watch)}`,
+    `    delivery: ${watch.deliveryChannel}`,
+    `    fix-session on failure: ${watch.triggerFixSession ? 'yes' : 'no'}`,
+  ];
+  if (watch.lastOverall) parts.push(`    last checked: ${watch.lastOverall}`);
+  return parts.join('\n');
+}
+
+export function registerCiRuntimeCommands(registry: CommandRegistry): void {
+  registry.register({
+    name: 'ci',
+    description: 'CI-watch: one-shot per-job status and standing watches over the operator surface',
+    usage: 'status <repo-or-pr> | watch <repo-or-pr> <deliveryChannel> [--fix-session] | watches | unwatch <id>',
+    argsHint: '[status|watch|watches|unwatch]',
+    async handler(args, ctx) {
+      const sub = args[0];
+      const rpc = getOperatorRpc(ctx);
+
+      if (sub === 'status') {
+        const target = args[1] ? parseCiTarget(args[1]) : null;
+        if (!target) {
+          ctx.print('Usage: /ci status <repo-or-pr>  (e.g. owner/repo, owner/repo#123, owner/repo@branch)');
+          return;
+        }
+        if (!rpc.available) {
+          ctx.print(`[ci] ${rpc.reason}`);
+          return;
+        }
+        try {
+          const { report } = await rpc.sdk.operator.invoke('ci.status', {
+            repo: target.repo,
+            ...(target.ref !== undefined ? { ref: target.ref } : {}),
+            ...(target.prNumber !== undefined ? { prNumber: target.prNumber } : {}),
+          });
+          ctx.print(renderReport(report));
+        } catch (error) {
+          ctx.print(`[ci status] ${describeOperatorRpcError(error)}`);
+        }
+        return;
+      }
+
+      if (sub === 'watch') {
+        const target = args[1] ? parseCiTarget(args[1]) : null;
+        const deliveryChannel = args[2];
+        const triggerFixSession = args.includes('--fix-session');
+        if (!target || !deliveryChannel) {
+          ctx.print('Usage: /ci watch <repo-or-pr> <deliveryChannel> [--fix-session]  (deliveryChannel: "surfaceKind" or "surfaceKind:address")');
+          return;
+        }
+        if (!rpc.available) {
+          ctx.print(`[ci] ${rpc.reason}`);
+          return;
+        }
+        try {
+          const { watch } = await rpc.sdk.operator.invoke('ci.watches.create', {
+            repo: target.repo,
+            ...(target.ref !== undefined ? { ref: target.ref } : {}),
+            ...(target.prNumber !== undefined ? { prNumber: target.prNumber } : {}),
+            deliveryChannel,
+            triggerFixSession,
+          });
+          ctx.print(`[ci watch] created watch ${watch.id} for ${formatTarget(watch)} -> ${watch.deliveryChannel}`);
+        } catch (error) {
+          ctx.print(`[ci watch] ${describeOperatorRpcError(error)}`);
+        }
+        return;
+      }
+
+      if (sub === 'watches') {
+        const runId = args[1] === 'run' ? args[2] : undefined;
+        if (!rpc.available) {
+          ctx.print(`[ci] ${rpc.reason}`);
+          return;
+        }
+        if (args[1] === 'run') {
+          if (!runId) {
+            ctx.print('Usage: /ci watches run <id>');
+            return;
+          }
+          try {
+            const result = await rpc.sdk.operator.invoke('ci.watches.run', { watchId: runId });
+            const lines = [renderReport(result.report)];
+            lines.push(`notified: ${result.notified ? 'yes' : 'no'}${result.notificationId ? ` (${result.notificationId})` : ''}`);
+            lines.push(`fix-session triggered: ${result.fixSessionTriggered ? 'yes' : 'no'}${result.fixSessionId ? ` (${result.fixSessionId})` : ''}`);
+            ctx.print(lines.join('\n'));
+          } catch (error) {
+            ctx.print(`[ci watches run] ${describeOperatorRpcError(error)}`);
+          }
+          return;
+        }
+        try {
+          const { watches } = await rpc.sdk.operator.invoke('ci.watches.list', {});
+          if (watches.length === 0) {
+            ctx.print('[ci watches] no standing watches.');
+            return;
+          }
+          ctx.print(['CI watches:', ...watches.map(renderWatch)].join('\n'));
+        } catch (error) {
+          ctx.print(`[ci watches] ${describeOperatorRpcError(error)}`);
+        }
+        return;
+      }
+
+      if (sub === 'unwatch') {
+        const watchId = args[1];
+        if (!watchId) {
+          ctx.print('Usage: /ci unwatch <id>');
+          return;
+        }
+        if (!rpc.available) {
+          ctx.print(`[ci] ${rpc.reason}`);
+          return;
+        }
+        try {
+          const result = await rpc.sdk.operator.invoke('ci.watches.delete', { watchId });
+          ctx.print(result.deleted ? `[ci unwatch] deleted watch ${watchId}.` : `[ci unwatch] no watch found with id ${watchId}.`);
+        } catch (error) {
+          ctx.print(`[ci unwatch] ${describeOperatorRpcError(error)}`);
+        }
+        return;
+      }
+
+      ctx.print(
+        'Usage: /ci <subcommand>\n'
+        + '  /ci status <repo-or-pr>                        — per-job CI status (never a rollup)\n'
+        + '  /ci watch <repo-or-pr> <deliveryChannel> [--fix-session] — create a standing watch\n'
+        + '  /ci watches                                    — list standing watches\n'
+        + '  /ci watches run <id>                           — check one watch now\n'
+        + '  /ci unwatch <id>                                — delete a standing watch'
+      );
+    },
+  });
+}

package/src/input/commands/cost-attribution-format.ts

@@ -0,0 +1,52 @@
+/**
+ * cost-attribution-format.ts — pure rendering helpers for /cost attribution.
+ *
+ * cost.attribution.get (SDK 1.6.1) is honest-unpriced by design: an unknown
+ * model contributes to unpricedRecordCount with a null cost rather than a
+ * fabricated amount, and costState is 'priced' | 'estimated' | 'unpriced'
+ * (a mix across contributors). These helpers preserve that distinction all
+ * the way to the rendered line — "unpriced" always reads as unpriced,
+ * "estimated" is always labeled, and a dollar figure only ever comes from a
+ * real priced/estimated costUsd.
+ */
+import type { OperatorMethodOutput } from '@pellux/goodvibes-sdk';
+
+export type CostAttributionResult = OperatorMethodOutput<'cost.attribution.get'>;
+export type CostAttributionDimension = CostAttributionResult['dimension'];
+export type CostWindow = CostAttributionResult['window'];
+
+/** Dimensions always queried and rendered, even when empty (agent/model/provider are the headline breakdown). */
+export const COST_ATTRIBUTION_PRIMARY_DIMENSIONS: readonly CostAttributionDimension[] = ['agent', 'model', 'provider'];
+
+/**
+ * Dimensions that exist on the wire but return honest-empty until their
+ * emit sites tag records with this dimension. Queried the same as the
+ * primary set, but rendered ONLY when non-empty — never a fabricated
+ * "0 tool calls" section implying tool-level attribution works today.
+ */
+export const COST_ATTRIBUTION_OPTIONAL_DIMENSIONS: readonly CostAttributionDimension[] = ['tool', 'hook', 'mcp'];
+
+function formatCostAmount(costUsd: number | null, costState: CostAttributionResult['costState']): string {
+  if (costUsd === null || costState === 'unpriced') return 'unpriced';
+  const amount = `$${costUsd.toFixed(4)}`;
+  return costState === 'estimated' ? `${amount} (estimated)` : amount;
+}
+
+function formatTokens(tokens: CostAttributionResult['tokens']): string {
+  return `in=${tokens.inputTokens} out=${tokens.outputTokens} cacheR=${tokens.cacheReadTokens} cacheW=${tokens.cacheWriteTokens}`;
+}
+
+/** Render one dimension's windowed attribution result as text lines, or null when it's an optional dimension with no rows yet. */
+export function formatCostAttributionSection(result: CostAttributionResult, isOptional: boolean): string[] | null {
+  if (isOptional && result.rows.length === 0) return null;
+  const lines: string[] = [`${result.dimension} (${result.window}, since ${new Date(result.windowStartMs).toLocaleString()}):`];
+  if (result.rows.length === 0) {
+    lines.push('  (no attributed records in this window)');
+    return lines;
+  }
+  for (const row of result.rows) {
+    lines.push(`  ${row.key.padEnd(24)} ${formatCostAmount(row.costUsd, row.costState).padEnd(20)} ${formatTokens(row.tokens)}`);
+  }
+  lines.push(`  total: ${formatCostAmount(result.totalCostUsd, result.costState)} — ${result.pricedRecordCount} priced, ${result.unpricedRecordCount} unpriced record(s)`);
+  return lines;
+}

package/src/input/commands/cost-runtime.ts

@@ -1,6 +1,14 @@
 import type { CommandRegistry } from '../command-registry.ts';
 import { CostTrackerPanel } from '../../panels/cost-tracker-panel.ts';
 import { openCommandPanel, requirePanelManager } from './runtime-services.ts';
+import { describeOperatorRpcError, getOperatorRpc } from './operator-rpc.ts';
+import {
+  COST_ATTRIBUTION_OPTIONAL_DIMENSIONS,
+  COST_ATTRIBUTION_PRIMARY_DIMENSIONS,
+  formatCostAttributionSection,
+  type CostAttributionResult,
+  type CostWindow,
+} from './cost-attribution-format.ts';
 
 /**
  * /cost budget <usd> — makes the CostTrackerPanel's budget alert real (WO-139).
@@ -13,9 +21,9 @@ import { openCommandPanel, requirePanelManager } from './runtime-services.ts';
 export function registerCostRuntimeCommands(registry: CommandRegistry): void {
   registry.register({
     name: 'cost',
-    description: 'Inspect session/agent cost tracking and configure the budget alert threshold',
-    usage: '[panel|budget <usd>]',
-    handler(args, ctx) {
+    description: 'Inspect session/agent cost tracking, windowed cost attribution, and the budget alert threshold',
+    usage: '[panel|budget <usd>|attribution [24h|7d] [--json]]',
+    async handler(args, ctx) {
       const sub = (args[0] ?? 'panel').toLowerCase();
 
       if (sub === 'panel' || sub === 'open') {
@@ -43,7 +51,39 @@ export function registerCostRuntimeCommands(registry: CommandRegistry): void {
         return;
       }
 
-      ctx.print('Usage: /cost [panel|budget <usd>]');
+      if (sub === 'attribution' || sub === 'attr') {
+        const window: CostWindow = args.includes('7d') ? '7d' : '24h';
+        const asJson = args.includes('--json');
+        const rpc = getOperatorRpc(ctx);
+        if (!rpc.available) {
+          ctx.print(`[cost attribution] ${rpc.reason}`);
+          return;
+        }
+        const dimensions = [...COST_ATTRIBUTION_PRIMARY_DIMENSIONS, ...COST_ATTRIBUTION_OPTIONAL_DIMENSIONS];
+        const results: CostAttributionResult[] = [];
+        try {
+          for (const dimension of dimensions) {
+            results.push(await rpc.sdk.operator.invoke('cost.attribution.get', { window, dimension }));
+          }
+        } catch (error) {
+          ctx.print(`[cost attribution] round-trip request failed: ${describeOperatorRpcError(error)}`);
+          return;
+        }
+        if (asJson) {
+          ctx.print(JSON.stringify(results, null, 2));
+          return;
+        }
+        const lines: string[] = [`Cost Attribution — ${window}`];
+        for (const result of results) {
+          const isOptional = (COST_ATTRIBUTION_OPTIONAL_DIMENSIONS as readonly string[]).includes(result.dimension);
+          const section = formatCostAttributionSection(result, isOptional);
+          if (section) lines.push('', ...section);
+        }
+        ctx.print(lines.join('\n'));
+        return;
+      }
+
+      ctx.print('Usage: /cost [panel|budget <usd>|attribution [24h|7d] [--json]]');
     },
   });
 }

package/src/input/commands/editor-runtime.ts

@@ -0,0 +1,22 @@
+import type { CommandRegistry } from '../command-registry.ts';
+
+/**
+ * `/editor` — open the current composer draft in the user's $EDITOR / $VISUAL,
+ * then load the edited text back into the composer. The actual terminal
+ * suspend/resume and buffer round-trip are wired in main.ts as the
+ * `openComposerEditor` command action; this command is the front door for it.
+ */
+export function registerEditorRuntimeCommands(registry: CommandRegistry): void {
+  registry.register({
+    name: 'editor',
+    aliases: ['ed'],
+    description: 'Edit the current composer draft in your $EDITOR, then resume with the result',
+    handler(_args, ctx) {
+      if (!ctx.openComposerEditor) {
+        ctx.print('External editor composition is not available in this runtime.');
+        return;
+      }
+      ctx.openComposerEditor();
+    },
+  });
+}

package/src/input/commands/flags-runtime.ts

@@ -0,0 +1,328 @@
+/**
+ * `/flags` — surface every feature flag grouped by state, with runtime toggling
+ * for the flags that support it and a doctor section that names the "dark"
+ * subsystems (built but disabled) alongside the command to switch each on.
+ *
+ * The flag registry and runtime state come from the FeatureFlagManager
+ * (ctx.platform.featureFlagManager); persistence of an override goes through
+ * the config `featureFlags` category, reusing persistFlagState so the on-disk
+ * behavior matches the settings modal exactly.
+ */
+
+import type { CommandRegistry, CommandContext } from '../command-registry.ts';
+import type { FeatureFlag, FlagState } from '@/runtime/index.ts';
+import type { OperatorMethodOutput } from '@pellux/goodvibes-sdk';
+import { FEATURE_FLAG_CONFIG } from '@pellux/goodvibes-sdk/platform/runtime/state';
+import { persistFlagState } from '../settings-modal-mutations.ts';
+import { describeOperatorRpcError, getOperatorRpc } from './operator-rpc.ts';
+import { SETTINGS_CATEGORY_GROUPS, type SettingsCategory } from '../settings-modal-types.ts';
+import { getFeatureUnitHostCategory } from '../feature-unit-layout.ts';
+
+/** The flags.graduation.report response, as typed by the installed operator contract. */
+type GraduationReport = OperatorMethodOutput<'flags.graduation.report'>;
+type GraduationEntry = GraduationReport['entries'][number];
+
+/** A flag paired with its live runtime state and any pending-restart marker. */
+export interface FlagSnapshotEntry {
+  readonly flag: FeatureFlag;
+  /** Live effective state the runtime currently sees. */
+  readonly state: FlagState;
+  /** Persisted config-layer value; differs from `state` only for a startup-gated flag awaiting restart. */
+  readonly persistedState: FlagState;
+  /** True when a startup-gated flag's saved value needs a restart to take effect. */
+  readonly pendingRestart: boolean;
+}
+
+const ENABLED_MARK = '●';
+const DISABLED_MARK = '○';
+const KILLED_MARK = '✕';
+
+function toggleability(flag: FeatureFlag): string {
+  return flag.runtimeToggleable ? 'runtime-toggleable' : 'startup-only';
+}
+
+function stateMark(state: FlagState): string {
+  return state === 'enabled' ? ENABLED_MARK : state === 'killed' ? KILLED_MARK : DISABLED_MARK;
+}
+
+/** The config keys a flag tunes, from FEATURE_FLAG_CONFIG (empty for no-config flags). */
+function flagConfigKeys(flagId: string): readonly string[] {
+  return FEATURE_FLAG_CONFIG[flagId]?.configKeys ?? [];
+}
+
+/** Format one flag as a feature unit: state + name + toggleability, then a config-key summary. */
+function formatUnit(entry: FlagSnapshotEntry): string {
+  const { flag } = entry;
+  const lines = [`  ${stateMark(entry.state)} ${flag.id}  —  ${flag.name}  [${toggleability(flag)}]`];
+  if (entry.pendingRestart) {
+    lines.push(`      restart pending: saved ${entry.persistedState}; still ${entry.state} until next launch`);
+  }
+  const keys = flagConfigKeys(flag.id);
+  if (keys.length > 0) {
+    const shown = keys.slice(0, 4).join(', ');
+    const more = keys.length > 4 ? `, +${keys.length - 4} more` : '';
+    lines.push(`      tunes: ${shown}${more}  (edit in /settings)`);
+  } else {
+    lines.push('      no config keys — toggle only');
+  }
+  if (entry.state === 'killed' && flag.killReason) {
+    lines.push(`      killed: ${flag.killReason}`);
+  }
+  return lines.join('\n');
+}
+
+/** Top-level settings group label that hosts a flag's feature unit (mirrors the settings modal grouping). */
+function groupLabelForFlag(flagId: string): string {
+  const host = getFeatureUnitHostCategory(flagId);
+  for (const group of SETTINGS_CATEGORY_GROUPS) {
+    if (group.categories.includes(host as SettingsCategory)) return group.label;
+  }
+  return 'Advanced';
+}
+
+/**
+ * Build the `/flags` overview: feature units grouped by their topical settings
+ * group — each flag with the config keys it tunes — matching how the settings
+ * modal now presents them. This replaces the old flat Enabled/Disabled/Killed
+ * dump; the doctor and graduation views keep their diagnostic form. Pure —
+ * exported for testing.
+ */
+export function formatFlagsOverview(entries: readonly FlagSnapshotEntry[]): string {
+  if (entries.length === 0) return 'No feature flags are registered in this runtime.';
+
+  const enabled = entries.filter((e) => e.state === 'enabled').length;
+  const dark = entries.filter((e) => e.state === 'disabled').length;
+  const killed = entries.filter((e) => e.state === 'killed').length;
+
+  const out: string[] = [
+    `Feature flags (${entries.length} total) — ${enabled} enabled · ${dark} dark · ${killed} killed`,
+    'Each flag is one feature unit: its toggle plus the config keys it tunes. Full editing lives in /settings.',
+    '',
+  ];
+
+  // Bucket the (already tier-then-id sorted) entries by their topical group,
+  // preserving SETTINGS_CATEGORY_GROUPS order.
+  const byGroup = new Map<string, FlagSnapshotEntry[]>();
+  for (const entry of entries) {
+    const label = groupLabelForFlag(entry.flag.id);
+    if (!byGroup.has(label)) byGroup.set(label, []);
+    byGroup.get(label)!.push(entry);
+  }
+  const orderedLabels = [
+    ...SETTINGS_CATEGORY_GROUPS.map((g) => g.label).filter((label) => byGroup.has(label)),
+    ...[...byGroup.keys()].filter((label) => !SETTINGS_CATEGORY_GROUPS.some((g) => g.label === label)),
+  ];
+
+  for (const label of orderedLabels) {
+    out.push(`${label.toUpperCase()}:`);
+    for (const entry of byGroup.get(label)!) out.push(formatUnit(entry));
+    out.push('');
+  }
+
+  out.push('Toggle runtime-toggleable flags:  /flags on <id>   /flags off <id>');
+  out.push('Startup-only flags apply on next launch. Interactive toggling + full config: /settings.');
+  out.push('See /flags doctor for dark subsystems you can switch on; /flags graduation for release readiness.');
+  return out.join('\n');
+}
+
+/** Build the `/flags doctor` text: disabled (built, dark) flags + how to enable each. Pure. */
+export function formatFlagsDoctor(entries: readonly FlagSnapshotEntry[]): string {
+  const dark = entries.filter((e) => e.state === 'disabled');
+  if (dark.length === 0) {
+    return 'Feature flag doctor: no dark subsystems — every built flag is enabled or killed.';
+  }
+  const out: string[] = [
+    `Feature flag doctor — ${dark.length} dark subsystem${dark.length === 1 ? '' : 's'} (built but disabled):`,
+    '',
+  ];
+  for (const entry of dark) {
+    const { flag } = entry;
+    out.push(`  ${DISABLED_MARK} ${flag.id}  —  ${flag.name}`);
+    out.push(`      ${flag.description}`);
+    if (flag.runtimeToggleable) {
+      out.push(`      enable now:   /flags on ${flag.id}`);
+    } else {
+      out.push(`      enable (next launch, startup-only):   /flags on ${flag.id}`);
+    }
+    out.push('');
+  }
+  return out.join('\n').trimEnd();
+}
+
+/** Snapshot the manager's flags into a stable, tier-then-id-sorted list. */
+function snapshotEntries(ctx: CommandContext): FlagSnapshotEntry[] {
+  const manager = ctx.platform.featureFlagManager;
+  if (!manager) return [];
+  return Array.from(manager.getAll().values())
+    .map(({ flag, state, persistedState, pendingRestart }) => ({ flag, state, persistedState, pendingRestart }))
+    .sort((a, b) => (a.flag.tier - b.flag.tier) || a.flag.id.localeCompare(b.flag.id));
+}
+
+function applyToggle(ctx: CommandContext, id: string, target: 'enabled' | 'disabled'): void {
+  const manager = ctx.platform.featureFlagManager;
+  if (!manager) {
+    ctx.print('Feature flags are not available in this runtime.');
+    return;
+  }
+  const entry = snapshotEntries(ctx).find((e) => e.flag.id === id);
+  if (!entry) {
+    ctx.print(`Unknown feature flag: ${id}. Run /flags to list them.`);
+    return;
+  }
+  if (entry.state === target) {
+    ctx.print(`Flag ${id} is already ${target}.`);
+    return;
+  }
+  const { flag } = entry;
+
+  // Persist the override, then apply the same value to the live manager through
+  // applyConfigState — the same consistent path the settings modal uses. It
+  // flips runtime-toggleable flags immediately and records a pending-restart
+  // marker (never a fake live flip) for startup-gated ones.
+  try {
+    persistFlagState(ctx.platform.configManager, flag.id, target, flag.defaultState);
+    manager.applyConfigState(flag.id, target);
+  } catch (err) {
+    ctx.print(`Could not ${target === 'enabled' ? 'enable' : 'disable'} ${id}: ${err instanceof Error ? err.message : String(err)}`);
+    return;
+  }
+
+  if (manager.hasPendingRestart(flag.id)) {
+    ctx.print(`Flag ${id} is startup-only. Saved ${target} — it applies on next launch (currently ${manager.getState(flag.id)}).`);
+    return;
+  }
+  ctx.print(`Flag ${id} is now ${manager.getState(flag.id)} (runtime + persisted).`);
+  ctx.renderRequest();
+}
+
+// ---------------------------------------------------------------------------
+// /flags graduation — render flags.graduation.report (the release-readiness lane
+// for each flag). Candidates awaiting a decision are the only release-blocking
+// state, so they sort first; every flag shows its evidence, with "no evidence
+// collected" stated plainly rather than implied.
+// ---------------------------------------------------------------------------
+
+const GRADUATION_MARK: Record<GraduationEntry['state'], string> = {
+  'graduate-candidate': '◆',
+  blocked: '✕',
+  soaking: '◐',
+  dark: '○',
+  graduated: '●',
+};
+
+/** Sort rank: candidates (need a decision) first, then blocked, soaking, dark, graduated. */
+const GRADUATION_RANK: Record<GraduationEntry['state'], number> = {
+  'graduate-candidate': 0,
+  blocked: 1,
+  soaking: 2,
+  dark: 3,
+  graduated: 4,
+};
+
+/** One evidence line — real divergence readings, or an explicit absence of them. */
+function formatEvidence(entry: GraduationEntry): string {
+  const { evidence } = entry;
+  const parts = [evidence.note];
+  if (evidence.divergence) {
+    const d = evidence.divergence;
+    parts.push(`divergence ${(d.divergenceRate * 100).toFixed(2)}% over ${d.totalEvaluations} evals, gate ${d.gateStatus}`);
+  }
+  return `${parts.join(' · ')} (instrumentation: ${evidence.instrumentation})`;
+}
+
+function formatGraduationEntry(entry: GraduationEntry): string {
+  const toggle = entry.runtimeToggleable ? 'runtime-toggleable' : 'startup-only';
+  const lines = [
+    `  ${GRADUATION_MARK[entry.state]} ${entry.flagId}  —  ${entry.name}  [tier ${entry.tier}, default ${entry.currentDefault}, ${toggle}]`,
+    `      state: ${entry.state}`,
+    `      evidence: ${formatEvidence(entry)}`,
+  ];
+  if (entry.blocker) lines.push(`      blocked ${entry.blocker.date}: ${entry.blocker.reason}`);
+  if (entry.note) lines.push(`      note: ${entry.note}`);
+  return lines.join('\n');
+}
+
+/** Build the `/flags graduation` overview. Pure — exported for testing. */
+export function formatGraduationReport(report: GraduationReport): string {
+  const { summary } = report;
+  const out: string[] = [
+    `Feature-flag graduation (${summary.total} flags) — generated ${new Date(report.generatedAt).toISOString()}`,
+    `  candidates awaiting decision: ${summary.graduateCandidate} · graduated: ${summary.graduated} · soaking: ${summary.soaking} · dark: ${summary.dark} · blocked: ${summary.blocked}`,
+    '',
+  ];
+
+  const sorted = [...report.entries].sort(
+    (a, b) => (GRADUATION_RANK[a.state] - GRADUATION_RANK[b.state]) || (a.tier - b.tier) || a.flagId.localeCompare(b.flagId),
+  );
+
+  if (report.releaseBlockers.length > 0) {
+    out.push(`RELEASE BLOCKERS (${report.releaseBlockers.length}) — each must graduate (flip default ON) or record a dated blocker:`);
+    for (const entry of sorted.filter((e) => e.state === 'graduate-candidate')) out.push(formatGraduationEntry(entry));
+    out.push('');
+  } else {
+    out.push('No release blockers — nothing sits in graduate-candidate.');
+    out.push('');
+  }
+
+  const rest = sorted.filter((e) => e.state !== 'graduate-candidate');
+  if (rest.length > 0) {
+    out.push('All other flags:');
+    for (const entry of rest) out.push(formatGraduationEntry(entry));
+  }
+  return out.join('\n').trimEnd();
+}
+
+async function runGraduationReport(ctx: CommandContext): Promise<void> {
+  const rpc = getOperatorRpc(ctx);
+  if (!rpc.available) {
+    ctx.print(`[flags graduation] ${rpc.reason}`);
+    return;
+  }
+  try {
+    const report = await rpc.sdk.operator.invoke('flags.graduation.report', {});
+    ctx.print(formatGraduationReport(report));
+  } catch (error) {
+    ctx.print(`[flags graduation] ${describeOperatorRpcError(error)}`);
+  }
+}
+
+export function registerFlagsRuntimeCommands(registry: CommandRegistry): void {
+  registry.register({
+    name: 'flags',
+    description: 'List feature flags by state, toggle runtime-toggleable ones, surface dark subsystems, and report graduation readiness',
+    usage: '[list|on <id>|off <id>|doctor|graduation]',
+    argsHint: '[on|off <id> | doctor | graduation]',
+    async handler(args, ctx) {
+      const sub = (args[0] ?? 'list').toLowerCase();
+      switch (sub) {
+        case 'list':
+        case 'ls':
+          ctx.print(formatFlagsOverview(snapshotEntries(ctx)));
+          return;
+        case 'doctor':
+          ctx.print(formatFlagsDoctor(snapshotEntries(ctx)));
+          return;
+        case 'graduation':
+        case 'grad':
+          await runGraduationReport(ctx);
+          return;
+        case 'on':
+        case 'enable': {
+          const id = args[1];
+          if (!id) { ctx.print('Usage: /flags on <id>'); return; }
+          applyToggle(ctx, id, 'enabled');
+          return;
+        }
+        case 'off':
+        case 'disable': {
+          const id = args[1];
+          if (!id) { ctx.print('Usage: /flags off <id>'); return; }
+          applyToggle(ctx, id, 'disabled');
+          return;
+        }
+        default:
+          ctx.print(`Unknown /flags subcommand: ${sub}. Use: list | on <id> | off <id> | doctor | graduation`);
+      }
+    },
+  });
+}