@pellux/goodvibes-tui 1.13.1 → 1.14.0

package/src/permissions/prompt.ts

@@ -4,6 +4,7 @@ import type { PermissionCategory, PermissionRequestAnalysis } from '@pellux/good
 import { buildPermissionApprovalBrief, getDisplayArg } from '@pellux/goodvibes-sdk/platform/permissions';
 import { DIFF_TONES, UI_TONES } from '../renderer/ui-primitives.ts';
 import type { HunkSelectionState } from './hunk-selection.ts';
+import { readSandboxAskAnnotation } from './sandbox-exec-gate.ts';
 export { buildPendingPermissionExtras } from './hunk-selection.ts';
 
 import type { PermissionPromptRequest, PermissionPromptDecision, PermissionRequestHandler, PermissionRequest } from '@pellux/goodvibes-sdk/platform/permissions';
@@ -87,6 +88,24 @@ function categoryVerb(category: PermissionCategory): string {
  * cannot drift apart (Risk 2 — main.ts's render loop reserves viewport
  * space from getPromptHeight *before* the real render happens).
  */
+/**
+ * The optional sandbox model-judgment tier (see sandbox-judgment.ts in the
+ * SDK) annotates an escalation ask by pushing one string — verbatim
+ * "model judgment: looks safe because…" / "model judgment: flags risk
+ * because…" — onto `analysis.reasons`, alongside the sandbox-boundary and
+ * policy reasons. Pulled out here so it gets its own clearly-labeled row
+ * instead of blending into the generic Review bullets, where the truncation
+ * to 2 reasons could silently cut it (it is typically the LAST reason
+ * pushed, after the boundary line and any policy reasons).
+ */
+const MODEL_JUDGMENT_PREFIX = 'model judgment:';
+
+function extractModelJudgmentAnnotation(reasons: readonly string[]): { annotation: string | undefined; rest: string[] } {
+  const idx = reasons.findIndex((r) => r.toLowerCase().startsWith(MODEL_JUDGMENT_PREFIX));
+  if (idx === -1) return { annotation: undefined, rest: [...reasons] };
+  return { annotation: reasons[idx], rest: [...reasons.slice(0, idx), ...reasons.slice(idx + 1)] };
+}
+
 function hunkListRowCount(hunkState: HunkSelectionState): number {
   return Math.min(hunkState.hunks.length, MAX_VISIBLE_HUNKS) + 2;
 }
@@ -153,24 +172,57 @@ export class PermissionPromptUI {
     return scope === undefined || scope === 'local' || scope === 'project';
   }
 
+  /**
+   * The exact session-scoped permission rule that pressing [A] ("Allow always
+   * this session") will remember. Mirrors the SDK PermissionManager's
+   * getApprovalKey (`<tool>:<path>` when a path arg exists, `<tool>:<command>`
+   * for a command arg, else the bare `<tool>`), so the preview shown to the
+   * user before they choose is the exact key that gets written. Kept in sync
+   * with that SDK function by construction.
+   */
+  static rememberScopeKey(request: PermissionPromptRequest): string {
+    const args = request.args ?? {};
+    if (typeof args.path === 'string' && args.path.length > 0) return `${request.tool}:${args.path}`;
+    if (typeof args.command === 'string' && args.command.length > 0) return `${request.tool}:${args.command}`;
+    return request.tool;
+  }
+
+  /** The one-line preview text for what [A] remembers, truncated to the width. */
+  private static rememberPreviewText(request: PermissionPromptRequest, width: number): string {
+    const key = this.rememberScopeKey(request);
+    const prefix = '   Remembers : [A] allows "';
+    const suffix = '" for this session';
+    const budget = Math.max(6, width - prefix.length - suffix.length);
+    const shown = key.length > budget ? `...${key.slice(-(budget - 3))}` : key;
+    return `${prefix}${shown}${suffix}`;
+  }
+
   static getPromptHeight(
     request: PermissionPromptRequest,
     hunkState?: HunkSelectionState,
     detailsExpanded = false,
+    requestedBy?: string,
   ): number {
-    // Condensed low-risk card: top separator, title, summary, choices, bottom
-    // separator — see createPromptLines' condensed branch (must stay in sync).
-    if (this.isCondensed(request, hunkState, detailsExpanded)) return 5;
+    // Attribution line (only when known) + the always-present remember-scope
+    // preview line are added to BOTH card shapes; keep in sync with
+    // createPromptLines. A hunk-selection prompt has no single [A] remember key,
+    // so the preview line is suppressed there (see createPromptLines).
+    const attributionLines = requestedBy ? 1 : 0;
+    const previewLines = hunkState ? 0 : 1;
+    // Condensed low-risk card: top separator, title, [attribution], [preview],
+    // summary, choices, bottom separator — see createPromptLines' condensed branch.
+    if (this.isCondensed(request, hunkState, detailsExpanded)) return 5 + attributionLines + previewLines;
     const analysis = this.fallbackAnalysis(request);
-    const reasonLines = Math.min(2, Math.max(1, analysis.reasons.length));
-    const extraLines = (analysis.host ? 1 : 0) + (analysis.surface ? 1 : 0) + (analysis.sideEffects && analysis.sideEffects.length > 0 ? 1 : 0);
+    const { annotation: judgmentAnnotation, rest: reasonsMinusJudgment } = extractModelJudgmentAnnotation(analysis.reasons);
+    const reasonLines = Math.min(2, Math.max(1, reasonsMinusJudgment.length));
+    const extraLines = (analysis.host ? 1 : 0) + (analysis.surface ? 1 : 0) + (analysis.sideEffects && analysis.sideEffects.length > 0 ? 1 : 0) + (readSandboxAskAnnotation(request) ? 1 : 0) + (judgmentAnnotation ? 1 : 0);
     const hunkLines = hunkState ? hunkListRowCount(hunkState) : 0;
     // Base 12 counted a single arg line; the Path field now spans `pathRows`
     // lines and the full card adds one raw-args row (2a reachability), so the
     // arg allotment becomes pathRows + 1 → base 12 + pathRows (12 already
     // included one of those). See createPromptLines' full branch.
     const pathRows = this.pathRowTexts(this.resolvedTargets(request), 999).length;
-    return 12 + pathRows + reasonLines + extraLines + hunkLines;
+    return 12 + pathRows + reasonLines + extraLines + hunkLines + attributionLines + previewLines;
   }
 
   /** Returns the key argument to display for a given tool invocation. */
@@ -205,6 +257,7 @@ export class PermissionPromptUI {
     request: PermissionRequest,
     hunkState?: HunkSelectionState,
     detailsExpanded = false,
+    requestedBy?: string,
   ): Line[] {
     const lines: Line[] = [];
     const { tool, args, category } = request;
@@ -217,6 +270,19 @@ export class PermissionPromptUI {
     const TEXT   = '252';
     const DIM    = '244';
 
+    // Attribution line (which agent/process is asking) and the remember-scope
+    // preview line ([A] writes exactly this key). Both are shared by the
+    // condensed and full cards; the preview is suppressed for a hunk-selection
+    // prompt, which has no single whole-request [A] remember key.
+    const pushAttribution = (): void => {
+      if (!requestedBy) return;
+      lines.push(UIFactory.stringToLine(`   Requested by: ${requestedBy}`.padEnd(width), width, { fg: DIM }));
+    };
+    const pushRememberPreview = (): void => {
+      if (hunkState) return;
+      lines.push(UIFactory.stringToLine(this.rememberPreviewText(request, width).padEnd(width), width, { fg: DIM }));
+    };
+
     const maxArgLen = Math.max(10, width - 16);
     const pathRows = this.pathRowTexts(this.resolvedTargets(request), maxArgLen);
 
@@ -225,9 +291,11 @@ export class PermissionPromptUI {
     if (this.isCondensed(request, hunkState, detailsExpanded)) {
       lines.push(UIFactory.stringToLine('─'.repeat(width), width, { fg: ACCENT, dim: true }));
       lines.push(UIFactory.stringToLine(` [${label}] ${brief.title} `.padEnd(width), width, { fg: WARN, bold: true }));
+      pushAttribution();
       const scopeText = analysis.blastRadius ? ` (${analysis.blastRadius})` : '';
       const summaryLine = `   ${categoryVerb(category)} → ${pathRows[0]}${scopeText}`;
       lines.push(UIFactory.stringToLine(summaryLine.padEnd(width), width, { fg: TEXT }));
+      pushRememberPreview();
       lines.push(UIFactory.stringToLine(
         `   [Y] Allow once    [A] Allow always (session)    [N] Deny    [d] details`.padEnd(width),
         width, { fg: ACCENT, bold: true }));
@@ -243,6 +311,9 @@ export class PermissionPromptUI {
     const titleLine = ` [${label}] ${titleText} `;
     lines.push(UIFactory.stringToLine(titleLine.padEnd(width), width, { fg: WARN, bold: true }));
 
+    // Requester attribution (which agent/process raised this request).
+    pushAttribution();
+
     // Tool name row
     const toolLine = `   Tool      : ${tool}`;
     lines.push(UIFactory.stringToLine(toolLine.padEnd(width), width, { fg: TEXT }));
@@ -275,6 +346,20 @@ export class PermissionPromptUI {
       lines.push(UIFactory.stringToLine(hostLine.padEnd(width), width, { fg: DIM }));
     }
 
+    // Sandbox escalation row: when the sandbox-aware exec gate turned an
+    // auto-allow into an ask because the boundary-safe command still needs host
+    // access, name what it wants ("wants network …"). The escalation text is the
+    // SDK policy's, verbatim — this row only surfaces it.
+    const sandboxAnnotation = readSandboxAskAnnotation(request);
+    if (sandboxAnnotation && sandboxAnnotation.sandboxEscalations.length > 0) {
+      const escalations = sandboxAnnotation.sandboxEscalations.join('; ');
+      const maxSandboxLen = Math.max(10, width - 16);
+      const truncatedSandbox =
+        escalations.length > maxSandboxLen ? `${escalations.slice(0, maxSandboxLen - 3)}...` : escalations;
+      const sandboxLine = `   Sandbox   : ${truncatedSandbox}`;
+      lines.push(UIFactory.stringToLine(sandboxLine.padEnd(width), width, { fg: WARN }));
+    }
+
     const summary = analysis.summary.length > width - 16
       ? `${analysis.summary.slice(0, Math.max(0, width - 19))}...`
       : analysis.summary;
@@ -293,7 +378,20 @@ export class PermissionPromptUI {
       lines.push(UIFactory.stringToLine(effectsLine.padEnd(width), width, { fg: DIM }));
     }
 
-    for (const reason of analysis.reasons.slice(0, 2)) {
+    // Model-judgment annotation: gets its own clearly-labeled row (never
+    // subject to the Review truncation below) so a `sandbox-model-judgment`
+    // verdict — "model judgment: looks safe because…" / "flags risk because…"
+    // — is never silently cut. See extractModelJudgmentAnnotation.
+    const { annotation: judgmentAnnotation, rest: reasonsMinusJudgment } = extractModelJudgmentAnnotation(analysis.reasons);
+    if (judgmentAnnotation) {
+      const maxJudgmentLen = Math.max(10, width - 16);
+      const truncatedJudgment =
+        judgmentAnnotation.length > maxJudgmentLen ? `${judgmentAnnotation.slice(0, maxJudgmentLen - 3)}...` : judgmentAnnotation;
+      const judgmentLine = `   Judgment  : ${truncatedJudgment}`;
+      lines.push(UIFactory.stringToLine(judgmentLine.padEnd(width), width, { fg: ACCENT, bold: true }));
+    }
+
+    for (const reason of reasonsMinusJudgment.slice(0, 2)) {
       const maxReasonLen = Math.max(10, width - 16);
       const truncatedReason =
         reason.length > maxReasonLen ? `${reason.slice(0, maxReasonLen - 3)}...` : reason;
@@ -352,6 +450,9 @@ export class PermissionPromptUI {
       lines.push(UIFactory.stringToLine(trailerLine.padEnd(width), width, { fg: DIM }));
     }
 
+    // Remember-scope preview: exactly what [A] will write (omitted for hunk mode).
+    pushRememberPreview();
+
     // Choices row. A condensable card shown in full is the expanded form, so it
     // offers `[d]` to collapse back; other full cards omit the details toggle.
     const collapseHint = this.isCondensed(request, hunkState, false) ? '    [d] hide details' : '';

package/src/permissions/sandbox-exec-gate.ts

@@ -0,0 +1,162 @@
+/**
+ * sandbox-exec-gate.ts — sandbox-aware layer over the exec approval ask.
+ *
+ * The per-command exec sandbox already RUNS boundary-safe commands inside a
+ * bubblewrap boundary (the SDK exec tool's runner half). This is the APPROVAL
+ * half: when the base permission policy would prompt ("ask") for an exec, and
+ * the sandbox is genuinely active, a command that runs entirely inside the OS
+ * boundary with no host-access need should auto-allow instead of prompting —
+ * and a command that still needs host access should surface as an explicit ask
+ * that NAMES what it wants ("wants network …", "wants host privilege
+ * escalation").
+ *
+ * The decision is the SDK's `decideSandboxedExec` — never re-implemented here.
+ * This module only (a) reads the live sandbox posture, (b) extracts the exec
+ * command(s) from the request, (c) maps the SDK decision onto the existing ask
+ * callback: allow → approve without prompting; ask → attach the named
+ * escalations to the request so the approval card renders them, then delegate to
+ * the underlying ask. Non-exec requests, and any request while the sandbox is
+ * inactive, pass through byte-for-byte unchanged.
+ *
+ * This runs INSIDE the permission machinery's ask layer (like trustGatedAsk), so
+ * it composes with the real layer chain and is only ever consulted for execs the
+ * base policy already resolved to "ask" — it can never turn a deny into an allow,
+ * and the frozen catastrophic block is untouched.
+ */
+import { decideSandboxedExec } from '@pellux/goodvibes-sdk/platform/runtime/permissions/sandbox-policy';
+import { detectSandboxAvailability, probeSandboxHost, type SandboxAvailability } from '@pellux/goodvibes-sdk/platform/tools/exec/sandbox';
+import type {
+  PermissionPromptRequest,
+  PermissionPromptDecision,
+} from '@pellux/goodvibes-sdk/platform/permissions';
+import type { ConfigManager } from '@pellux/goodvibes-sdk/platform/config';
+import type { FeatureFlagManager } from '@/runtime/index.ts';
+import { readSandboxExecList, SANDBOX_EGRESS_ALLOWLIST_CONFIG_KEY } from '../input/sandbox-exec-config.ts';
+
+type AskCallback = (request: PermissionPromptRequest) => Promise<PermissionPromptDecision>;
+
+/**
+ * TUI-local metadata the gate attaches to an exec ask so the approval card can
+ * render the sandbox posture and the named escalations. Carried as extra own
+ * properties on the request object (they survive the broker → local-prompt
+ * spread); the renderer reads them defensively.
+ */
+export interface SandboxAskAnnotation {
+  /** True when the command(s) will run inside the boundary. */
+  readonly sandboxed: boolean;
+  /** Named host-access needs to show as the ask's escalations (from the SDK policy). */
+  readonly sandboxEscalations: readonly string[];
+}
+
+export interface SandboxExecAskDeps {
+  /** The graduation-gated `exec-sandbox` feature flag state (read live). */
+  readonly isSandboxFeatureEnabled: () => boolean;
+  /** The `sandbox.enabled` config switch (read live). */
+  readonly isSandboxConfigEnabled: () => boolean;
+  /** The `sandbox.egressAllowlist` command base names (read live). */
+  readonly readEgressAllowlist: () => readonly string[];
+  /**
+   * Honest host availability of the exec sandbox backend. Probing the host spawns
+   * bwrap, so the caller passes a memoized probe — invoked at most once, and only
+   * when an exec ask actually arrives while the feature + config are on.
+   */
+  readonly detectAvailability: () => SandboxAvailability;
+}
+
+/**
+ * Build the gate's live-reading dependencies from the runtime's config + feature
+ * flags. The host probe (a bwrap spawn) is deferred to first use inside
+ * createSandboxExecAsk, so the default path stays zero-cost until an exec ask
+ * actually arrives with the sandbox turned on.
+ */
+export function sandboxExecAskDepsFromRuntime(
+  configManager: Pick<ConfigManager, 'get' | 'getCategory'>,
+  featureFlags: Pick<FeatureFlagManager, 'isEnabled'>,
+): SandboxExecAskDeps {
+  return {
+    isSandboxFeatureEnabled: () => featureFlags.isEnabled('exec-sandbox'),
+    isSandboxConfigEnabled: () => Boolean(configManager.getCategory('sandbox').enabled),
+    readEgressAllowlist: () => readSandboxExecList(configManager, SANDBOX_EGRESS_ALLOWLIST_CONFIG_KEY),
+    detectAvailability: () => detectSandboxAvailability(probeSandboxHost()),
+  };
+}
+
+/** Pull the shell command string(s) out of an exec request's args. */
+export function extractExecCommands(request: PermissionPromptRequest): string[] {
+  const args = request.args ?? {};
+  const out: string[] = [];
+  if (Array.isArray(args.commands)) {
+    for (const entry of args.commands) {
+      if (typeof entry === 'string') out.push(entry);
+      else if (entry && typeof entry === 'object' && typeof (entry as Record<string, unknown>).cmd === 'string') {
+        out.push((entry as Record<string, string>).cmd);
+      }
+    }
+  }
+  if (typeof args.command === 'string') out.push(args.command);
+  if (typeof args.cmd === 'string') out.push(args.cmd);
+  return out.filter((c) => c.length > 0);
+}
+
+/** True for the shell-command tool whose asks the sandbox policy can relax. */
+function isExecRequest(request: PermissionPromptRequest): boolean {
+  return request.category === 'execute' && request.tool === 'exec';
+}
+
+/**
+ * Wrap the permission machinery's ask callback with the sandbox-aware exec
+ * policy. Only exec asks are considered; everything else delegates unchanged.
+ */
+export function createSandboxExecAsk(deps: SandboxExecAskDeps, ask: AskCallback): AskCallback {
+  let cachedAvailability: SandboxAvailability | null = null;
+  const availability = (): SandboxAvailability => {
+    if (cachedAvailability === null) cachedAvailability = deps.detectAvailability();
+    return cachedAvailability;
+  };
+
+  return (request) => {
+    if (!isExecRequest(request)) return ask(request);
+    const commands = extractExecCommands(request);
+    if (commands.length === 0) return ask(request);
+
+    // The sandbox is genuinely active only when the feature flag AND the config
+    // switch are on AND the host can actually provide a boundary.
+    const featureAndConfig = deps.isSandboxFeatureEnabled() && deps.isSandboxConfigEnabled();
+    const sandboxActive = featureAndConfig && availability().available;
+    if (!sandboxActive) return ask(request);
+
+    const egressAllowlist = deps.readEgressAllowlist();
+    const decisions = commands.map((command) =>
+      decideSandboxedExec({ command, sandboxActive: true, egressAllowlist, baseEffectWhenNotSandboxed: 'ask' }),
+    );
+
+    // A batch auto-allows only when EVERY command is boundary-safe. If any needs
+    // host access, the whole ask surfaces with the union of named escalations.
+    if (decisions.every((decision) => decision.effect === 'allow')) {
+      return Promise.resolve({ approved: true });
+    }
+
+    const escalations = dedupe(decisions.flatMap((decision) => decision.escalations));
+    return ask(annotateExecAsk(request, { sandboxed: true, sandboxEscalations: escalations }));
+  };
+}
+
+function dedupe(values: readonly string[]): string[] {
+  return [...new Set(values)];
+}
+
+/** Attach the sandbox annotation to a copy of the request (never mutate the original). */
+function annotateExecAsk(
+  request: PermissionPromptRequest,
+  annotation: SandboxAskAnnotation,
+): PermissionPromptRequest {
+  return Object.assign({}, request, annotation);
+}
+
+/** Read the sandbox annotation off a request, if the gate attached one. */
+export function readSandboxAskAnnotation(request: unknown): SandboxAskAnnotation | null {
+  if (!request || typeof request !== 'object') return null;
+  const candidate = request as Partial<SandboxAskAnnotation>;
+  if (candidate.sandboxed !== true || !Array.isArray(candidate.sandboxEscalations)) return null;
+  return { sandboxed: true, sandboxEscalations: candidate.sandboxEscalations };
+}

package/src/renderer/settings-modal-helpers.ts

@@ -28,6 +28,9 @@ export function formatValue(entry: SettingEntry): string {
   if (typeof val === 'boolean') return val ? 'true' : 'false';
   if (typeof val === 'string' && isSecretConfigKey(entry.setting.key)) return maskSecretValue(val);
   if (typeof val === 'string' && val === '') return '(empty)';
+  // Array-backed settings (e.g. worktree.setup.commands) display as a
+  // comma-separated list, matching how they're edited (see worktree-setup-config.ts).
+  if (Array.isArray(val)) return val.length > 0 ? val.join(', ') : '(empty)';
   return String(val);
 }
 
@@ -57,6 +60,7 @@ export const CATEGORY_LABELS: Record<(typeof SETTINGS_CATEGORIES)[number], strin
   subscriptions: 'Subscriptions',
   behavior: 'Behavior',
   storage: 'Storage',
+  atRest: 'Data at Rest',
   permissions: 'Permissions',
   orchestration: 'Orchestration',
   planner: 'Planner',
@@ -70,10 +74,12 @@ export const CATEGORY_LABELS: Record<(typeof SETTINGS_CATEGORIES)[number], strin
   web: 'Web',
   batch: 'Batch',
   automation: 'Automation',
+  checkin: 'Check-in',
   watchers: 'Watchers',
   runtime: 'Runtime',
   telemetry: 'Telemetry',
   cache: 'Cache',
+  diagnostics: 'Diagnostics',
   mcp: 'MCP',
   sandbox: 'Sandbox',
   surfaces: 'Surfaces',
@@ -81,8 +87,16 @@ export const CATEGORY_LABELS: Record<(typeof SETTINGS_CATEGORIES)[number], strin
   release: 'Release',
   danger: 'Danger',
   tools: 'Tools',
-  flags: 'Feature Flags',
+  flags: 'Advanced Features',
   network: 'Network',
+  relay: 'Relay',
+  learning: 'Learning',
+  fetch: 'Fetch Safety',
+  agents: 'Agents & Context',
+  security: 'Token Security',
+  integrations: 'Integration Delivery',
+  policy: 'Policy-as-Code',
+  notifications: 'Notifications',
 };
 
 const SETTING_LABELS: Partial<Record<string, string>> = {
@@ -95,6 +109,9 @@ const SETTING_LABELS: Partial<Record<string, string>> = {
   'behavior.returnContextMode': 'Return Context',
   'behavior.guidanceMode': 'Guidance Mode',
   'storage.secretPolicy': 'Secret Policy',
+  'permissions.mode': 'Permission Mode',
+  'permissions.backgroundAgents': 'Background Agents',
+  'diagnostics.postEdit': 'Post-Edit Diagnostics',
   'sandbox.vmBackend': 'Sandbox Backend',
   'sandbox.qemuBinary': 'QEMU Binary',
   'sandbox.qemuImagePath': 'QEMU Image',
@@ -154,6 +171,9 @@ const SETTING_LABELS: Partial<Record<string, string>> = {
 };
 
 export function getSettingLabel(entry: SettingEntry): string {
+  // Feature-unit toggle headers carry the flag's human name, not the raw
+  // `featureFlags.<id>` key tail.
+  if (entry.flag) return entry.flag.flag.name;
   return SETTING_LABELS[entry.setting.key] ?? entry.setting.key.replace(/^[^.]+\./, '');
 }
 

package/src/renderer/settings-modal.ts

@@ -30,6 +30,7 @@ const CATEGORY_INFO: Record<SettingsCategory, string> = {
   subscriptions: 'Provider subscription login state and routing posture. Active sessions can be reviewed or signed out here; API keys remain managed through secrets.',
   behavior: 'Day-to-day shell behavior: approval posture, compaction, history, guidance, notifications, stale-context warnings, return context, and Human-in-the-Loop mode.',
   storage: 'Local storage posture, including secret storage policy and maximum artifact size for knowledge/home graph/document ingestion.',
+  atRest: 'Data-at-rest policy for the on-disk transcript journal and execution ledger: whether secret/credential patterns are redacted at write time, and the age/size caps that trigger pruning.',
   permissions: 'Permission mode and tool-class policy. These settings decide whether the shell prompts before read/write/exec/network/agent actions.',
   orchestration: 'Agent orchestration limits and recursion controls.',
   planner: 'How /workstream decomposes a goal into work items: agent-driven decomposition (with heuristic fallback) or the forced heuristic path, plus the planning agent\'s turn, token, and wall-clock bounds.',
@@ -43,10 +44,12 @@ const CATEGORY_INFO: Record<SettingsCategory, string> = {
   web: 'Browser surface settings for the local or network web UI.',
   batch: 'Batch execution settings, including local vs Cloudflare queue behavior.',
   automation: 'Scheduled and automated run settings, concurrency, timeout, catch-up, cooldown, and retention behavior.',
+  checkin: 'Proactive check-in: on a cadence, a briefing is judged and you are contacted only when something warrants it. Off by default; every run — scheduled or manual — leaves a receipt (see /checkin) recording whether it stayed quiet, delivered a message, or was skipped.',
   watchers: 'File/process watcher heartbeat, polling, and recovery-window behavior.',
   runtime: 'Runtime guardrails such as companion chat limiter and event bus listener caps.',
   telemetry: 'Telemetry payload policy.',
   cache: 'Provider and model cache behavior, TTL, and hit-rate monitoring.',
+  diagnostics: 'Post-edit diagnostics: whether the shell runs language diagnostics on a file after the model edits or writes it, surfacing new problems inline.',
   mcp: 'MCP server trust and scope review. Trust changes can expose local files, tools, databases, browsers, or remote automation depending on the server.',
   sandbox: 'Isolation strategy for REPL, MCP, Windows, and QEMU-backed execution. Use these settings to separate risky tools from the host shell.',
   surfaces: 'External app surfaces such as Slack, Discord, ntfy, Home Assistant, Telegram, webhooks, chat bridges, and messaging providers.',
@@ -54,8 +57,16 @@ const CATEGORY_INFO: Record<SettingsCategory, string> = {
   release: 'Release-channel preference.',
   danger: 'High-impact switches for daemon and HTTP listener behavior. These are operational overrides, not normal preferences.',
   tools: 'Tool LLM and helper model routing. Empty provider/model values inherit the active chat route unless a specific helper/tool route is set.',
-  flags: 'Feature flags are SDK runtime gates. They are separate from normal config keys because they enable or disable staged runtime behavior.',
+  flags: 'Advanced feature toggles with no tuning knobs — internal and startup-gated runtime gates. Features that DO have config sit as units (toggle + settings) in their topical category, not here.',
   network: 'Combined network view for daemon control-plane, HTTP listener, browser web surface, and general outbound network settings.',
+  fetch: 'Fetch response sanitization and host trust tiers for the fetch tool: sanitize mode plus default trusted/blocked host lists. Gated by the Fetch Response Sanitization feature.',
+  agents: 'Sub-agent context-window awareness and per-turn passive knowledge/code injection: token budget, relevance floor, code-chunk limit, and the compaction threshold. Gated by the agent context/injection features.',
+  security: 'API token scope and rotation auditing: rotation cadence, warning lead time, and whether overdue/over-scoped tokens are blocked or only reported. Gated by the Token Scope and Rotation Audit feature.',
+  integrations: 'Integration delivery reliability (Slack/Discord/webhook): retry counts, backoff bounds, dead-letter queue size, and SLO enforcement. Gated by the Integration Delivery SLO feature.',
+  policy: 'Policy-as-code bundle loading: where the startup policy bundle is loaded from and its file path. Gated by the Policy-as-Code feature.',
+  notifications: 'Notification router burst-suppression tuning: burst window, threshold, and cooldown. Gated by the Adaptive Notification Suppression feature.',
+  relay: 'Outbound zero-knowledge relay reachability, for reaching this daemon from outside the LAN without opening an inbound port. Off by default; also gated by the relay-connect feature flag. The relay operator sees only ciphertext and connection metadata — self-host your own relay for full control.',
+  learning: 'Idle-time memory consolidation: merging duplicate standing memory records and decaying/archiving stale ones. Off by default — nothing runs until enabled.',
 };
 
 const ENUM_VALUE_DESCRIPTIONS: Record<string, Record<string, string>> = {
@@ -75,10 +86,20 @@ const ENUM_VALUE_DESCRIPTIONS: Record<string, Record<string, string>> = {
     guided: 'Provide more explanation and next-step context during configuration and operations.',
   },
   'permissions.mode': {
-    prompt: 'Ask before powerful or risky actions according to tool policy.',
-    'allow-all': 'Allow actions without prompting. This is fast but removes an important safety gate.',
+    prompt: 'Normal: ask before powerful or risky actions according to tool policy.',
+    plan: 'Plan mode: read-only planning posture — writes, commands, and network calls are blocked so the model can plan without changing anything. Toggle with /plan or Shift+Tab.',
+    'accept-edits': 'Accept edits: file writes and edits are auto-approved, but exec, network, and escalations are still gated.',
+    'allow-all': 'Auto: allow all actions without prompting. Fast, but removes an important safety gate.',
     custom: 'Use per-tool-class permission settings from the rows below.',
   },
+  'permissions.backgroundAgents': {
+    inherit: 'Background and subagent tool calls run through the SAME session permission mode as foreground work.',
+    'allow-all': 'Background and subagent tool calls are exempt from prompting (auto-approved) even when foreground work is gated.',
+  },
+  'diagnostics.postEdit': {
+    on: 'After the model edits or writes a file, run language diagnostics on it and surface any new problems.',
+    off: 'Do not run diagnostics automatically after edits.',
+  },
   'storage.secretPolicy': {
     preferred_secure: 'Use secure secret storage when available, with supported fallback behavior.',
     require_secure: 'Require secure secret storage and reject plaintext fallback.',
@@ -213,6 +234,9 @@ function buildFlagContext(entry: FlagEntry | null): string[] {
     `Default: ${entry.flag.defaultState}`,
     `Tier: ${entry.flag.tier}`,
     `Runtime toggleable: ${entry.flag.runtimeToggleable ? 'yes' : 'no'}`,
+    ...(entry.pendingRestart
+      ? [`Pending restart: saved as ${entry.persistedState}; effective state stays ${entry.state} until the next launch.`]
+      : []),
     '',
     entry.flag.description,
     ...(entry.state === 'killed' && entry.flag.killReason ? ['', `Kill reason: ${entry.flag.killReason}`] : []),
@@ -302,15 +326,16 @@ function buildContextLines(modal: SettingsModal, width: number): string[] {
     `${CATEGORY_LABELS[category]} configuration`,
   ];
 
-  if (category === 'flags') {
-    lines.push(...buildFlagContext(modal.getSelectedFlag()));
-  } else if (category === 'mcp') {
+  if (category === 'mcp') {
     lines.push(...buildMcpContext(modal, modal.getSelectedMcp()));
   } else if (category === 'subscriptions') {
     lines.push(...buildSubscriptionContext(modal, modal.getSelectedSubscription()));
   } else {
     const selected = modal.getSelected();
-    if (selected) lines.push(...buildSettingContext(modal, selected));
+    // A feature-unit toggle header shows flag context (tier, default, impact);
+    // its config sub-options and plain settings show the setting context.
+    if (selected?.flag) lines.push(...buildFlagContext(selected.flag));
+    else if (selected) lines.push(...buildSettingContext(modal, selected));
     else lines.push('No setting is selected in this category.');
   }
 
@@ -328,9 +353,9 @@ function buildContextLines(modal: SettingsModal, width: number): string[] {
 }
 
 function categoryItemCount(modal: SettingsModal, category: SettingsCategory): number {
-  if (category === 'flags') return modal.flagEntries.length;
   if (category === 'mcp') return modal.mcpEntries.length;
   if (category === 'subscriptions') return modal.subscriptionEntries.length;
+  // 'flags' (Advanced Features) now flows through the normal group path.
   return modal.groups.get(category)?.length ?? 0;
 }
 
@@ -404,39 +429,47 @@ function renderSettingRows(modal: SettingsModal, width: number, height: number):
     const entry = items[index]!;
     const selected = index === selectedIndex;
     const marker = selected ? (modal.focusPane === 'settings' ? GLYPHS.navigation.selected : '•') : entry.isDefault ? ' ' : '◇';
-    const value = currentSettingValue(modal, entry, selected);
-    const source = `${entry.effectiveSource ?? 'default'}${entry.locked ? ' locked' : ''}${entry.conflict ? ' conflict' : ''}`;
-    const label = getSettingLabel(entry);
-    rows.push(`${marker} ${padDisplay(label, keyWidth)}  ${padDisplay(value, valueWidth)}  ${padDisplay(entry.setting.type, typeWidth)}  ${padDisplay(source, sourceWidth)}  ${padDisplay(formatDefaultValue(entry.setting.default), defaultWidth)}`);
+    rows.push(renderSettingTableRow(modal, entry, selected, marker, keyWidth, valueWidth, typeWidth, sourceWidth, defaultWidth));
   }
 
   if (window.end < items.length) rows.push(`${GLYPHS.navigation.moreBelow} ${items.length - window.end} more setting(s) below`);
   return rows.slice(0, height);
 }
 
-function renderFlagRows(modal: SettingsModal, width: number, height: number): string[] {
-  const rows: string[] = [];
-  const items = modal.flagEntries;
-  if (items.length === 0) return ['No feature flags registered.'];
-  const selectedIndex = clamp(modal.selectedIndex, 0, items.length - 1);
-  const nameWidth = clamp(Math.floor(width * 0.40), 24, 58);
-  const stateWidth = 10;
-  const tierWidth = 6;
-  const runtimeWidth = 9;
-  const defaultWidth = 9;
-  const idWidth = Math.max(12, width - nameWidth - stateWidth - tierWidth - runtimeWidth - defaultWidth - 14);
-  rows.push(`  ${padDisplay('Feature Flag', nameWidth)}  ${padDisplay('State', stateWidth)}  ${padDisplay('Tier', tierWidth)}  ${padDisplay('Runtime', runtimeWidth)}  ${padDisplay('Default', defaultWidth)}  ${padDisplay('ID', idWidth)}`);
-  const visibleCount = Math.max(1, height - 2);
-  const window = stableWindow(items.length, selectedIndex, visibleCount);
-  if (window.start > 0) rows.push(`${GLYPHS.navigation.moreAbove} ${window.start} more flag(s) above`);
-  for (let index = window.start; index < window.end; index += 1) {
-    const entry = items[index]!;
-    const selected = index === selectedIndex;
-    const marker = selected ? (modal.focusPane === 'settings' ? GLYPHS.navigation.selected : '•') : ' ';
-    rows.push(`${marker} ${padDisplay(entry.flag.name, nameWidth)}  ${padDisplay(entry.state, stateWidth)}  ${padDisplay(String(entry.flag.tier), tierWidth)}  ${padDisplay(entry.flag.runtimeToggleable ? 'yes' : 'restart', runtimeWidth)}  ${padDisplay(entry.flag.defaultState, defaultWidth)}  ${padDisplay(entry.flag.id, idWidth)}`);
+/**
+ * One settings-table row. A feature-unit toggle header (entry.flag) shows the
+ * flag name, its live state, tier/toggleability, and default state. A config
+ * sub-option owned by a feature unit (entry.ownerFlagId) is indented under its
+ * header. Everything else renders as a plain setting row.
+ */
+function renderSettingTableRow(
+  modal: SettingsModal,
+  entry: SettingEntry,
+  selected: boolean,
+  marker: string,
+  keyWidth: number,
+  valueWidth: number,
+  typeWidth: number,
+  sourceWidth: number,
+  defaultWidth: number,
+): string {
+  if (entry.flag) {
+    const { flag, state, pendingRestart, persistedState } = entry.flag;
+    const stateMark = state === 'enabled' ? '●' : state === 'killed' ? '✕' : '○';
+    const label = `${stateMark} ${flag.name}`;
+    const source = `tier ${flag.tier} ${flag.runtimeToggleable ? 'live' : 'restart'}`;
+    // A startup-gated flag toggled this session keeps its effective state and
+    // shows the pending value it will take on restart, so the row never implies
+    // the change already took effect.
+    const value = pendingRestart ? `${state} → ${persistedState} on restart` : state;
+    return `${marker} ${padDisplay(label, keyWidth)}  ${padDisplay(value, valueWidth)}  ${padDisplay('feature', typeWidth)}  ${padDisplay(source, sourceWidth)}  ${padDisplay(flag.defaultState, defaultWidth)}`;
   }
-  if (window.end < items.length) rows.push(`${GLYPHS.navigation.moreBelow} ${items.length - window.end} more flag(s) below`);
-  return rows.slice(0, height);
+  const value = currentSettingValue(modal, entry, selected);
+  const source = `${entry.effectiveSource ?? 'default'}${entry.locked ? ' locked' : ''}${entry.conflict ? ' conflict' : ''}`;
+  // Sub-options of a feature unit are indented under their toggle header so the
+  // "one unit = toggle + its knobs" grouping reads at a glance.
+  const label = entry.ownerFlagId ? `  · ${getSettingLabel(entry)}` : getSettingLabel(entry);
+  return `${marker} ${padDisplay(label, keyWidth)}  ${padDisplay(value, valueWidth)}  ${padDisplay(entry.setting.type, typeWidth)}  ${padDisplay(source, sourceWidth)}  ${padDisplay(formatDefaultValue(entry.setting.default), defaultWidth)}`;
 }
 
 function renderMcpRows(modal: SettingsModal, width: number, height: number): string[] {
@@ -533,7 +566,6 @@ function renderSearchRows(modal: SettingsModal, width: number, height: number):
 
 function renderControlRows(modal: SettingsModal, width: number, height: number): string[] {
   if (modal.searchFocused) return renderSearchRows(modal, width, height);
-  if (modal.currentCategory === 'flags') return renderFlagRows(modal, width, height);
   if (modal.currentCategory === 'mcp') return renderMcpRows(modal, width, height);
   if (modal.currentCategory === 'subscriptions') return renderSubscriptionRows(modal, width, height);
   return renderSettingRows(modal, width, height);
@@ -594,15 +626,9 @@ function footerText(modal: SettingsModal, width: number): string {
       { key: 'Enter', verb: 'Edit trust' },
       { key: 'Esc', verb: 'Close' },
     ]));
-  if (modal.currentCategory === 'flags')
-    return joinHints('Focus feature flags', formatHints([
-      { key: 'Up/Down', verb: 'Flag' },
-      { key: 'Left', verb: 'Categories' },
-      { key: 'Tab', verb: 'Pane' },
-      { key: '/', verb: 'Search' },
-      { key: 'Enter/Space', verb: 'Toggle' },
-      { key: 'Esc', verb: 'Close' },
-    ]));
+  // 'flags' (Advanced Features) and every topical category that now hosts feature
+  // units flow through the default settings footer below — Enter/Space toggles a
+  // feature-unit header exactly as it edits/toggles any setting row.
   // Default settings pane: tier the reset affordances by available width.
   // W<80:  minimal — only the most critical action survives.
   // W<160: compact but still shows both reset affordances.