@pellux/goodvibes-tui 1.13.1 → 1.15.0

package/src/input/commands/health-metrics-format.ts

@@ -0,0 +1,67 @@
+/**
+ * Pure formatters for the `/health metrics` surface (daemon runtime.metrics.get
+ * and quota.snapshot.get). Kept separate from the command wiring so the honesty
+ * bars are unit-testable without a live daemon: scope refusals are named, empty
+ * maps say "none reported" rather than showing zeros, and an unobserved quota
+ * renders as an explicit "no signal yet" instead of a fabricated full quota.
+ */
+import { GoodVibesSdkError } from '@pellux/goodvibes-sdk';
+
+/** Cap on how many entries of a single metric map we list before summarizing the rest. */
+export const METRIC_MAP_LIST_CAP = 40;
+
+/** Render one runtime-metric map as an indented `key: value` block, honestly capped. */
+export function renderMetricMap(label: string, map: Record<string, unknown> | undefined): string[] {
+  const entries = Object.entries(map ?? {}).sort(([a], [b]) => a.localeCompare(b));
+  if (entries.length === 0) return [`  ${label}: none reported`];
+  const lines = [`  ${label}: ${entries.length}`];
+  for (const [key, value] of entries.slice(0, METRIC_MAP_LIST_CAP)) {
+    const rendered = typeof value === 'object' && value !== null ? JSON.stringify(value) : String(value);
+    const trimmed = rendered.length > 120 ? `${rendered.slice(0, 117)}...` : rendered;
+    lines.push(`    ${key}: ${trimmed}`);
+  }
+  if (entries.length > METRIC_MAP_LIST_CAP) {
+    lines.push(`    (+${entries.length - METRIC_MAP_LIST_CAP} more)`);
+  }
+  return lines;
+}
+
+/**
+ * When a telemetry verb fails because the companion token lacks the required
+ * scope, say exactly that — never render zeros in place of missing authority.
+ * Returns the honest line, or null when the error is not a scope refusal.
+ */
+export function telemetryScopeRefusalLine(error: unknown, what: string): string | null {
+  if (error instanceof GoodVibesSdkError && (error.status === 401 || error.status === 403)) {
+    return `  ${what}: unavailable — the companion token lacks the read:telemetry scope this data requires (daemon returned ${error.status}).`;
+  }
+  return null;
+}
+
+/** The shape of quota.snapshot.get we render (a superset-safe subset of the SDK type). */
+export interface QuotaSnapshotView {
+  readonly hasSignal: boolean;
+  readonly remaining?: number | undefined;
+  readonly limit?: number | undefined;
+  readonly resetAt?: number | undefined;
+  readonly activeCooldownMs?: number | undefined;
+  readonly recentRateLimitCount: number;
+}
+
+/**
+ * Render the remaining-quota line for a provider. `hasSignal:false` becomes an
+ * explicit "no rate-limit signal observed yet", never zeros or a full quota.
+ */
+export function formatQuotaSnapshotLine(provider: string, quota: QuotaSnapshotView): string {
+  if (!quota.hasSignal) {
+    return `  quota (${provider}): no rate-limit signal observed yet (${quota.recentRateLimitCount} recent rate-limit event(s)).`;
+  }
+  const parts: string[] = [];
+  if (quota.remaining !== undefined) {
+    parts.push(`remaining ${quota.remaining}${quota.limit !== undefined ? `/${quota.limit}` : ''}`);
+  }
+  if (quota.resetAt !== undefined) parts.push(`resets ${new Date(quota.resetAt).toISOString()}`);
+  if (quota.activeCooldownMs !== undefined && quota.activeCooldownMs > 0) parts.push(`cooldown ${quota.activeCooldownMs}ms`);
+  parts.push(`${quota.recentRateLimitCount} recent rate-limit event(s)`);
+  return `  quota (${provider}): ${parts.join(', ')}.`;
+}

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

@@ -19,6 +19,8 @@ import {
   requireSubscriptionManager,
   requireSessionMemoryStore,
 } from './runtime-services.ts';
