devflow-kit 2.0.1 → 2.1.0

package/dist/core/flags.js

@@ -1,139 +1,244 @@
 /**
- * Claude Code flag registry.
+ * Claude Code flag registry — typed, extensible mechanism for managing
+ * Claude Code feature flags and settings.
  *
- * Typed, extensible mechanism for managing Claude Code feature flags.
- * Pure functions: applyFlags, stripFlags, getDefaultFlags — no I/O.
+ * Pure functions: applyFlags, stripFlags, getDefaultFlagsRecord — no I/O.
+ *
+ * D14: Typed registry — flags carry kind (boolean|enum|number|string), target
+ * (env|setting), and per-kind defaultValue. Neutral values delete their target
+ * key; active values write the appropriate payload. Number 0 is ACTIVE. Sink
+ * validation via coerceFlagValue (applies PF-023: validate at the convergence
+ * point every caller reaches). applyFlags(settingsJson, FlagsRecord) is the
+ * sole API; init.ts works directly with FlagsRecord (no legacy string[] bridge).
+ */
+// ─── Registry ─────────────────────────────────────────────────────────────────
+// Phase 0 probe findings: see docs/reference/claude-code-flags-probe.md
+/**
+ * Ordered registry of all Claude Code flags managed by devflow.
+ *
+ * IDs are the stable manifest keys (`features.flags` in the devflow manifest).
+ * Array order drives the `--list` table and TUI row order — intentional changes
+ * to order are display changes and should be made deliberately.
+ *
+ * Not every Claude Code env var belongs here. One notable exclusion:
+ *   `CLAUDE_CODE_DISABLE_UNKNOWN_MODEL_WINDOW_ENFORCEMENT` — deliberately
+ *   proxy-owned. It is paired with `ANTHROPIC_BASE_URL` in proxy.ts and its
+ *   lifecycle is coupled to relay enable/disable; strip is handled by
+ *   `stripProxyEnv` (src/cli/commands/proxy.ts). Adding it here would create a
+ *   second owner and double-strip it on uninstall. (mirrors agent-teams note)
  */
 export const FLAG_REGISTRY = [
-    // === Recommended (default ON) ===
+    // ══ Recommended (default ON) ══════════════════════════════════════════════
     {
         id: 'tui',
         label: 'Fullscreen terminal UI',
         description: 'Flicker-free fullscreen rendering',
-        hint: 'Modern fullscreen interface',
-        target: { type: 'setting', key: 'tui', value: 'fullscreen' },
-        defaultEnabled: true,
+        hint: 'Enables fullscreen mode — flicker-free and cursor-stable',
+        blurb: 'fullscreen terminal UI',
+        kind: 'boolean',
+        target: { type: 'setting', key: 'tui' },
+        onPayload: 'fullscreen',
+        recommended: true,
+        defaultValue: true,
     },
     {
         id: 'tool-search',
         label: 'Deferred tool loading',
         description: 'Load tool schemas on demand instead of all at startup',
-        hint: 'Faster startup',
-        target: { type: 'env', key: 'ENABLE_TOOL_SEARCH', value: 'true' },
-        defaultEnabled: true,
+        hint: 'Defers tool schema loading to first use — smaller initial context',
+        blurb: 'deferred tool schema loading',
+        kind: 'boolean',
+        target: { type: 'env', key: 'ENABLE_TOOL_SEARCH' },
+        onPayload: 'true',
+        recommended: true,
+        defaultValue: true,
     },
     {
         id: 'lsp',
         label: 'LSP support',
         description: 'Enable Language Server Protocol integration',
-        hint: 'Code intelligence from your editor',
-        target: { type: 'env', key: 'ENABLE_LSP_TOOL', value: 'true' },
-        defaultEnabled: true,
+        hint: 'Activates LSP tool so Claude can query your editor code intelligence',
+        blurb: 'editor code intelligence',
+        kind: 'boolean',
+        target: { type: 'env', key: 'ENABLE_LSP_TOOL' },
+        onPayload: 'true',
+        recommended: true,
+        defaultValue: true,
     },
     {
         id: 'prompt-caching-1h',
         label: 'Extended prompt cache',
         description: 'Extend prompt cache TTL from 5min to 1h',
-        hint: 'Cheaper long sessions',
-        target: { type: 'env', key: 'ENABLE_PROMPT_CACHING_1H', value: 'true' },
-        defaultEnabled: true,
+        hint: 'Extends cache TTL from 5 min to 1 hr — cheaper long sessions',
+        blurb: '1-hour prompt cache TTL',
+        kind: 'boolean',
+        target: { type: 'env', key: 'ENABLE_PROMPT_CACHING_1H' },
+        onPayload: 'true',
+        recommended: true,
+        defaultValue: true,
     },
     {
         id: 'show-turn-duration',
         label: 'Show turn duration',
         description: 'Display timing info after each turn',
-        hint: 'See how long each response takes',
-        target: { type: 'setting', key: 'showTurnDuration', value: true },
-        defaultEnabled: true,
+        hint: 'Shows wall-clock time for each turn — useful for spotting slow paths',
+        blurb: 'wall-clock time per turn',
+        kind: 'boolean',
+        target: { type: 'setting', key: 'showTurnDuration' },
+        onPayload: true,
+        recommended: true,
+        defaultValue: true,
     },
     {
         id: 'clear-context-on-plan',
         label: 'Clear context on plan accept',
         description: 'Clear context window when accepting a plan',
-        hint: 'Clean slate after planning',
-        target: { type: 'setting', key: 'showClearContextOnPlanAccept', value: true },
-        defaultEnabled: true,
+        hint: 'Clears context on plan accept so implementation starts with full budget',
+        blurb: 'clear context on plan accept',
+        kind: 'boolean',
+        target: { type: 'setting', key: 'showClearContextOnPlanAccept' },
+        onPayload: true,
+        recommended: true,
+        defaultValue: true,
     },
     {
         id: 'disable-bundled-skills',
         label: 'Disable bundled skills',
         description: "Remove Claude Code's built-in skills and workflows (devflow provides its own)",
-        hint: 'Cleaner skill list',
-        target: { type: 'setting', key: 'disableBundledSkills', value: true },
-        defaultEnabled: true,
+        hint: "Removes Claude Code's built-in skills — devflow installs its own set",
+        blurb: 'remove built-in CC skills',
+        kind: 'boolean',
+        target: { type: 'setting', key: 'disableBundledSkills' },
+        onPayload: true,
+        recommended: true,
+        defaultValue: true,
     },
     {
         id: 'pin-sonnet-4-6',
         label: 'Pin Sonnet to 4.6',
         description: 'Pin the default Sonnet model to claude-sonnet-4-6',
-        hint: 'Stable, deterministic Sonnet version',
-        target: { type: 'env', key: 'ANTHROPIC_DEFAULT_SONNET_MODEL', value: 'claude-sonnet-4-6' },
-        defaultEnabled: true,
+        hint: 'Pins Sonnet to 4.6 — stable, deterministic alias across model updates',
+        blurb: 'pin Sonnet to 4.6 model',
+        kind: 'boolean',
+        target: { type: 'env', key: 'ANTHROPIC_DEFAULT_SONNET_MODEL' },
+        onPayload: 'claude-sonnet-4-6',
+        recommended: true,
+        defaultValue: true,
+    },
+    {
+        // Devflow fan-outs routinely exceed the upstream default of 20.
+        // Set to 40 by default so parallel Code/Review/Research waves don't
+        // silently queue. upstreamDefault recorded for display. (applies PF-023 bounds)
+        id: 'max-concurrent-subagents',
+        label: 'Max concurrent subagents',
+        description: 'Maximum number of subagents Claude Code will spawn concurrently',
+        hint: 'Sets concurrent subagent cap; upstream default is 20 — devflow uses 40',
+        blurb: 'parallel subagent cap',
+        kind: 'number',
+        target: { type: 'env', key: 'CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS' },
+        recommended: true,
+        defaultValue: 40,
+        min: 1,
+        max: 100, // devflow sanity bound (applies PF-023)
+        integer: true,
+        upstreamDefault: 20,
     },
-    // === Optional (default OFF) — skip these if you're unsure ===
+    // ══ Optional (default OFF) — skip these if you're unsure ══════════════════
     {
         id: 'brief',
         label: 'Brief output mode',
         description: 'Reduce verbosity of Claude Code output',
-        hint: 'Shorter responses',
-        target: { type: 'env', key: 'CLAUDE_CODE_BRIEF', value: 'true' },
-        defaultEnabled: false,
+        hint: 'Reduces output verbosity — shorter responses, less explanation',
+        blurb: 'shorter, less verbose output',
+        kind: 'boolean',
+        target: { type: 'env', key: 'CLAUDE_CODE_BRIEF' },
+        onPayload: 'true',
+        recommended: false,
+        defaultValue: false,
     },
     {
         id: 'thinking-summaries',
         label: 'Thinking summaries',
         description: 'Show thinking summaries during reasoning',
-        hint: 'See reasoning previews',
-        target: { type: 'setting', key: 'showThinkingSummaries', value: true },
-        defaultEnabled: false,
+        hint: 'Surfaces condensed reasoning previews during extended thinking',
+        blurb: 'condensed reasoning previews',
+        kind: 'boolean',
+        target: { type: 'setting', key: 'showThinkingSummaries' },
+        onPayload: true,
+        recommended: false,
+        defaultValue: false,
     },
     {
         id: 'subprocess-env-scrub',
         label: 'Subprocess env scrub',
         description: 'Strip cloud credentials from subprocesses',
-        hint: 'Security: strip cloud creds from subprocesses',
-        target: { type: 'env', key: 'CLAUDE_CODE_SUBPROCESS_ENV_SCRUB', value: '1' },
-        defaultEnabled: false,
+        hint: 'Strips cloud credentials (AWS, GCP, Azure) from subprocess env',
+        blurb: 'strip cloud credentials',
+        kind: 'boolean',
+        target: { type: 'env', key: 'CLAUDE_CODE_SUBPROCESS_ENV_SCRUB' },
+        onPayload: '1',
+        recommended: false,
+        defaultValue: false,
     },
     {
         id: 'disable-nonessential-traffic',
         label: 'Disable non-essential traffic',
         description: 'Suppress usage metrics telemetry',
-        hint: 'No telemetry',
-        target: { type: 'env', key: 'CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC', value: 'true' },
-        defaultEnabled: false,
+        hint: 'Suppresses usage telemetry sent back to Anthropic',
+        blurb: 'suppress usage telemetry',
+        kind: 'boolean',
+        target: { type: 'env', key: 'CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC' },
+        onPayload: 'true',
+        recommended: false,
+        defaultValue: false,
     },
     {
         id: 'forked-subagents',
         label: 'Forked subagents',
         description: 'Better subagent perf on external builds',
-        hint: 'Faster parallel agents (experimental)',
-        target: { type: 'env', key: 'CLAUDE_CODE_FORK_SUBAGENT', value: '1' },
-        defaultEnabled: false,
+        hint: 'Enables forked subagent model — faster parallel agents (experimental)',
+        blurb: 'faster parallel agents',
+        kind: 'boolean',
+        target: { type: 'env', key: 'CLAUDE_CODE_FORK_SUBAGENT' },
+        onPayload: '1',
+        recommended: false,
+        defaultValue: false,
     },
     {
         id: 'disable-adaptive-thinking',
         label: 'Disable adaptive thinking',
         description: 'Disable adaptive reasoning on Opus/Sonnet 4.6',
-        hint: 'Fixed thinking budget',
-        target: { type: 'env', key: 'CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING', value: 'true' },
-        defaultEnabled: false,
+        hint: 'Disables adaptive thinking budget — fixes compute per turn',
+        blurb: 'fixed compute per turn',
+        kind: 'boolean',
+        target: { type: 'env', key: 'CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING' },
+        onPayload: 'true',
+        recommended: false,
+        defaultValue: false,
     },
     {
         id: 'always-thinking',
         label: 'Always enable thinking',
         description: 'Enable extended thinking by default',
-        hint: 'Thinking on every turn',
-        target: { type: 'setting', key: 'alwaysThinkingEnabled', value: true },
-        defaultEnabled: false,
+        hint: 'Forces extended thinking on every turn, including non-complex ones',
+        blurb: 'extended thinking always',
+        kind: 'boolean',
+        target: { type: 'setting', key: 'alwaysThinkingEnabled' },
+        onPayload: true,
+        recommended: false,
+        defaultValue: false,
     },
     {
         id: 'disable-git-instructions',
         label: 'Disable git instructions',
         description: 'Remove git workflow instructions from system prompt',
-        hint: 'Smaller system prompt',
-        target: { type: 'env', key: 'CLAUDE_CODE_DISABLE_GIT_INSTRUCTIONS', value: 'true' },
-        defaultEnabled: false,
+        hint: 'Removes git workflow from system prompt — saves tokens in each turn',
+        blurb: 'remove git system prompt',
+        kind: 'boolean',
+        target: { type: 'env', key: 'CLAUDE_CODE_DISABLE_GIT_INSTRUCTIONS' },
+        onPayload: 'true',
+        recommended: false,
+        defaultValue: false,
     },
     // NOTE: DISABLE_COMPACT and DISABLE_AUTOUPDATER intentionally omit the CLAUDE_CODE_ prefix —
     // these names are defined by upstream Claude Code and must match exactly.
@@ -141,79 +246,707 @@ export const FLAG_REGISTRY = [
         id: 'disable-compact',
         label: 'Disable auto-compaction',
         description: 'Disable automatic context compaction',
-        hint: 'Keep full context (uses more tokens)',
-        target: { type: 'env', key: 'DISABLE_COMPACT', value: 'true' },
-        defaultEnabled: false,
+        hint: 'Disables auto-compaction — retains full context at the cost of more tokens',
+        blurb: 'retain full context always',
+        kind: 'boolean',
+        target: { type: 'env', key: 'DISABLE_COMPACT' },
+        onPayload: 'true',
+        recommended: false,
+        defaultValue: false,
     },
     {
+        // v2.1.223 semantics: disables the 1M-token context window experiment and
+        // falls back to the standard context budget for the model.
         id: 'disable-1m-context',
         label: 'Disable 1M context window',
-        description: 'Use standard context window instead of extended 1M',
-        hint: 'Use smaller context window',
-        target: { type: 'env', key: 'CLAUDE_CODE_DISABLE_1M_CONTEXT', value: 'true' },
-        defaultEnabled: false,
+        description: 'Disable the 1M-token context window experiment (v2.1.223+)',
+        hint: 'Opts out of the 1M context experiment — uses standard context budget',
+        blurb: 'use standard context budget',
+        kind: 'boolean',
+        target: { type: 'env', key: 'CLAUDE_CODE_DISABLE_1M_CONTEXT' },
+        onPayload: 'true',
+        recommended: false,
+        defaultValue: false,
     },
     {
         id: 'disable-autoupdater',
         label: 'Disable auto-updater',
         description: 'Prevent automatic update checks',
-        hint: 'No automatic updates',
-        target: { type: 'env', key: 'DISABLE_AUTOUPDATER', value: 'true' },
-        defaultEnabled: false,
+        hint: 'Prevents automatic update checks — manage updates manually',
+        blurb: 'manual update management',
+        kind: 'boolean',
+        target: { type: 'env', key: 'DISABLE_AUTOUPDATER' },
+        onPayload: 'true',
+        recommended: false,
+        defaultValue: false,
     },
     {
         id: 'agent-teams',
         label: 'Agent Teams (experimental)',
         description: 'Enable Claude Code experimental Agent Teams',
-        hint: 'Peer agents / teammate mode — experimental',
-        target: { type: 'env', key: 'CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS', value: '1' },
-        defaultEnabled: false,
+        hint: 'Enables peer-agent teammate mode — experimental, may change any release',
+        blurb: 'peer-agent teammate mode',
+        kind: 'boolean',
+        target: { type: 'env', key: 'CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS' },
+        onPayload: '1',
+        recommended: false,
+        defaultValue: false,
         // Note: the legacy `teammateMode:"auto"` settings key is stripped by
         // src/core/teammate-mode-cleanup.ts during uninstall (stripDevflowTeammateModeFromJson).
         // The env var above is the only surface managed by FLAG_REGISTRY for this flag.
     },
+    {
+        // Upstream: restores Todo/TaskCreate tools removed by default in Opus 4.8+,
+        // Sonnet 5+, and Fable 5+. Set to '1' to re-enable.
+        id: 'enable-todo-tools',
+        label: 'Enable todo/task tools',
+        description: 'Restore Todo and TaskCreate tools removed by default in newer models',
+        hint: 'Re-enables Todo/TaskCreate tools on Opus 4.8+ / Sonnet 5+ / Fable 5+',
+        blurb: 'restore Todo/Task tools',
+        kind: 'boolean',
+        target: { type: 'env', key: 'CLAUDE_CODE_ENABLE_TODO_TOOLS' },
+        onPayload: '1',
+        recommended: false,
+        defaultValue: false,
+    },
+    // ── Valued flags (number/enum/string) ────────────────────────────────────
+    {
+        // Domain: unset by default; set only when users want a non-default spawn depth.
+        // upstreamDefault: 3 (recorded for display). PF-023 bounds: max 10.
+        id: 'subagent-spawn-depth',
+        label: 'Max subagent spawn depth',
+        description: 'Maximum depth of nested subagent spawning',
+        hint: 'Caps nested spawn depth; upstream default is 3 — raise only when needed',
+        blurb: 'nested spawn depth limit',
+        kind: 'number',
+        target: { type: 'env', key: 'CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH' },
+        recommended: false,
+        defaultValue: undefined,
+        min: 1,
+        max: 10, // devflow sanity bound (applies PF-023)
+        integer: true,
+        upstreamDefault: 3,
+    },
+    {
+        // Phase 0: domain verified small|medium|large|unrestricted from binary
+        // (4-value cluster at adjacent string offsets, adjacent to Workflows feature text).
+        id: 'workflow-size-guideline',
+        label: 'Workflow size guideline',
+        description: 'Guide Claude on the expected size of workflow plans',
+        hint: 'Hints preferred plan scale: small/medium/large/unrestricted',
+        blurb: 'plan scale hint',
+        kind: 'enum',
+        target: { type: 'setting', key: 'workflowSizeGuideline' },
+        values: ['small', 'medium', 'large', 'unrestricted'],
+        recommended: false,
+        defaultValue: undefined,
+    },
+    {
+        id: 'default-model',
+        label: 'Default model',
+        description: 'Override the default model for Claude Code',
+        hint: 'Sets ANTHROPIC_DEFAULT_MODEL — overrides session-level model selection',
+        blurb: 'override default model',
+        kind: 'string',
+        target: { type: 'env', key: 'ANTHROPIC_DEFAULT_MODEL' },
+        recommended: false,
+        defaultValue: undefined,
+        maxLength: 64,
+    },
+    {
+        // Upstream default: 30 min. 0 = disabled (still ACTIVE — written to env).
+        // PF-023 bounds: max 1440 (24h). min 0 (0 = off, explicit value not neutral).
+        id: 'goal-checkin-minutes',
+        label: 'Goal check-in interval',
+        description: 'Interval in minutes for Claude to check in on task goals',
+        hint: 'Periodic goal check-ins every N min; 0 = off; upstream default is 30',
+        blurb: 'goal check-in interval',
+        kind: 'number',
+        target: { type: 'env', key: 'CLAUDE_CODE_GOAL_CHECKIN_MINUTES' },
+        recommended: false,
+        defaultValue: undefined,
+        min: 0, // 0 = off (ACTIVE, not neutral — written as "0")
+        max: 1440, // devflow sanity bound: 24 hours (applies PF-023)
+        integer: true,
+        upstreamDefault: 30,
+    },
+    {
+        // Writes as { command: value } per Claude Code spellcheck setting shape.
+        id: 'spellcheck',
+        label: 'Spellcheck command',
+        description: 'Custom spellcheck command for Claude Code',
+        hint: 'Sets the external spell-check command (written as {command: ...})',
+        blurb: 'external spell-check command',
+        kind: 'string',
+        target: { type: 'setting', key: 'spellcheck' },
+        recommended: false,
+        defaultValue: undefined,
+        wrapKey: 'command',
+        maxLength: 256, // devflow sanity bound (applies PF-023)
+    },
+    {
+        // view-mode folded into the registry; neutralValue 'default' deletes the viewMode key.
+        // VIEW_MODES, ViewMode, resolveExistingViewMode, and resolveFinalViewMode remain exported
+        // for init.ts and other callers that read/resolve view-mode in the settings pipeline.
+        id: 'view-mode',
+        label: 'View mode',
+        description: 'Interface view mode (default / verbose / focus)',
+        hint: "Controls view mode; 'default' removes the key (Claude Code native default)",
+        blurb: 'interface view mode',
+        kind: 'enum',
+        target: { type: 'setting', key: 'viewMode' },
+        values: ['default', 'verbose', 'focus'],
+        valueHints: {
+            default: 'Standard view (no override)',
+            verbose: 'Show all tool output and reasoning',
+            focus: 'Minimal UI — hides secondary panels',
+        },
+        neutralValue: 'default',
+        recommended: false,
+        defaultValue: 'default',
+    },
 ];