+import { getOperatorRpc, describeOperatorRpcError } from './operator-rpc.ts';
+import { formatQuotaSnapshotLine, renderMetricMap, telemetryScopeRefusalLine } from './health-metrics-format.ts';
 
 function renderSandboxHealthSummary(configManager: ConfigManager): string[] {
   const backend = String(configManager.get('sandbox.vmBackend') ?? 'local');
@@ -34,12 +36,13 @@ function renderSandboxHealthSummary(configManager: ConfigManager): string[] {
   return lines;
 }
 
+
 export function registerHealthRuntimeCommands(registry: CommandRegistry): void {
   registry.register({
     name: 'health',
     aliases: ['doctor'],
     description: 'Health workspace for startup posture, service readiness, sandbox posture, and provider health',
-    usage: '[report|review|open|setup|services|sandbox|provider|accounts|auth|settings|intelligence|remote|mcp|continuity|worktrees|maintenance|term|repair [domain]] — bare and report stay a cross-domain transcript report (see also /health provider for the providers modal)',
+    usage: '[report|review|open|setup|services|sandbox|provider|accounts|auth|settings|intelligence|remote|mcp|metrics|continuity|worktrees|maintenance|term|repair [domain]] — bare and report stay a cross-domain transcript report (see also /health provider for the providers modal)',
     async handler(args, ctx) {
       const sub = (args[0] ?? 'review').toLowerCase();
       const readModels = requireReadModels(ctx);
@@ -217,6 +220,56 @@ export function registerHealthRuntimeCommands(registry: CommandRegistry): void {
         return;
       }
 
+      if (sub === 'metrics' || sub === 'runtime' || sub === 'quota') {
+        const rpc = getOperatorRpc(ctx);
+        if (!rpc.available) {
+          ctx.print([
+            'Health Review: Runtime Metrics',
+            `  unavailable: ${rpc.reason}`,
+            '  next: connect a daemon (control plane) to read live runtime metrics.',
+          ].join('\n'));
+          return;
+        }
+
+        const lines: string[] = ['Health Review: Runtime Metrics'];
+
+        // Process-wide runtime metrics snapshot (runtime.metrics.get). Requires
+        // the read:telemetry scope; a scope refusal is rendered as such, never
+        // as zero counters.
+        try {
+          const metrics = await rpc.sdk.operator.invoke('runtime.metrics.get', {});
+          lines.push(...renderMetricMap('counters', metrics.counters as Record<string, unknown>));
+          lines.push(...renderMetricMap('gauges', metrics.gauges as Record<string, unknown>));
+          lines.push(...renderMetricMap('histograms', metrics.histograms as Record<string, unknown>));
+          const byModel = Object.keys(metrics.toolFormat?.byModel ?? {}).length;
+          const byClass = Object.keys(metrics.toolFormat?.byClass ?? {}).length;
+          lines.push(`  tool-format telemetry: ${byModel} model(s), ${byClass} class(es)`);
+        } catch (error) {
+          const scopeLine = telemetryScopeRefusalLine(error, 'runtime metrics');
+          lines.push(scopeLine ?? `  runtime metrics: ${describeOperatorRpcError(error)}`);
+        }
+
+        // Remaining rate-limit quota for the active provider (quota.snapshot.get).
+        // hasSignal:false is an honest "no observation yet", never a fabricated
+        // full quota. An explicit provider may be passed: /health metrics <provider>.
+        const provider = (args[1] ?? ctx.session.runtime.provider ?? '').trim();
+        if (provider) {
+          try {
+            const quota = await rpc.sdk.operator.invoke('quota.snapshot.get', { provider });
+            lines.push(formatQuotaSnapshotLine(provider, quota));
+          } catch (error) {
+            const scopeLine = telemetryScopeRefusalLine(error, `quota (${provider})`);
+            lines.push(scopeLine ?? `  quota (${provider}): ${describeOperatorRpcError(error)}`);
+          }
+        } else {
+          lines.push('  quota: no active provider to query (pass one: /health metrics <provider>).');
+        }
+
+        lines.push('  next: /health accounts');
+        ctx.print(lines.join('\n'));
+        return;
+      }
+
       if (sub === 'continuity') {
         const continuity = readModels.continuity.getSnapshot();
         const returnMode = String(ctx.platform.configManager.get('behavior.returnContextMode') ?? 'off');
@@ -455,6 +508,7 @@ export function registerHealthRuntimeCommands(registry: CommandRegistry): void {
         '  /health auth',
         '  /health settings',
         '  /health intelligence',
+        '  /health metrics',
         '  /health remote',
         '  /health maintenance',
         '  /health worktrees',

package/src/input/commands/memory.ts

@@ -19,6 +19,7 @@ import { handleRecallExport, handleRecallHandoffExport, handleRecallHandoffImpor
 import { handleRecallGet, handleRecallLink, handleRecallList, handleRecallRemove, handleRecallSearch, handleRecallVector } from './recall-query.ts';
 import { handleRecallExplain, handleRecallInjections, handleRecallPromote, handleRecallQueue, handleRecallReview } from './recall-review.ts';
 import { VALID_CLASSES, VALID_REVIEW_STATES, VALID_SCOPES } from './recall-shared.ts';
+import { handleRecallFilesApply, handleRecallFilesReview, handleRecallFilesSync } from './recall-files.ts';
 
 // ── Top-level command ─────────────────────────────────────────────────────────
 
@@ -57,6 +58,9 @@ function printRecallUsage(context: CommandContext): void {
     '  review <id> <state> [--confidence <n>] [--by <name>] [--reason <text>]',
     '  stale <id> [reason...]                          — Mark a record stale with an operator reason',
     '  contradict <id> [reason...]                     — Mark a record contradicted with an operator reason',
+    '  files sync [--dir <path>]                       — Project standing (project/team) records to git-backed markdown files',
+    '  files review [--dir <path>]                     — Diff the projection directory against the store; prints proposals, applies nothing',
+    '  files apply <id> [<id> ...] | --all [--dir <path>] — Apply only the named proposals from the last review, through the store\'s own update/delete',
     '  explain <task...> [--scope <path> ...]         — Show the knowledge records that would be injected for a task',
     '  injections [agentId]                           — Show per-turn passive knowledge injection records; no id shows the main session, an id shows that spawned agent',
     '  promote <id> <scope>                           — Promote a memory record into session|project|team scope',
@@ -111,6 +115,25 @@ export const recallCommand: SlashCommand = {
         await handleRecallCapture(rest, context);
         break;
 
+      case 'files': {
+        const [filesSub, ...filesRest] = rest;
+        switch (filesSub) {
+          case 'sync':
+            await handleRecallFilesSync(filesRest, context);
+            break;
+          case 'review':
+            await handleRecallFilesReview(filesRest, context);
+            break;
+          case 'apply':
+            await handleRecallFilesApply(filesRest, context);
+            break;
+          default:
+            context.print('[recall] Usage: /recall files <sync|review|apply> ...');
+            break;
+        }
+        break;
+      }
+
       case 'get':
       case 'show':
         await handleRecallGet(rest, context);

package/src/input/commands/operator-rpc.ts

@@ -0,0 +1,95 @@
+/**
+ * operator-rpc.ts
+ *
+ * Generic operator-verb dispatch for gateway methods that do not (yet) have a
+ * named facade on the in-process `OperatorClient` (`ctx.clients.operator`,
+ * always DirectTransport-backed in this TUI — see bootstrap-shell.ts). The
+ * initiative cluster (`ci.*`, `checkin.*`, `principals.*`,
+ * `channels.profiles.*`) ships in the operator contract but has not been
+ * promoted to that narrow facade, so commands reach it the same way any
+ * external operator client would: a real HTTP round-trip to the currently
+ * configured control-plane daemon, using `createGoodVibesSdk`'s generic
+ * `sdk.operator.invoke(methodId, input)` (typed against the installed
+ * contract — see `@pellux/goodvibes-contracts`).
+ *
+ * This is deliberately a fresh, lightweight connection per call (no pooling,
+ * no persistent socket) — these are low-frequency, operator-initiated admin
+ * calls, not hot-path session traffic. `getOperatorRpc` never throws: it
+ * returns `{ available: false, reason }` up front for every case the caller
+ * can decide about statically (daemon disabled, no reachable base URL), so
+ * commands can print an honest "not available" line instead of guessing.
+ * Once a call is made, a non-2xx response (including the 404 a not-yet-wired
+ * verb returns) surfaces to the caller as a thrown `GoodVibesSdkError` —
+ * callers should catch and render `describeOperatorRpcError` rather than
+ * pretend the request succeeded.
+ */
+import { join } from 'node:path';
+import { createGoodVibesSdk } from '@pellux/goodvibes-sdk';
+import type { GoodVibesSdk } from '@pellux/goodvibes-sdk';
+import { GoodVibesSdkError } from '@pellux/goodvibes-sdk';
+import { resolveDaemonEnabled } from '@pellux/goodvibes-sdk/platform/config';
+import { getOrCreateCompanionToken } from '@pellux/goodvibes-sdk/platform/pairing';
+import type { CommandContext } from '../command-registry.ts';
+import { requireShellPaths } from './runtime-services.ts';
+
+export interface OperatorRpcUnavailable {
+  readonly available: false;
+  readonly reason: string;
+}
+
+export interface OperatorRpcAvailable {
+  readonly available: true;
+  readonly sdk: GoodVibesSdk;
+}
+
+export type OperatorRpc = OperatorRpcUnavailable | OperatorRpcAvailable;
+
+function resolveControlPlaneBaseUrl(context: CommandContext): string | null {
+  const configManager = context.platform.configManager;
+  const explicit = String(configManager.get('controlPlane.baseUrl') ?? '').trim();
+  if (explicit) return explicit;
+  const host = String(configManager.get('controlPlane.host') ?? '').trim();
+  const port = configManager.get('controlPlane.port');
+  if (host && typeof port === 'number' && port > 0) return `http://${host}:${port}`;
+  return null;
+}
+
+/**
+ * Resolve (or honestly refuse to resolve) an operator SDK client wired to
+ * this workspace's control-plane daemon. Reasons for refusal are surfaced
+ * verbatim to the caller so `/ci`, `/checkin`, and `/principals` can print
+ * them directly rather than inventing their own wording.
+ */
+export function getOperatorRpc(context: CommandContext): OperatorRpc {
+  const configManager = context.platform.configManager;
+  if (!resolveDaemonEnabled(configManager)) {
+    return { available: false, reason: 'the daemon is disabled (daemon.enabled=false) — no operator surface to reach. Enable it in /settings, then retry.' };
+  }
+  const baseUrl = resolveControlPlaneBaseUrl(context);
+  if (!baseUrl) {
+    return { available: false, reason: 'no control-plane base URL is configured (controlPlane.baseUrl / controlPlane.host+port) — cannot reach the operator surface.' };
+  }
+  const shellPaths = requireShellPaths(context);
+  const daemonHomeDir = join(shellPaths.homeDirectory, '.goodvibes', 'daemon');
+  const token = getOrCreateCompanionToken('tui', { daemonHomeDir }).token;
+  const sdk = createGoodVibesSdk({ baseUrl, authToken: token });
+  return { available: true, sdk };
+}
+
+/**
+ * Render a thrown operator-rpc error honestly: a 404 means this daemon has
+ * not wired a handler for the verb (a live local runtime that simply doesn't
+ * implement it yet), never "no result" or a fabricated empty state.
+ */
+export function describeOperatorRpcError(error: unknown): string {
+  if (error instanceof GoodVibesSdkError) {
+    if (error.status === 404) {
+      return 'the connected daemon returned 404 — this operator verb is not wired up on that daemon yet.';
+    }
+    if (error.status === 401 || error.status === 403) {
+      return `the connected daemon rejected the request (${error.status}): ${error.message}`;
+    }
+    return `operator request failed${error.status ? ` (${error.status})` : ''}: ${error.message}`;
+  }
+  return error instanceof Error ? error.message : String(error);
+}

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

@@ -0,0 +1,22 @@
+import type { CommandRegistry } from '../command-registry.ts';
+
+/**
+ * /palette — open the fuzzy command palette, a searchable picker over every
+ * registered slash command. The palette itself is generated live from the
+ * registry (see openCommandPalette in shell/ui-openers.ts); this command is
+ * just the discoverable front door, mirroring the Ctrl+K chord.
+ */
+export function registerPaletteRuntimeCommands(registry: CommandRegistry): void {
+  registry.register({
+    name: 'palette',
+    aliases: ['k'],
+    description: 'Open the command palette to search and run any slash command',
+    handler(_args, ctx) {
+      if (!ctx.openCommandPalette) {
+        ctx.print('The command palette is unavailable in this context.');
+        return;
+      }
+      ctx.openCommandPalette();
+    },
+  });
+}

package/src/input/commands/permissions-provenance.ts

@@ -0,0 +1,264 @@
+import { readFileSync } from 'node:fs';
+import type { ConfigManager, ConfigKey } from '../../config/index.ts';
+import { CONFIG_SCHEMA } from '../../config/index.ts';
+import { SHIPPED_CREDENTIAL_READ_RULES } from '@pellux/goodvibes-sdk/platform/permissions';
+
+// ---------------------------------------------------------------------------
+// /permissions provenance panel.
+//
+// Shows every permission-relevant setting in effect AND where each value came
+// from. Provenance is taken from the platform's own ConfigManager.
+// describeConfigKeySource (the recorded on-disk tier: shared / project / global
+// / default) — never a guess. Because CLI --config overrides mutate the config
+// in memory WITHOUT touching any file, we additionally compare the live value
+// against the recorded on-disk / built-in-default value: when they diverge, the
+// value was changed at runtime and its true origin is NOT recorded on disk, so
+// the line is labelled exactly that rather than mis-attributed to a file.
+// ---------------------------------------------------------------------------
+
+/** A permission-relevant setting, its live value, and where that value came from. */
+export interface PermissionProvenanceRow {
+  readonly key: string;
+  readonly label: string;
+  /** The effective (live) value the running session uses. */
+  readonly value: unknown;
+  /** Human origin: a config file + path, "built-in default", or an "origin not recorded" label. */
+  readonly origin: string;
+  readonly originPath: string | null;
+  /** False when the origin is genuinely not recorded anywhere (runtime override, unreadable file, unknown key). */
+  readonly recorded: boolean;
+  /** True when the live value diverges from the recorded on-disk / default value (an in-memory runtime override). */
+  readonly overridden: boolean;
+  /** The recorded on-disk / default value, shown alongside the effective value when overridden. */
+  readonly recordedValue?: unknown;
+  readonly note?: string;
+}
+
+/** A shipped (SDK-managed, code-embedded) policy rule — not driven by any config key, so it has no ConfigKey-based tier. */
+export interface ShippedPolicyRuleRow {
+  readonly id: string;
+  readonly effect: 'allow' | 'deny';
+  readonly description: string;
+  readonly toolPattern: string;
+  readonly pathPatterns: readonly string[];
+}
+
+export interface PermissionProvenance {
+  readonly sessionMode: string;
+  readonly sessionModeLabel: string;
+  readonly rows: readonly PermissionProvenanceRow[];
+  /**
+   * Shipped managed policy rules baked into the SDK's PermissionManager
+   * (currently: default-deny reads of well-known credential stores). These
+   * are NOT config-key-driven — there is no on/off setting and no file they
+   * could be recorded in — so they cannot use the shared/project/global/
+   * default tier model above. Listed separately with an honest "shipped
+   * default" origin rather than force-fit into a ConfigKey row.
+   */
+  readonly shippedRules: readonly ShippedPolicyRuleRow[];
+}
+
+/** The permission-relevant settings, in the order the panel lists them. */
+const PERMISSION_KEYS: readonly { readonly key: string; readonly label: string; readonly note?: string }[] = [
+  { key: 'permissions.mode', label: 'Permission mode', note: 'also the current session mode' },
+  { key: 'permissions.backgroundAgents', label: 'Background-agent mode' },
+  { key: 'behavior.autoApprove', label: 'Auto-approve everything' },
+  { key: 'featureFlags.permissions-policy-engine', label: 'Runtime policy engine (flag)' },
+  { key: 'permissions.tools.read', label: 'Tool rule: read' },
+  { key: 'permissions.tools.write', label: 'Tool rule: write' },
+  { key: 'permissions.tools.edit', label: 'Tool rule: edit' },
+  { key: 'permissions.tools.exec', label: 'Tool rule: exec' },
+  { key: 'permissions.tools.find', label: 'Tool rule: find' },
+  { key: 'permissions.tools.fetch', label: 'Tool rule: fetch' },
+  { key: 'permissions.tools.analyze', label: 'Tool rule: analyze' },
+  { key: 'permissions.tools.inspect', label: 'Tool rule: inspect' },
+  { key: 'permissions.tools.agent', label: 'Tool rule: agent' },
+  { key: 'permissions.tools.state', label: 'Tool rule: state' },
+  { key: 'permissions.tools.workflow', label: 'Tool rule: workflow' },
+  { key: 'permissions.tools.registry', label: 'Tool rule: registry' },
+  { key: 'permissions.tools.delegate', label: 'Tool rule: delegate' },
+  { key: 'permissions.tools.mcp', label: 'Tool rule: mcp' },
+];
+
+function permissionModeLabel(mode: unknown): string {
+  if (mode === 'prompt') return 'Ask before powerful actions';
+  if (mode === 'allow-all') return 'Allow everything';
+  if (mode === 'plan') return 'Plan only (read-only)';
+  if (mode === 'accept-edits') return 'Auto-accept file edits';
+  if (mode === 'custom') return 'Custom rules';
+  return String(mode ?? 'unknown');
+}
+
+/** Read a dotted key out of a parsed JSON object; segments may themselves contain hyphens. */
+function readDotPath(obj: unknown, key: string): { present: boolean; value: unknown } {
+  let cursor: unknown = obj;
+  for (const part of key.split('.')) {
+    if (cursor == null || typeof cursor !== 'object' || !(part in (cursor as object))) {
+      return { present: false, value: undefined };
+    }
+    cursor = (cursor as Record<string, unknown>)[part];
+  }
+  return { present: true, value: cursor };
+}
+
+/** The value a config key resolves to from a single on-disk file, or null when the file is unreadable. */
+function fileValue(path: string, key: string): { present: boolean; value: unknown } | null {
+  try {
+    return readDotPath(JSON.parse(readFileSync(path, 'utf-8')), key);
+  } catch {
+    return null;
+  }
+}
+
+function schemaDefault(key: string): { known: boolean; value: unknown } {
+  const setting = CONFIG_SCHEMA.find((s) => s.key === key);
+  return setting ? { known: true, value: setting.default } : { known: false, value: undefined };
+}
+
+function sameValue(a: unknown, b: unknown): boolean {
+  return JSON.stringify(a) === JSON.stringify(b);
+}
+
+type ConfigProvenanceManager = Pick<ConfigManager, 'get' | 'describeConfigKeySource' | 'getConfigPath' | 'getProjectConfigPath'>;
+
+function buildRow(
+  configManager: ConfigProvenanceManager,
+  entry: { key: string; label: string; note?: string },
+): PermissionProvenanceRow {
+  const { key, label, note } = entry;
+  let live: unknown;
+  try {
+    live = configManager.get(key as ConfigKey);
+  } catch {
+    live = undefined;
+  }
+
+  let src: ReturnType<ConfigManager['describeConfigKeySource']> | null = null;
+  try {
+    src = configManager.describeConfigKeySource(key as ConfigKey);
+  } catch {
+    src = null;
+  }
+
+  const base = { key, label, value: live, ...(note ? { note } : {}) };
+
+  // No recorded tier for this key (e.g. a feature-flag key outside the typed schema).
+  if (!src) {
+    return { ...base, origin: 'origin not recorded (key is outside the config schema)', originPath: null, recorded: false, overridden: false };
+  }
+
+  const tier = src.tier;
+  const globalPath = configManager.getConfigPath();
+  const projectPath = configManager.getProjectConfigPath();
+  const originPath = tier === 'shared' ? src.sharedTierPath
+    : tier === 'project' ? (projectPath ?? null)
+    : tier === 'global' ? globalPath
+    : null;
+
+  // The value the recorded layer actually holds on disk (or the built-in default).
+  let recordedValue: unknown;
+  let recordedSource: string;
+  if (tier === 'default') {
+    const def = schemaDefault(key);
+    recordedValue = def.value;
+    recordedSource = def.known ? 'built-in default' : 'built-in default (not in schema)';
+  } else if (originPath) {
+    const fv = fileValue(originPath, key);
+    if (!fv || !fv.present) {
+      // The tier says this file carries the key, but we could not read it back —
+      // do not guess; report the origin as unrecorded.
+      return { ...base, origin: `origin not recorded (${tier} config file could not be read back)`, originPath, recorded: false, overridden: false };
+    }
+    recordedValue = fv.value;
+    recordedSource = `${tier} config file`;
+  } else {
+    return { ...base, origin: `origin not recorded (no path for ${tier} tier)`, originPath: null, recorded: false, overridden: false };
+  }
+
+  const overridden = !sameValue(live, recordedValue);
+  if (overridden) {
+    // A CLI --config override (or any in-memory set that did not persist) sits on
+    // top of the recorded value. There is no on-disk record of where it came from.
+    return {
+      ...base,
+      origin: 'runtime override (in-memory; origin not recorded on disk)',
+      originPath,
+      recorded: false,
+      overridden: true,
+      recordedValue,
+    };
+  }
+
+  return { ...base, origin: recordedSource, originPath, recorded: true, overridden: false, recordedValue };
+}
+
+function buildShippedRuleRows(): ShippedPolicyRuleRow[] {
+  return SHIPPED_CREDENTIAL_READ_RULES.map((rule) => ({
+    id: rule.id,
+    effect: rule.effect,
+    description: rule.description ?? '(no description)',
+    toolPattern: Array.isArray(rule.toolPattern) ? rule.toolPattern.join(', ') : rule.toolPattern,
+    pathPatterns: 'pathPatterns' in rule ? rule.pathPatterns : [],
+  }));
+}
+
+export function buildPermissionProvenance(configManager: ConfigProvenanceManager): PermissionProvenance {
+  const mode = configManager.get('permissions.mode' as ConfigKey);
+  return {
+    sessionMode: String(mode ?? 'prompt'),
+    sessionModeLabel: permissionModeLabel(mode),
+    rows: PERMISSION_KEYS.map((entry) => buildRow(configManager, entry)),
+    shippedRules: buildShippedRuleRows(),
+  };
+}
+
+function displayValue(value: unknown): string {
+  if (value === undefined) return '(unset)';
+  if (typeof value === 'string') return value.length === 0 ? '(empty)' : value;
+  return JSON.stringify(value);
+}
+
+/** Render the provenance panel as plain lines for the command surface. */
+export function renderPermissionProvenance(provenance: PermissionProvenance): string {
+  const lines: string[] = [
+    'Permissions — settings in effect and where each came from',
+    `  session mode: ${provenance.sessionMode} (${provenance.sessionModeLabel})`,
+    '',
+    'Every line is traceable to its recorded origin. A value changed at runtime',
+    '(e.g. via --config) is not recorded on disk and is labelled as such.',
+    '',
+  ];
+  const keyWidth = Math.max(...provenance.rows.map((r) => r.label.length));
+  for (const row of provenance.rows) {
+    const flag = row.overridden ? ' *' : row.recorded ? '' : ' ?';
+    const valueText = displayValue(row.value);
+    lines.push(`  ${row.label.padEnd(keyWidth)} : ${valueText}${flag}`);
+    if (row.overridden) {
+      lines.push(`  ${' '.repeat(keyWidth)}   origin: ${row.origin}`);
+      lines.push(`  ${' '.repeat(keyWidth)}   on disk: ${displayValue(row.recordedValue)} (${row.originPath ?? 'no file'})`);
+    } else {
+      const pathText = row.originPath ? ` (${row.originPath})` : '';
+      lines.push(`  ${' '.repeat(keyWidth)}   origin: ${row.origin}${pathText}`);
+    }
+    if (row.note) lines.push(`  ${' '.repeat(keyWidth)}   note: ${row.note}`);
+  }
+  lines.push('');
+  lines.push('  Legend: * = runtime override (not recorded on disk)   ? = origin not recorded');
+  lines.push('  Tiers: shared / project / global config file, or the built-in default.');
+
+  if (provenance.shippedRules.length > 0) {
+    lines.push('');
+    lines.push('Shipped policy rules — baked into the SDK, not driven by any config key');
+    lines.push('(origin: shipped default; a user allow-rule always wins over these):');
+    for (const rule of provenance.shippedRules) {
+      lines.push(`  ${rule.id}  [${rule.effect}]  tools: ${rule.toolPattern}`);
+      lines.push(`    ${rule.description}`);
+      lines.push(`    origin: shipped default (SDK-managed policy rule)`);
+      if (rule.pathPatterns.length > 0) {
+        lines.push(`    paths: ${rule.pathPatterns.join(', ')}`);
+      }
+    }
+  }
+
+  return lines.join('\n');
+}

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

@@ -0,0 +1,21 @@
+import type { CommandRegistry } from '../command-registry.ts';
+import { buildPermissionProvenance, renderPermissionProvenance } from './permissions-provenance.ts';
+
+/**
+ * `/permissions` — the permission provenance panel. Prints every
+ * permission-relevant setting in effect and where each value came from
+ * (default / config file / runtime override / session mode), plus the current
+ * session mode. Read-only: it changes no config. See permissions-provenance.ts
+ * for how origin is resolved from the platform's own ConfigManager.
+ */
+export function registerPermissionsRuntimeCommands(registry: CommandRegistry): void {
+  registry.register({
+    name: 'permissions',
+    aliases: ['perms'],
+    description: 'Show permission settings in effect and where each value came from (provenance)',
+    handler(_args, ctx) {
+      const provenance = buildPermissionProvenance(ctx.platform.configManager);
+      ctx.print(renderPermissionProvenance(provenance));
+    },
+  });
+}

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

@@ -6,6 +6,7 @@ import type {
 } from '@pellux/goodvibes-sdk/platform/knowledge';
 import type { CommandRegistry } from '../command-registry.ts';
 import { openModalCommand, requirePlanManager, requireSessionLineageTracker } from './runtime-services.ts';
+import { togglePlanMode, permissionModeLabel, type PermissionModeValue } from '../../core/permission-mode.ts';
 
 /**
  * Single-token verbs that look like a `/plan` subcommand but are not real ones.
@@ -60,7 +61,8 @@ function formatNextQuestion(question: ProjectPlanningQuestion | undefined): stri
 
 export function registerPlanningRuntimeCommands(registry: CommandRegistry): void {
   registry.register({
-    name: 'plan',
+    name: 'project-plan',
+    aliases: ['planning'],
     description: 'Inspect or seed TUI-owned project planning state',
     usage: '[panel | approve | dismiss | answer <n> <text> | list | show <id> | mode | explain | override <strategy> | status | clear | <planning goal>]',
     argsHint: '[panel|approve|status|<goal>]',
@@ -314,4 +316,29 @@ export function registerPlanningRuntimeCommands(registry: CommandRegistry): void
       );
     },
   });
+
+  // /plan now enters/toggles the SESSION PERMISSION plan mode (read-only
+  // planning posture) — distinct from the project-planning manager above, which
+  // moved to /project-plan (alias /planning). The change goes through the SDK
+  // config surface (permissions.mode), the same value the PermissionManager
+  // reads and Shift+Tab cycles, so plan mode is one concept across surfaces.
+  registry.register({
+    name: 'plan',
+    description: 'Enter or exit plan mode — a read-only planning posture where writes, commands, and network calls are blocked',
+    usage: '[on | off | toggle]',
+    argsHint: '[on|off]',
+    handler(args, ctx) {
+      const configManager = ctx.platform.configManager;
+      const current = configManager.get('permissions.mode') as PermissionModeValue | undefined;
+      const sub = (args[0] ?? 'toggle').toLowerCase();
+      const next: PermissionModeValue =
+        sub === 'on' || sub === 'enter' ? 'plan'
+        : sub === 'off' || sub === 'exit' ? 'prompt'
+        : togglePlanMode(current);
+      configManager.set('permissions.mode', next);
+      ctx.print(next === 'plan'
+        ? '[Permissions] Plan mode ON — read-only: writes, commands, and network calls are blocked until you exit (/plan off or Shift+Tab).'
+        : `[Permissions] Plan mode OFF — mode: ${permissionModeLabel(next)}.`);
+    },
+  });
 }