+// Pre-built lookup for O(1) flag-by-id access.
+const FLAG_REGISTRY_MAP = new Map(FLAG_REGISTRY.map(f => [f.id, f]));
 /**
- * Return IDs of all flags that are enabled by default.
+ * O(1) flag lookup backed by FLAG_REGISTRY_MAP.
+ * Returns undefined when the id is not in the registry.
  */
-export function getDefaultFlags() {
-    return FLAG_REGISTRY.filter(f => f.defaultEnabled).map(f => f.id);
+export function findFlag(id) {
+    return FLAG_REGISTRY_MAP.get(id);
 }
+// ─── Core value helpers ───────────────────────────────────────────────────────
 /**
- * Apply enabled flags to a settings JSON string.
- * Sets env vars for env-type flags and top-level keys for setting-type flags.
- * Ignores unknown flag IDs (forward-compatible with old manifests).
+ * Returns the neutral value for a flag — the value that means "no preference"
+ * (applying neutral deletes the target key).
+ *
+ * - boolean: false (false = off = no key written)
+ * - enum: neutralValue if defined, else null
+ * - number: null (no number, including 0, is neutral — 0 is ACTIVE)
+ * - string: null
  */
-export function applyFlags(settingsJson, flagIds) {
-    const settings = JSON.parse(settingsJson);
-    const flagMap = new Map(FLAG_REGISTRY.map(f => [f.id, f]));
-    for (const id of flagIds) {
-        const flag = flagMap.get(id);
-        if (!flag)
+export function neutralValueOf(flag) {
+    switch (flag.kind) {
+        case 'boolean': return false;
+        case 'enum': return flag.neutralValue ?? null;
+        case 'number': return null;
+        case 'string': return null;
+    }
+}
+/**
+ * Returns true when `value` is the neutral value for `flag`.
+ * null is always neutral. Number 0 is NOT neutral.
+ */
+export function isNeutral(flag, value) {
+    if (value === null)
+        return true;
+    return value === neutralValueOf(flag);
+}
+/**
+ * Map a record value to a TUI value.
+ *
+ * viewMode GLUE RULE (PF-017 one-shared-definition corollary): the mapping lives here,
+ * next to neutralValueOf — the definition it depends on — not across a module boundary.
+ *   enum with neutralValue: neutralValue → null in TUI (null is the TUI representation
+ *   of "use the default"; the key is deleted when persisted).
+ * All other values pass through unchanged.
+ *
+ * Consumers: flags-view/state.ts (buildFlagRows, buildDevflowDefault, collectFlagRecord).
+ */
+export function recordToTui(flag, v) {
+    if (v === null)
+        return null;
+    if (flag.kind === 'enum' && flag.neutralValue !== undefined) {
+        if (v === flag.neutralValue)
+            return null;
+    }
+    return v;
+}
+/**
+ * Map a TUI value back to a record value.
+ *
+ * viewMode GLUE RULE (PF-017 one-shared-definition corollary): inverse of recordToTui,
+ * co-located with that function so the round-trip contract is auditable in one place.
+ *   enum with neutralValue: null → neutralValue (e.g. 'default').
+ * All other values pass through unchanged.
+ *
+ * Consumers: flags-view/state.ts (collectFlagRecord).
+ */
+export function tuiToRecord(flag, v) {
+    if (v === null && flag.kind === 'enum' && flag.neutralValue !== undefined) {
+        return flag.neutralValue;
+    }
+    return v;
+}
+/**
+ * Validate and coerce `raw` to a safe value for `flag` at the sink.
+ * Returns null when the value is invalid (hostile-value defence — applies PF-023).
+ *
+ * Number invariants: finite, within [min, max], integer when required.
+ * String invariants: within maxLength, no control characters.
+ * Enum invariants: value must be in the declared values array.
+ * Boolean invariants: must be a boolean.
+ */
+export function coerceFlagValue(flag, raw) {
+    if (raw === null || raw === undefined)
+        return null;
+    switch (flag.kind) {
+        case 'boolean': {
+            if (typeof raw !== 'boolean')
+                return null;
+            return raw;
+        }
+        case 'enum': {
+            if (typeof raw !== 'string')
+                return null;
+            if (!flag.values.includes(raw))
+                return null;
+            return raw;
+        }
+        case 'number': {
+            if (typeof raw !== 'number')
+                return null;
+            if (!Number.isFinite(raw))
+                return null; // rejects Infinity, NaN, 1e309
+            if (flag.min !== undefined && raw < flag.min)
+                return null;
+            if (flag.max !== undefined && raw > flag.max)
+                return null;
+            if (flag.integer === true && !Number.isInteger(raw))
+                return null;
+            return raw;
+        }
+        case 'string': {
+            if (typeof raw !== 'string')
+                return null;
+            // Empty string is UNSET, never an active value — caller should pass null for unset.
+            if (raw === '')
+                return null;
+            if (flag.maxLength !== undefined && raw.length > flag.maxLength)
+                return null;
+            // Reject ASCII control chars except \t (horizontal tab is benign in commands).
+            // LF (\x0a) MUST be rejected: `spellcheck` is executed as a shell command, where
+            // a newline is a statement separator, and the --status table is line-oriented.
+            // The range \x0a-\x1f covers LF through US, with \x09 (TAB) as the sole omission.
+            if (/[\x00-\x08\x0a-\x1f\x7f]/.test(raw))
+                return null;
+            return raw;
+        }
+    }
+}
+/**
+ * Parse a CLI text input to a FlagsRecordValue.
+ * 'unset' (literal) → null for any flag.
+ *
+ * Number branch uses strict decimal grammar (applies PF-023 — invariant at the sink
+ * every caller reaches, not per-caller): rejects empty, padded, hex, exponent,
+ * and leading-zero forms. Equivalent to the TUI's strict parsing so both entry
+ * points share one grammar.
+ *
+ * String branch: empty string → null (empty is UNSET, not an active value).
+ */
+export function parseFlagValueInput(flag, text) {
+    if (text === 'unset')
+        return null;
+    switch (flag.kind) {
+        case 'boolean': {
+            if (text === 'true')
+                return true;
+            if (text === 'false')
+                return false;
+            return null;
+        }
+        case 'enum':
+            return coerceFlagValue(flag, text);
+        case 'number': {
+            // Strict decimal grammar: reject empty, padded, hex, exponent, and leading zeros.
+            // Number('') === 0, Number(' 3 ') === 3, Number('0x5') === 5, Number('1e1') === 10 —
+            // all would pass bare Number() but violate the strict grammar contract.
+            if (text === '' || text !== text.trim())
+                return null;
+            if (!/^[+-]?(?:0|[1-9]\d*)(?:\.\d+)?$/.test(text))
+                return null;
+            return coerceFlagValue(flag, Number(text));
+        }
+        case 'string':
+            // Empty string → null (empty is UNSET); coerceFlagValue handles the rest.
+            return coerceFlagValue(flag, text);
+    }
+}
+/**
+ * Returns a human-readable kind label for a flag — used by --list output.
+ *
+ * Exhaustive switch (no default): TypeScript narrows on `flag.kind` so
+ * each branch sees the narrowed subtype directly.
+ *
+ * Output examples:
+ *   boolean                      → 'boolean'
+ *   enum [small|medium|large|…]  → 'enum [small|medium|large|…]'
+ *   number min=1 max=100 integer → 'number min=1 max=100 integer'
+ *   string maxLen=64             → 'string maxLen=64'
+ */
+export function describeFlagKind(flag) {
+    switch (flag.kind) {
+        case 'boolean':
+            return 'boolean';
+        case 'enum':
+            return `enum [${flag.values.join('|')}]`;
+        case 'number': {
+            const parts = [];
+            if (flag.min !== undefined)
+                parts.push(`min=${flag.min}`);
+            if (flag.max !== undefined)
+                parts.push(`max=${flag.max}`);
+            if (flag.integer)
+                parts.push('integer');
+            return `number${parts.length ? ' ' + parts.join(' ') : ''}`;
+        }
+        case 'string':
+            return `string${flag.maxLength !== undefined ? ` maxLen=${flag.maxLength}` : ''}`;
+    }
+}
+/**
+ * Returns the expected-input hint shown by --set when a value is invalid.
+ *
+ * Exhaustive switch: TypeScript narrows each arm directly.
+ *
+ * Output examples:
+ *   boolean → 'true|false|unset'
+ *   enum    → 'small|medium|large|unrestricted|unset'
+ *   number  → 'a valid number value or unset'
+ *   string  → 'a valid string value or unset'
+ */
+export function expectedInputFor(flag) {
+    switch (flag.kind) {
+        case 'boolean':
+            return 'true|false|unset';
+        case 'enum':
+            return `${flag.values.join('|')}|unset`;
+        case 'number':
+            return 'a valid number value or unset';
+        case 'string':
+            return 'a valid string value or unset';
+    }
+}
+/**
+ * Returns the effective display for a flag value — the single source of truth
+ * for every render site (TUI cell, --status rows, --list default label,
+ * --enable/--disable confirmation text).
+ *
+ * Never returns 'unset' — always shows what the flag effectively does:
+ *   boolean true           → { text: 'on',  isDefault: false }
+ *   boolean false/null     → { text: 'off', isDefault: true }
+ *   enum active value      → { text: value, isDefault: false }
+ *   enum neutral/null      → { text: neutralValue ?? '—', isDefault: true }
+ *   number active value    → { text: String(value), isDefault: false }
+ *   number null            → { text: String(defaultValue ?? upstreamDefault), isDefault: true }
+ *                             or { text: '—', isDefault: true } when no default exists
+ *   string active value    → { text: value, isDefault: false }
+ *   string null            → { text: '—', isDefault: true }
+ *
+ * D-EFFDV: one-definition seam consumed by formatFlagValue, render.ts formatValue,
+ * formatStatusRows (Site D), and handleList defaultLabel (Site C).
+ * All display sites must route through here — never re-derive independently.
+ */
+export function effectiveDisplay(flag, value) {
+    // Boolean: true = 'on' (active), false/null = 'off' (neutral but meaningful)
+    if (flag.kind === 'boolean') {
+        const active = value === true;
+        return { text: active ? 'on' : 'off', isDefault: !active };
+    }
+    // Active non-null non-neutral value for enum/number/string
+    if (value !== null && !isNeutral(flag, value)) {
+        return { text: String(value), isDefault: false };
+    }
+    // Neutral or null: show what the flag effectively defaults to
+    switch (flag.kind) {
+        case 'enum': {
+            const neutral = flag.neutralValue ?? '—';
+            return { text: neutral, isDefault: true };
+        }
+        case 'number': {
+            const def = flag.defaultValue ?? flag.upstreamDefault;
+            return { text: def !== undefined ? String(def) : '—', isDefault: true };
+        }
+        case 'string':
+            return { text: '—', isDefault: true };
+    }
+}
+/**
+ * Format a flag value for display (CLI output, confirmation messages).
+ *
+ * Delegates to effectiveDisplay — see its JSDoc for the full vocabulary.
+ * D-EFFDV: one definition, all sites route through effectiveDisplay.
+ *
+ * NOTE: --set confirmation for an explicit 'unset' input should special-case
+ * null → literal 'unset' at the call site, since the user named it explicitly.
+ */
+export function formatFlagValue(flag, value) {
+    return effectiveDisplay(flag, value).text;
+}
+/**
+ * Count flags in `record` that have active (non-neutral) values.
+ * Unknown IDs are counted if their value is truthy.
+ */
+export function countActiveFlags(record) {
+    let count = 0;
+    for (const [id, value] of Object.entries(record)) {
+        if (value === null)
             continue;
-        if (flag.target.type === 'env') {
-            settings.env ??= {};
-            settings.env[flag.target.key] = flag.target.value;
+        const flag = FLAG_REGISTRY_MAP.get(id);
+        if (flag) {
+            if (!isNeutral(flag, value))
+                count++;
+        }
+        else if (value) {
+            // Unknown flag ID: count if truthy
+            count++;
+        }
+    }
+    return count;
+}
+/**
+ * Read the view-mode from a FlagsRecord.
+ * Returns 'default' when the entry is absent, null, or unrecognised.
+ */
+export function readViewMode(record) {
+    const v = record['view-mode'];
+    if (typeof v === 'string' && VIEW_MODES.includes(v)) {
+        return v;
+    }
+    return 'default';
+}
+/**
+ * Sanitize a FlagsRecord by coercing each known flag's value through
+ * coerceFlagValue.
+ *
+ * Known flag IDs (applies ADR-014 key-presence semantics):
+ *   - explicit null input → kept as null (deliberately unset)
+ *   - valid non-null input → kept as coerced value
+ *   - invalid non-null input → KEY DROPPED (absent = adopt default on next init,
+ *     which is safer than writing null = "deliberately unset" for a corrupt value)
+ *
+ * Unknown flag IDs (forward-compat):
+ *   - primitive values (boolean, number, string, null) → kept as-is
+ *   - non-primitive values (objects, arrays) → DROPPED to avoid laundering
+ *     untrusted shapes into FlagsRecordValue (applies PF-023)
+ *
+ * D39: `__proto__`, `constructor`, `prototype` are always skipped.
+ */
+export function sanitizeFlagsRecord(record) {
+    const result = {};
+    for (const [id, value] of Object.entries(record)) {
+        // D39: prototype pollution guard — skip dangerous own-property names that
+        // would invoke [[Set]] accessors on the result object and mutate its prototype.
+        if (id === '__proto__' || id === 'constructor' || id === 'prototype')
+            continue;
+        const flag = FLAG_REGISTRY_MAP.get(id);
+        if (flag) {
+            if (value === null) {
+                // Explicit null = deliberately unset: preserve key-presence semantics.
+                result[id] = null;
+            }
+            else {
+                const coerced = coerceFlagValue(flag, value);
+                if (coerced !== null) {
+                    result[id] = coerced;
+                }
+                // else: invalid non-null value → DROP the key so the flag is re-adopted
+                // on next init from registry defaults (safer than writing null = "unset").
+            }
+        }
+        else {
+            // Unknown id: forward-compat pass-through for primitive/null values only.
+            // Non-primitive values (objects, arrays) are dropped — laundering an
+            // arbitrary object into FlagsRecordValue violates the type contract.
+            if (value === null || typeof value === 'boolean' || typeof value === 'number' || typeof value === 'string') {
+                result[id] = value;
+            }
+        }
+    }
+    return result;
+}
+// ─── Record builders ──────────────────────────────────────────────────────────
+/**
+ * Per-kind default-value rule (single authoritative source — CONS-M2).
+ *
+ * - boolean: flag.defaultValue (always a boolean — never collapses to null)
+ * - enum / number / string: flag.defaultValue ?? null
+ *   (undefined defaultValue → null = adopt-on-next-init semantics)
+ *
+ * Call sites: getDefaultFlagsRecord, resolveSeedFlags (init-seed.ts),
+ * buildDevflowDefault (flags-view/state.ts). Adding a fifth kind or changing
+ * the null-collapse rule requires updating only this function.
+ */
+export function defaultValueOf(flag) {
+    return flag.kind === 'boolean' ? flag.defaultValue : (flag.defaultValue ?? null);
+}
+/**
+ * Return a FlagsRecord with every registered flag set to its defaultValue.
+ * Flags with undefined defaultValue get null.
+ * This record has an entry for EVERY flag — use it for initial seeding.
+ */
+export function getDefaultFlagsRecord() {
+    return Object.fromEntries(FLAG_REGISTRY.map(f => [f.id, defaultValueOf(f)]));
+}
+// ─── Migration helper ─────────────────────────────────────────────────────────
+/**
+ * Migrate a legacy (string-array) enabled-flags manifest to a typed FlagsRecord.
+ * Called by manifest.ts self-healing when it encounters an old string-array manifest.
+ *
+ * Contract (applies ADR-014 transition semantics):
+ * - knownIds defined   → knownSet = knownIds ∪ enabledIds
+ * - knownIds undefined → knownSet = full current registry ∪ enabledIds
+ *   (pre-knownFlags manifests: all flags known, so adopt-nothing is expressed
+ *   as value = enabledIds.includes(id) rather than absent entry)
+ * - Boolean registry flags in knownSet → value = enabledIds.includes(id)
+ * - Registry flags NOT in knownSet → NO entry (adopted on next seed)
+ * - Unknown enabled IDs (not in registry) → `true` preserved
+ * - viewMode fold: 'view-mode' = legacyViewMode ?? 'default'
+ */
+export function migrateLegacyFlagsToRecord(enabledIds, knownIds, legacyViewMode) {
+    const enabledSet = new Set(enabledIds);
+    const knownSet = knownIds !== undefined
+        ? new Set([...knownIds, ...enabledIds])
+        : new Set([...FLAG_REGISTRY.map(f => f.id), ...enabledIds]);
+    const result = {};
+    for (const flag of FLAG_REGISTRY) {
+        // view-mode is handled separately at the end
+        if (flag.id === 'view-mode')
+            continue;
+        if (!knownSet.has(flag.id)) {
+            // Not known at last install → NO entry (will be adopted on next seed)
+            continue;
+        }
+        if (flag.kind === 'boolean') {
+            result[flag.id] = enabledSet.has(flag.id);
+        }
+        else {
+            // Valued flags: legacy string arrays never contain them; null = neutral
+            result[flag.id] = null;
+        }
+    }
+    // Unknown enabled IDs (not in any registry) preserved as true
+    for (const id of enabledIds) {
+        if (!FLAG_REGISTRY_MAP.has(id)) {
+            result[id] = true;
+        }
+    }
+    // viewMode fold: always written so the view-mode entry is explicit
+    result['view-mode'] = legacyViewMode ?? 'default';
+    return result;
+}
+// ─── Apply / Strip ────────────────────────────────────────────────────────────
+/**
+ * Return `v` as a `Record<string, unknown>` only when it is a plain object.
+ * Returns undefined for arrays, null, or non-objects.
+ *
+ * Used as a guard at every `settings.env` access point so that a malformed
+ * `"env": []` in settings.json cannot cause `Object.keys([]).length === 0`
+ * to delete the entire env key, losing user-set env vars (applies TS-M3).
+ */
+function asPlainObject(v) {
+    return typeof v === 'object' && v !== null && !Array.isArray(v)
+        ? v
+        : undefined;
+}
+/** Compute the value to write to settings.json for an active flag. */
+function buildPayload(flag, value) {
+    switch (flag.kind) {
+        case 'boolean':
+            return flag.onPayload;
+        case 'enum':
+            return value;
+        case 'number':
+            // Env targets receive string values; setting targets receive numbers.
+            return flag.target.type === 'env' ? String(value) : value;
+        case 'string': {
+            const s = value;
+            return flag.wrapKey ? { [flag.wrapKey]: s } : s;
+        }
+    }
+}
+/**
+ * Apply a FlagsRecord to a settings JSON string.
+ *
+ * - Unknown flag IDs are skipped (forward-compatible with future flags).
+ * - `coerceFlagValue` is called at the sink before applying (applies PF-023).
+ * - Neutral values delete their target key.
+ * - Env payloads for number flags are stringified ('40', never 40).
+ * - Setting payloads for string flags with wrapKey are shaped ({ command: v }).
+ * - env object is created on demand; deleted when it becomes empty.
+ * - `__proto__`, `constructor`, `prototype` keys are silently skipped.
+ */
+export function applyFlags(settingsJson, flags) {
+    // REL-M2 sink guard (applies PF-023): a non-plain-object root (null, array, scalar)
+    // would cause a silent no-op or a confusing TypeError deep inside the loop.
+    // Throw early with a clear message so every caller path is self-guarding.
+    const root = JSON.parse(settingsJson);
+    if (root === null || typeof root !== 'object' || Array.isArray(root)) {
+        throw new Error('applyFlags: settings.json root must be a plain object');
+    }
+    const settings = root;
+    for (const [id, value] of Object.entries(flags)) {
+        // Prototype pollution guard
+        if (id === '__proto__' || id === 'constructor' || id === 'prototype')
+            continue;
+        const flag = FLAG_REGISTRY_MAP.get(id);
+        if (!flag)
+            continue; // unknown id — skip for forward compat
+        // Coerce at the sink (applies PF-023: validate at the convergence point)
+        const safe = coerceFlagValue(flag, value);
+        if (isNeutral(flag, safe)) {
+            // Neutral → delete the target key
+            if (flag.target.type === 'env') {
+                // asPlainObject guard: "env": [] must not delete a user's env var (applies TS-M3)
+                const env = asPlainObject(settings.env);
+                if (env)
+                    delete env[flag.target.key];
+            }
+            else {
+                delete settings[flag.target.key];
+            }
         }
         else {
-            settings[flag.target.key] = flag.target.value;
+            const payload = buildPayload(flag, safe);
+            if (flag.target.type === 'env') {
+                if (!asPlainObject(settings.env)) {
+                    settings.env = {};
+                }
+                settings.env[flag.target.key] = payload;
+            }
+            else {
+                settings[flag.target.key] = payload;
+            }
         }
     }
+    // Clean up empty env object; asPlainObject guard avoids matching "env": []
+    const env = asPlainObject(settings.env);
+    if (env && Object.keys(env).length === 0) {
+        delete settings.env;
+    }
     return JSON.stringify(settings, null, 2) + '\n';
 }
 /**
  * Strip all flag-managed keys from a settings JSON string.
- * Removes env vars and top-level settings controlled by the flag registry.
- * Cleans up empty env object when last entry is removed.
+ * Registry-driven unconditional delete. Now covers viewMode (via view-mode
+ * registry entry) and object-valued settings (spellcheck → key deleted).
+ * Cleans up empty env object. Strip-then-apply idempotence preserved (INV-1).
  */
 export function stripFlags(settingsJson) {
-    const settings = JSON.parse(settingsJson);
-    const env = settings.env;
+    // REL-M2 sink guard (applies PF-023): mirror of applyFlags — throw early on a
+    // non-plain-object root so every caller path is self-guarding.
+    const root = JSON.parse(settingsJson);
+    if (root === null || typeof root !== 'object' || Array.isArray(root)) {
+        throw new Error('stripFlags: settings.json root must be a plain object');
+    }
+    const settings = root;
+    // asPlainObject guard: "env": [] must not have its keys iterated as an object (applies TS-M3)
+    const env = asPlainObject(settings.env);
     for (const flag of FLAG_REGISTRY) {
         if (flag.target.type === 'env') {
-            if (env) {
+            if (env)
                 delete env[flag.target.key];
-            }
         }
         else {
             delete settings[flag.target.key];
@@ -224,33 +957,10 @@ export function stripFlags(settingsJson) {
     }
     return JSON.stringify(settings, null, 2) + '\n';
 }
+// ─── viewMode helpers ─────────────────────────────────────────────────────────
 const VIEW_MODE_KEY = 'viewMode';
 /** All valid view mode values. Used for validation at manifest read boundaries. */
 export const VIEW_MODES = ['default', 'verbose', 'focus'];
-/**
- * Apply a view mode to a settings JSON string.
- * 'default' removes the viewMode key (Claude Code default behaviour);
- * 'verbose' and 'focus' set the key explicitly.
- */
-export function applyViewMode(settingsJson, mode) {
-    const settings = JSON.parse(settingsJson);
-    if (mode === 'default') {
-        delete settings[VIEW_MODE_KEY];
-    }
-    else {
-        settings[VIEW_MODE_KEY] = mode;
-    }
-    return JSON.stringify(settings, null, 2) + '\n';
-}
-/**
- * Strip the viewMode key from a settings JSON string.
- * Used during uninstall / flag strip to restore Claude Code defaults.
- */
-export function stripViewMode(settingsJson) {
-    const settings = JSON.parse(settingsJson);
-    delete settings[VIEW_MODE_KEY];
-    return JSON.stringify(settings, null, 2) + '\n';
-}
 /**
  * Extract the non-default view mode from a settings JSON string.
  *
@@ -283,20 +993,11 @@ export function resolveExistingViewMode(settingsJson) {
 }
 /**
  * Resolve the final view mode to write, combining an existing settings value,
- * an init-prompt-selected value, and whether the selection was explicit (via
- * CLI flag) or implicit (prompt default / recommended path).
- *
- * @param current  - Existing viewMode from settings.json (resolveExistingViewMode).
- *                   undefined means no opinion in the current settings.
- * @param selected - What the init prompt (or recommended path) would use.
- * @param explicit - true when the user made an explicit interactive selection in
- *                   the Advanced init prompt, or when --reset was passed (which
- *                   forces viewMode back to 'default' and sets explicit=true so
- *                   that 'default' wins over any externally-set value).
+ * an init-prompt-selected value, and whether the selection was explicit.
  *
  * Rules:
  *   1. explicit ⇒ selected wins (user intent is unambiguous, even 'default')
- *   2. non-default current ⇒ current wins (preserve externally-set mode, e.g. /focus)
+ *   2. non-default current ⇒ current wins (preserve externally-set mode)
  *   3. else ⇒ selected
  */
 export function resolveFinalViewMode(current, selected, explicit) {
@@ -306,4 +1007,118 @@ export function resolveFinalViewMode(current, selected, explicit) {
         return current;
     return selected;
 }
+// ─── Fold-before-strip pipeline ───────────────────────────────────────────────
+/**
+ * Fold-before-strip pipeline — the single authoritative entry point for all
+ * settings.json mutation paths (applies PF-015, PF-017, ADR-014).
+ *
+ * Both `init.ts` and `persistFlagConfig` (flags.ts) MUST call this instead of
+ * invoking `stripFlags` + `applyFlags` directly; the invariant lives in the
+ * pipeline, not at call sites.
+ *
+ * Fold semantics (D15-adopt):
+ *
+ *   view-mode (Step 1): resolved via `resolveFinalViewMode` so an externally-set
+ *   `/focus` survives unless `viewModeExplicit` is true.
+ *
+ *   Valued flags — enum/number/string, excluding view-mode (Step 2):
+ *   The "claimed" set is determined by `opts.ownedRecord`:
+ *     - `undefined`  → use `record` itself (persistFlagConfig path — the manifest
+ *                      record IS what devflow claims)
+ *     - `null`       → nothing previously owned (fresh install)
+ *     - `FlagsRecord`→ the original manifest flags BEFORE seeding (init path)
+ *
+ *   A flag is "claimed" when it is present and non-null in the claimed set.
+ *   Claimed: record value wins (devflow previously set this value).
+ *   Unclaimed: fold from settings — if the user has a value in settings.json,
+ *   adopt it into the record (ADR-014 adoption, devflow takes ownership).
+ *
+ *   Boolean flags: never folded — on/off is always record-driven.
+ *
+ * The fold MUST run on pre-strip content — `stripFlags` removes the target
+ * keys, making any fold after strip vacuous.
+ *
+ * Uninstall note: `src/cli/commands/uninstall.ts` calls `stripFlags` directly
+ * with no record argument, preserving its full-sweep semantics. Do not change.
+ *
+ * Pure function: no I/O.
+ *
+ * @param settingsJson    Current settings.json content (pre-strip)
+ * @param record          FlagsRecord to fold into and apply
+ * @param opts.viewModeExplicit  true when the caller explicitly selected a view
+ *                        mode (TUI row changed or `--set view-mode=...` passed)
+ * @param opts.ownedRecord  Prior ownership set; see semantics above.
+ *                        Init path: `existingManifest?.features.flags ?? null`.
+ *                        persistFlagConfig path: omit (undefined).
+ * @returns `{ settings: updated JSON string, record: folded FlagsRecord }`
+ */
+export function convergeFlagsIntoSettings(settingsJson, record, opts) {
+    // ── Step 1: fold view-mode (must read pre-strip) ──────────────────────────
+    // PF-015: resolveExistingViewMode reads the viewMode key. stripFlags removes
+    // it as part of the view-mode registry entry. Reading after strip silently
+    // reverts an externally-set /focus.
+    const folded = {
+        ...record,
+        'view-mode': resolveFinalViewMode(resolveExistingViewMode(settingsJson), readViewMode(record), opts.viewModeExplicit),
+    };
+    // ── Step 2: fold existing values for valued flags (pre-strip) ────────────
+    // D15-adopt: for unclaimed valued flags, read the current settings value and
+    // adopt it into the record. Claimed flags (previously set by devflow) keep
+    // their record value; boolean flags are never folded.
+    //
+    // "Claimed" is determined by opts.ownedRecord:
+    //   undefined → use `record` (persistFlagConfig: manifest record = owned set)
+    //   null      → nothing claimed (fresh install)
+    //   FlagsRecord → original manifest flags before seeding (init path)
+    const claimedIn = opts.ownedRecord !== undefined ? opts.ownedRecord : record;
+    let parsed;
+    try {
+        parsed = JSON.parse(settingsJson);
+    }
+    catch {
+        parsed = {};
+    }
+    const env = asPlainObject(parsed.env);
+    for (const flag of FLAG_REGISTRY) {
+        if (flag.kind === 'boolean')
+            continue; // boolean flags: record-driven only
+        if (flag.id === 'view-mode')
+            continue; // already handled above
+        // Check whether devflow previously owned this flag's key.
+        // Any presence in claimedIn — including null (explicitly unset) — means
+        // devflow owns the slot; the record value (or its absence) wins over settings.
+        // Absence from claimedIn means devflow never wrote it → fold from settings.
+        const previouslyOwned = claimedIn !== null &&
+            Object.prototype.hasOwnProperty.call(claimedIn, flag.id);
+        if (previouslyOwned)
+            continue;
+        // Read the raw value from settings.json (before strip removes it)
+        const rawVal = flag.target.type === 'env'
+            ? env?.[flag.target.key]
+            : parsed[flag.target.key];
+        if (rawVal === undefined)
+            continue;
+        // Unwrap wrapKey-shaped values (e.g., spellcheck: { command: 'hunspell' } → 'hunspell')
+        let toCoerce = rawVal;
+        if (flag.kind === 'string' && flag.wrapKey !== undefined) {
+            const obj = asPlainObject(rawVal);
+            toCoerce = obj !== undefined ? obj[flag.wrapKey] : undefined;
+        }
+        if (toCoerce === undefined)
+            continue;
+        // Env vars store numbers as strings ('8') — convert to number for coercion
+        if (flag.kind === 'number' && typeof toCoerce === 'string') {
+            const n = Number(toCoerce);
+            toCoerce = Number.isFinite(n) ? n : toCoerce;
+        }
+        const coerced = coerceFlagValue(flag, toCoerce);
+        if (coerced !== null) {
+            folded[flag.id] = coerced;
+        }
+    }
+    // ── Step 3: strip all managed keys, then apply the folded record ──────────
+    const stripped = stripFlags(settingsJson);
+    const settings = applyFlags(stripped, folded);
+    return { settings, record: folded };
+}
 //# sourceMappingURL=flags.js.map