import { execFile } from "node:child_process";
import { appendFile, mkdir, readFile, rm, writeFile } from "node:fs/promises";
import { dirname, isAbsolute, join, resolve } from "node:path";
import { promisify } from "node:util";

import {
  DEFAULT_OBSERVED_ROUTING_CONFIG,
  DEFAULT_OUTPUT_ROUTER_ENABLED,
  DEFAULT_POST_TOOL_ROUTING,
  DEFAULT_ROUTER_THRESHOLDS,
  DEFAULT_SCRIPT_TRANSFORM_CONFIG,
  DEFAULT_STORAGE_POLICY,
  DEFAULT_VAULT_RETENTION,
  DEFAULT_VAULT_ROOT,
  normalizeFreeflowConfig,
} from "../../../router/dist/index.js";
import {
  handleModeCommand,
  readCapabilityState,
  readFreeflowConfig,
  readFreeflowConfigLayers,
  readFreeflowLocalConfig,
  readModeState,
  resetSessionOverrides,
  setSessionCoreOverride,
  VALID_MODES,
} from "../runtime/runtime-context.js";
import {
  PiSettingsComponent,
  type SettingsCommitResult,
  type SettingsEntry,
  type SettingsSessionResult,
} from "./settings-tui.js";

const POST_TOOL_ROUTING_VALUES = ["off", "safety-net", "strict"] as const;
const STORAGE_POLICY_VALUES = ["hybrid-dedupe", "store-everything"] as const;
const OBSERVED_PERSISTENCE_VALUES = ["none", "metadata-only", "exact"] as const;
const SCRIPT_LANGUAGES = ["javascript", "python", "jq"] as const;
const DEFAULT_FREEFLOW_ENABLED = true;
const DEFAULT_INTERACTION_CONTRACT_ENABLED = true;
const DEFAULT_SKILLS_ENABLED = true;
const MODE_VALUES = ["conversation", "workflow", "strict-workflow"];
const MODE_LABELS = {
  default: "Use configured default",
  conversation: "conversation",
  workflow: "workflow",
  "strict-workflow": "strict-workflow",
};
const MODE_DESCRIPTIONS = {
  conversation: "Discussion and read-only inspection",
  workflow: "Adaptive workflow for consequential work",
  "strict-workflow": "Stronger decision and evidence pressure for high-risk work",
};
const LOCAL_INHERIT = "inherit";
const execFileAsync = promisify(execFile);

type ConfigScope = "session" | "local" | "repository";
type ConfigSource = "session" | "local" | "repository" | "builtin";

type SettingKind = "boolean" | "enum" | "integer" | "string" | "list" | "json" | "group";

type SettingsItem = {
  id: string;
  label: string;
  description: string;
  path?: string[];
  kind: SettingKind;
  value: unknown;
  defaultValue?: unknown;
  values?: string[];
  valueLabels?: Record<string, string>;
  valueDescriptions?: Record<string, string>;
  inactive?: boolean;
  displaySuffix?: string;
  children?: SettingsItem[];
  parse?: (text: string) => unknown;
  format?: (value: unknown) => string;
  configScope?: ConfigScope;
  configValues?: Record<string, unknown>;
  effectiveValue?: unknown;
  effectiveSource?: ConfigSource;
  inheritedValue?: unknown;
  inheritedSource?: ConfigSource;
  localOverrideValue?: unknown;
  transient?: boolean;
};

type OpenSettingsOptions = {
  title: string;
  items: SettingsItem[];
  ctx: any;
  onChange: (item: SettingsItem, value: unknown) => Promise<SettingsCommitResult>;
  initialChoice?: SettingsItem;
};

function isRecord(value: unknown): value is Record<string, unknown> {
  return typeof value === "object" && value !== null && !Array.isArray(value);
}

function cloneJson<T>(value: T): T {
  if (value === undefined) return value;
  try {
    return JSON.parse(JSON.stringify(value));
  } catch (error) {
    throw new Error(`Could not clone settings value: ${error instanceof Error ? error.message : String(error)}`);
  }
}

function getPath(source: unknown, path: string[]): unknown {
  let current = source;
  for (const key of path) {
    if (!isRecord(current)) return undefined;
    current = current[key];
  }
  return current;
}

function setPath(target: Record<string, unknown>, path: string[], value: unknown) {
  let current: Record<string, unknown> = target;
  for (const key of path.slice(0, -1)) {
    const next = current[key];
    if (!isRecord(next)) {
      current[key] = {};
    }
    current = current[key] as Record<string, unknown>;
  }
  current[path[path.length - 1]!] = value;
}

function deletePath(target: Record<string, unknown>, path: string[]) {
  let current: unknown = target;
  const parents: Array<{ object: Record<string, unknown>; key: string }> = [];
  for (const key of path.slice(0, -1)) {
    if (!isRecord(current)) return;
    parents.push({ object: current, key });
    current = current[key];
  }
  if (!isRecord(current)) return;
  delete current[path[path.length - 1]!];

  for (let index = parents.length - 1; index >= 0; index--) {
    const { object, key } = parents[index]!;
    const child = object[key];
    if (isRecord(child) && Object.keys(child).length === 0) {
      delete object[key];
    }
  }
}

function valuesEqual(a: unknown, b: unknown): boolean {
  return JSON.stringify(a) === JSON.stringify(b);
}

function isEmptyValue(value: unknown): boolean {
  return Array.isArray(value) && value.length === 0;
}

function setConfigValue(config: Record<string, unknown>, item: SettingsItem, value: unknown) {
  if (!item.path?.length) {
    throw new Error(`${item.label} is a settings group, not a writable setting.`);
  }
  if (item.defaultValue !== undefined && valuesEqual(value, item.defaultValue)) {
    deletePath(config, item.path);
    return;
  }
  if (isEmptyValue(value)) {
    deletePath(config, item.path);
    return;
  }
  setPath(config, item.path, value);
}

function parseStringList(text: string): string[] {
  return text
    .split(",")
    .map((item) => item.trim())
    .filter(Boolean);
}

function parsePositiveInteger(text: string): number {
  const value = Number(text.trim());
  if (!Number.isInteger(value) || value <= 0) {
    throw new Error("Expected a positive integer.");
  }
  return value;
}

function parseJsonObject(text: string): unknown {
  const trimmed = text.trim();
  if (!trimmed) return {};
  let parsed: unknown;
  try {
    parsed = JSON.parse(trimmed);
  } catch (error) {
    throw new Error(`Expected valid JSON: ${error instanceof Error ? error.message : String(error)}`);
  }
  if (!isRecord(parsed)) {
    throw new Error("Expected a JSON object.");
  }
  return parsed;
}

function formatList(value: unknown): string {
  return Array.isArray(value) ? value.join(", ") : "";
}

function formatJson(value: unknown): string {
  return JSON.stringify(isRecord(value) ? value : {});
}

function booleanValue(value: unknown): string {
  return value === true ? "enabled" : "disabled";
}

function normalizedSettingsConfig(rawConfig: Record<string, unknown>) {
  const rawRouter = isRecord(rawConfig.outputRouter) ? rawConfig.outputRouter : {};
  const normalized = normalizeFreeflowConfig({
    ...rawConfig,
    outputRouter: { ...rawRouter, enabled: true },
  });
  return normalized.config;
}

function rawValue(rawConfig: Record<string, unknown>, path: string[], fallback: unknown): unknown {
  const value = getPath(rawConfig, path);
  return value === undefined ? fallback : value;
}

function outputRouterItems(rawConfig: Record<string, unknown>, freeflowInactive = false): SettingsItem[] {
  const effective = normalizedSettingsConfig(rawConfig);
  const routerEnabled = normalizeFreeflowConfig(rawConfig).config.outputRouter.enabled;
  const router = effective.outputRouter;
  const scriptTransform = effective.scriptTransform;
  const observedRouting = effective.observedRouting;
  const inactive = freeflowInactive || !routerEnabled;

  return [
    {
      id: "outputRouter.enabled",
      label: "Output Router",
      description: "Master switch for Freeflow routed evidence tools and router runtime guidance.",
      path: ["outputRouter", "enabled"],
      kind: "boolean",
      value: routerEnabled,
      defaultValue: DEFAULT_OUTPUT_ROUTER_ENABLED,
      inactive: freeflowInactive,
    },
    {
      id: "outputRouter.postToolRouting",
      label: "Native safety net",
      description:
        "Post-process large/noisy native read/bash output. safety-net can replace oversized native output with vaulted routed evidence; strict is stronger.",
      path: ["outputRouter", "postToolRouting"],
      kind: "enum",
      value: router.postToolRouting,
      values: [...POST_TOOL_ROUTING_VALUES],
      valueDescriptions: {
        off: "Leave native tool output unchanged",
        "safety-net": "Route oversized or noisy native output",
        strict: "Apply stronger native output routing",
      },
      defaultValue: DEFAULT_POST_TOOL_ROUTING,
      inactive,
    },
    {
      id: "outputRouter.storagePolicy",
      label: "Storage policy",
      description: "Vault storage behavior for exactness-sensitive and noisy output.",
      path: ["outputRouter", "storagePolicy"],
      kind: "enum",
      value: router.storagePolicy,
      values: [...STORAGE_POLICY_VALUES],
      defaultValue: DEFAULT_STORAGE_POLICY,
      inactive,
    },
    {
      id: "outputRouter.thresholds.largeOutputBytes",
      label: "Large output bytes",
      description: "Byte threshold for treating command/tool output as large.",
      path: ["outputRouter", "thresholds", "largeOutputBytes"],
      kind: "integer",
      value: router.thresholds.largeOutputBytes,
      defaultValue: DEFAULT_ROUTER_THRESHOLDS.largeOutputBytes,
      parse: parsePositiveInteger,
      inactive,
    },
    {
      id: "outputRouter.thresholds.largeOutputLines",
      label: "Large output lines",
      description: "Line threshold for treating command/tool output as large.",
      path: ["outputRouter", "thresholds", "largeOutputLines"],
      kind: "integer",
      value: router.thresholds.largeOutputLines,
      defaultValue: DEFAULT_ROUTER_THRESHOLDS.largeOutputLines,
      parse: parsePositiveInteger,
      inactive,
    },
    {
      id: "outputRouter.vault.root",
      label: "Vault root",
      description: "Root directory for recoverable routed output.",
      path: ["outputRouter", "vault", "root"],
      kind: "string",
      value: router.vault.root,
      defaultValue: DEFAULT_VAULT_ROOT,
      inactive,
    },
    {
      id: "outputRouter.vault.retention.ttlDays",
      label: "Vault retention days",
      description: "TTL retention for vaulted output. Set a positive integer; default is 7 days.",
      path: ["outputRouter", "vault", "retention", "ttlDays"],
      kind: "integer",
      value:
        router.vault.retention?.strategy === "ttl" ? router.vault.retention.ttlDays : DEFAULT_VAULT_RETENTION.ttlDays,
      defaultValue: DEFAULT_VAULT_RETENTION.ttlDays,
      parse: parsePositiveInteger,
      inactive,
    },
    {
      id: "outputRouter.generatedPaths",
      label: "Generated paths",
      description:
        "Comma-separated globs for generated repo paths that should be treated as noisy or lower-priority evidence.",
      path: ["outputRouter", "hints", "generatedPathGlobs"],
      kind: "list",
      value: rawValue(
        rawConfig,
        ["outputRouter", "hints", "generatedPathGlobs"],
        rawValue(rawConfig, ["outputRouter", "generatedPaths"], router.hints?.generatedPathGlobs ?? []),
      ),
      format: formatList,
      parse: parseStringList,
      inactive,
    },
    {
      id: "outputRouter.noisyCommandHints",
      label: "Noisy command hints",
      description: "Comma-separated command patterns that are likely to produce noisy output.",
      path: ["outputRouter", "hints", "noisyCommandPatterns"],
      kind: "list",
      value: rawValue(
        rawConfig,
        ["outputRouter", "hints", "noisyCommandPatterns"],
        rawValue(rawConfig, ["outputRouter", "noisyCommandHints"], router.hints?.noisyCommandPatterns ?? []),
      ),
      format: formatList,
      parse: parseStringList,
      inactive,
    },
    {
      id: "outputRouter.scriptTransform.enabled",
      label: "Script transform",
      description:
        "Enable sandboxed script transforms/producers. Requires proof-backed adapters; no unsandboxed fallback.",
      path: ["outputRouter", "scriptTransform", "enabled"],
      kind: "boolean",
      value: scriptTransform.enabled,
      defaultValue: DEFAULT_SCRIPT_TRANSFORM_CONFIG.enabled,
      inactive,
    },
    {
      id: "outputRouter.scriptTransform.languages",
      label: "Script languages",
      description: "Comma-separated sandbox languages to allow: javascript, python, jq.",
      path: ["outputRouter", "scriptTransform", "languages"],
      kind: "list",
      value: scriptTransform.languages,
      defaultValue: DEFAULT_SCRIPT_TRANSFORM_CONFIG.languages,
      format: formatList,
      parse: (text) => parseStringList(text).filter((value) => (SCRIPT_LANGUAGES as readonly string[]).includes(value)),
      inactive,
    },
    {
      id: "outputRouter.scriptTransform.limits.timeoutMs",
      label: "Script timeout ms",
      description: "Maximum sandboxed script execution time.",
      path: ["outputRouter", "scriptTransform", "limits", "timeoutMs"],
      kind: "integer",
      value: scriptTransform.limits.timeoutMs,
      defaultValue: DEFAULT_SCRIPT_TRANSFORM_CONFIG.limits.timeoutMs,
      parse: parsePositiveInteger,
      inactive,
    },
    {
      id: "outputRouter.scriptTransform.limits.maxInputBytes",
      label: "Script max input bytes",
      description: "Maximum input size for sandboxed scripts.",
      path: ["outputRouter", "scriptTransform", "limits", "maxInputBytes"],
      kind: "integer",
      value: scriptTransform.limits.maxInputBytes,
      defaultValue: DEFAULT_SCRIPT_TRANSFORM_CONFIG.limits.maxInputBytes,
      parse: parsePositiveInteger,
      inactive,
    },
    {
      id: "outputRouter.scriptTransform.limits.maxOutputBytes",
      label: "Script max output bytes",
      description: "Maximum output size for sandboxed scripts.",
      path: ["outputRouter", "scriptTransform", "limits", "maxOutputBytes"],
      kind: "integer",
      value: scriptTransform.limits.maxOutputBytes,
      defaultValue: DEFAULT_SCRIPT_TRANSFORM_CONFIG.limits.maxOutputBytes,
      parse: parsePositiveInteger,
      inactive,
    },
    {
      id: "outputRouter.observedRouting.enabled",
      label: "Observed routing",
      description: "Route configured host tool results after they run, e.g. MCP/web/fetch/code-search output.",
      path: ["outputRouter", "observedRouting", "enabled"],
      kind: "boolean",
      value: observedRouting.enabled,
      defaultValue: DEFAULT_OBSERVED_ROUTING_CONFIG.enabled,
      inactive,
    },
    ...observedProducerItems("web", "Web search", observedRouting.web, inactive),
    ...observedProducerItems("fetch", "Fetch content", observedRouting.fetch, inactive),
    ...observedProducerItems("codeSearch", "Code search", observedRouting.codeSearch, inactive),
    {
      id: "outputRouter.observedRouting.mcp.servers",
      label: "MCP servers JSON",
      description: 'JSON object keyed by MCP server id. Example: {"github":{"enabled":true,"persistence":"exact"}}',
      path: ["outputRouter", "observedRouting", "mcp", "servers"],
      kind: "json",
      value: observedRouting.mcp?.servers ?? {},
      defaultValue: DEFAULT_OBSERVED_ROUTING_CONFIG.mcp.servers,
      format: formatJson,
      parse: parseJsonObject,
      inactive,
    },
  ];
}

function observedProducerItems(
  id: "web" | "fetch" | "codeSearch",
  label: string,
  value: any,
  inactive: boolean,
): SettingsItem[] {
  return [
    {
      id: `outputRouter.observedRouting.${id}.enabled`,
      label: `${label} observed`,
      description: `Enable observed routing for ${label.toLowerCase()} output.`,
      path: ["outputRouter", "observedRouting", id, "enabled"],
      kind: "boolean",
      value: value?.enabled === true,
      defaultValue: false,
      inactive,
    },
    {
      id: `outputRouter.observedRouting.${id}.persistence`,
      label: `${label} persistence`,
      description: "Persistence mode for this observed producer: none, metadata-only, or exact.",
      path: ["outputRouter", "observedRouting", id, "persistence"],
      kind: "enum",
      value: value?.persistence ?? "none",
      values: [...OBSERVED_PERSISTENCE_VALUES],
      valueDescriptions: {
        none: "Do not persist observed output",
        "metadata-only": "Persist metadata without raw output",
        exact: "Persist exact recoverable output",
      },
      defaultValue: value?.enabled === true ? undefined : "none",
      inactive,
    },
  ];
}

function configValueForChoice(item: SettingsItem, value: unknown): unknown {
  const key = String(value);
  if (item.configValues && Object.hasOwn(item.configValues, key)) {
    return item.configValues[key];
  }
  return value;
}

function effectiveItemValue(item: SettingsItem): unknown {
  return item.effectiveValue !== undefined ? item.effectiveValue : item.value;
}

function formatCoreValue(value: unknown): string {
  return typeof value === "boolean" ? booleanValue(value) : String(value ?? "");
}

function coreDisplaySuffix(item: SettingsItem, inactive = false): string {
  const source = item.effectiveSource ?? "builtin";
  const parts =
    item.configScope === "repository" && source === "local"
      ? [`effective ${formatCoreValue(effectiveItemValue(item))}`, source]
      : [source];
  if (inactive) parts.push("inactive");
  return `(${parts.join(" · ")})`;
}

function updateScopedItemState(item: SettingsItem, value: unknown) {
  if (!item.configScope) return;
  const configValue = configValueForChoice(item, value);
  if (item.configScope === "session" || item.configScope === "local") {
    item.effectiveValue = configValue === undefined ? item.inheritedValue : configValue;
    item.effectiveSource = configValue === undefined ? (item.inheritedSource ?? "builtin") : item.configScope;
    return;
  }
  if (item.localOverrideValue !== undefined) {
    item.effectiveValue = item.localOverrideValue;
    item.effectiveSource = "local";
    return;
  }
  item.effectiveValue = configValue;
  item.effectiveSource =
    item.defaultValue !== undefined && valuesEqual(configValue, item.defaultValue) ? "builtin" : "repository";
}

type ScopedBooleanItemOptions = {
  scope: ConfigScope;
  rawConfig: Record<string, unknown>;
  localConfig: Record<string, unknown>;
  id: string;
  label: string;
  description: string;
  path: string[];
  effectiveValue: boolean;
  effectiveSource: ConfigSource;
  defaultValue: boolean;
};

function createScopedBooleanItem(options: ScopedBooleanItemOptions): SettingsItem {
  const repositoryValue = getPath(options.rawConfig, options.path);
  const inheritedValue = typeof repositoryValue === "boolean" ? repositoryValue : options.defaultValue;
  const inheritedSource: ConfigSource = typeof repositoryValue === "boolean" ? "repository" : "builtin";
  const localValue = getPath(options.localConfig, options.path);
  let item: SettingsItem;
  if (options.scope === "local") {
    const selectedValue = typeof localValue === "boolean" ? String(localValue) : LOCAL_INHERIT;
    item = {
      id: options.id,
      label: options.label,
      description: `${options.description} Choose inherit to use the repository value; use /freeflow settings repo to edit shared defaults.`,
      path: options.path,
      kind: "enum",
      value: selectedValue,
      values: [LOCAL_INHERIT, "true", "false"],
      valueLabels: {
        inherit: "Inherit repository",
        true: "enabled",
        false: "disabled",
      },
      valueDescriptions: {
        inherit: `Use ${formatCoreValue(inheritedValue)} from ${inheritedSource}.`,
        true: "Set a personal enabled override.",
        false: "Set a personal disabled override.",
      },
      format: (value) => {
        if (value === LOCAL_INHERIT) return LOCAL_INHERIT;
        return booleanValue(value === "true");
      },
      configScope: "local",
      configValues: {
        inherit: undefined,
        true: true,
        false: false,
      },
      effectiveValue: options.effectiveValue,
      effectiveSource: options.effectiveSource,
      inheritedValue,
      inheritedSource,
    };
  } else {
    item = {
      id: options.id,
      label: options.label,
      description: `${options.description} This edits shared .freeflow/config.json.`,
      path: options.path,
      kind: "boolean",
      value: inheritedValue,
      defaultValue: options.defaultValue,
      configScope: "repository",
      effectiveValue: options.effectiveValue,
      effectiveSource: options.effectiveSource,
      localOverrideValue: typeof localValue === "boolean" ? localValue : undefined,
    };
  }
  item.displaySuffix = coreDisplaySuffix(item);
  return item;
}

type ScopedDefaultModeItemOptions = {
  scope: ConfigScope;
  repositoryDefaultMode: string;
  repositoryDefaultSource: ConfigSource;
  localDefaultMode?: string;
  effectiveValue: string;
  effectiveSource: ConfigSource;
};

function createScopedDefaultModeItem(options: ScopedDefaultModeItemOptions): SettingsItem {
  let item: SettingsItem;
  if (options.scope === "local") {
    item = {
      id: "freeflow.defaultMode",
      label: "Default mode",
      description:
        "Personal default mode for this checkout. Choose inherit to use the repository default; use /freeflow settings repo to edit shared defaults.",
      path: ["defaultMode"],
      kind: "enum",
      value: options.localDefaultMode ?? LOCAL_INHERIT,
      values: [LOCAL_INHERIT, ...MODE_VALUES],
      valueLabels: {
        inherit: "Inherit repository",
        ...MODE_LABELS,
      },
      valueDescriptions: {
        inherit: `Use ${options.repositoryDefaultMode} from ${options.repositoryDefaultSource}.`,
        ...MODE_DESCRIPTIONS,
      },
      format: (value) => String(value),
      configScope: "local",
      configValues: { inherit: undefined },
      effectiveValue: options.effectiveValue,
      effectiveSource: options.effectiveSource,
      inheritedValue: options.repositoryDefaultMode,
      inheritedSource: options.repositoryDefaultSource,
    };
  } else {
    item = {
      id: "freeflow.defaultMode",
      label: "Default mode",
      description:
        "Shared repository default Freeflow mode used when Skills are enabled. This edits .freeflow/config.json.",
      path: ["defaultMode"],
      kind: "enum",
      value: options.repositoryDefaultMode,
      values: MODE_VALUES,
      valueLabels: MODE_LABELS,
      valueDescriptions: MODE_DESCRIPTIONS,
      configScope: "repository",
      effectiveValue: options.effectiveValue,
      effectiveSource: options.effectiveSource,
      localOverrideValue: options.localDefaultMode,
    };
  }
  item.displaySuffix = coreDisplaySuffix(item);
  return item;
}

function sessionModeDisplaySuffix(
  sessionMode: string,
  defaultMode: string,
  defaultSource: ConfigSource,
  inactive: boolean,
): string | undefined {
  if (sessionMode !== "default") return undefined;
  const inactiveSuffix = inactive ? " · inactive" : "";
  return `(${defaultMode} · ${defaultSource}${inactiveSuffix})`;
}

function validModeOrUndefined(value: unknown): string | undefined {
  return typeof value === "string" && VALID_MODES.has(value) ? value : undefined;
}

function resolveSettingsCoreView(
  rawConfig: Record<string, unknown>,
  layers?: Awaited<ReturnType<typeof readFreeflowConfigLayers>>,
) {
  const localConfig = layers?.local.valid && isRecord(layers.local.parsed) ? layers.local.parsed : {};
  const repositorySkillsValue = getPath(rawConfig, ["skills"]);
  const repositorySkills = isRecord(repositorySkillsValue) ? repositorySkillsValue : {};
  const fallbackCore = {
    enabled: getPath(rawConfig, ["enabled"]) !== false,
    interactionContract: getPath(rawConfig, ["interactionContract"]) !== false,
    skills: { enabled: getPath(repositorySkills, ["enabled"]) !== false },
    defaultMode: validModeOrUndefined(rawConfig.defaultMode) ?? "workflow",
  };
  const fallbackSources = {
    enabled: typeof getPath(rawConfig, ["enabled"]) === "boolean" ? "repository" : "builtin",
    interactionContract: typeof getPath(rawConfig, ["interactionContract"]) === "boolean" ? "repository" : "builtin",
    skillsEnabled: typeof getPath(repositorySkills, ["enabled"]) === "boolean" ? "repository" : "builtin",
    defaultMode: validModeOrUndefined(rawConfig.defaultMode) !== undefined ? "repository" : "builtin",
  } as const;
  return {
    localConfig,
    core: layers?.coreConfig ?? fallbackCore,
    sources: (layers?.sources ?? fallbackSources) as {
      enabled: ConfigSource;
      interactionContract: ConfigSource;
      skillsEnabled: ConfigSource;
      defaultMode: ConfigSource;
    },
  };
}

function groupEnabled(items: SettingsItem[], id: string): boolean {
  return items.find((item) => item.id === id)?.value === true;
}

function createSessionBooleanItem(options: {
  id: string;
  label: string;
  description: string;
  key: "enabled" | "interactionContract" | "skillsEnabled";
  inheritedValue: boolean;
  inheritedSource: ConfigSource;
  effectiveValue: boolean;
  effectiveSource: ConfigSource;
  sessionOverrides: Record<string, boolean>;
}): SettingsItem {
  const override = options.sessionOverrides[options.key];
  const item: SettingsItem = {
    id: options.id,
    label: options.label,
    description: options.description,
    kind: "enum",
    value: typeof override === "boolean" ? String(override) : LOCAL_INHERIT,
    values: [LOCAL_INHERIT, "true", "false"],
    valueLabels: {
      inherit: "Inherit configured value",
      true: "Enabled for this session",
      false: "Disabled for this session",
    },
    valueDescriptions: {
      inherit: `Use ${formatCoreValue(options.inheritedValue)} from ${options.inheritedSource}.`,
      true: "Temporarily enable this setting for the current Pi session.",
      false: "Temporarily disable this setting for the current Pi session.",
    },
    format: (value) => {
      if (value === LOCAL_INHERIT) return LOCAL_INHERIT;
      return booleanValue(value === "true");
    },
    configScope: "session",
    configValues: {
      inherit: undefined,
      true: true,
      false: false,
    },
    effectiveValue: options.effectiveValue,
    effectiveSource: options.effectiveSource,
    inheritedValue: options.inheritedValue,
    inheritedSource: options.inheritedSource,
  };
  item.displaySuffix = coreDisplaySuffix(item);
  return item;
}

function sessionFreeflowItems(
  state: Awaited<ReturnType<typeof readCapabilityState>>,
  modeState: Awaited<ReturnType<typeof readModeState>>,
): SettingsItem[] {
  const sessionOverrides = state.sessionOverrides as Record<string, boolean>;
  const configured = state.configuredCoreConfig;
  const configuredSources = state.configuredSources as {
    enabled: ConfigSource;
    interactionContract: ConfigSource;
    skillsEnabled: ConfigSource;
  };
  const effectiveSources = state.configSources as {
    enabled: ConfigSource;
    interactionContract: ConfigSource;
    skillsEnabled: ConfigSource;
  };

  const freeflowItem = createSessionBooleanItem({
    id: "freeflow.enabled",
    label: "Freeflow",
    description: "Temporary master override for this Pi session.",
    key: "enabled",
    inheritedValue: configured.enabled,
    inheritedSource: configuredSources.enabled,
    effectiveValue: state.enabled,
    effectiveSource: effectiveSources.enabled,
    sessionOverrides,
  });
  const interactionItem = createSessionBooleanItem({
    id: "freeflow.interactionContract",
    label: "Interaction Contract",
    description: "Temporary Interaction Contract override for this Pi session.",
    key: "interactionContract",
    inheritedValue: configured.interactionContract,
    inheritedSource: configuredSources.interactionContract,
    effectiveValue: state.interactionContract.enabled,
    effectiveSource: effectiveSources.interactionContract,
    sessionOverrides,
  });
  const skillsItem = createSessionBooleanItem({
    id: "freeflow.skills.enabled",
    label: "Skills",
    description: "Temporary Freeflow Skills override for this Pi session.",
    key: "skillsEnabled",
    inheritedValue: configured.skills.enabled,
    inheritedSource: configuredSources.skillsEnabled,
    effectiveValue: state.skills.enabled,
    effectiveSource: effectiveSources.skillsEnabled,
    sessionOverrides,
  });

  const freeflowInactive = !state.enabled;
  const skillsEnabled = state.skills.enabled;
  interactionItem.inactive = freeflowInactive;
  skillsItem.inactive = freeflowInactive;

  const sessionMode = modeState.currentMode ?? "default";
  const sessionModeItem: SettingsItem = {
    id: "freeflow.sessionMode",
    label: "Mode",
    description: "Temporary mode override for this Pi session.",
    kind: "enum",
    value: sessionMode,
    values: ["default", ...MODE_VALUES],
    valueLabels: {
      ...MODE_LABELS,
      default: "Use configured default",
    },
    valueDescriptions: {
      default: `${modeState.defaultMode} from ${modeState.defaultModeSource}`,
      ...MODE_DESCRIPTIONS,
    },
    inactive: freeflowInactive || !skillsEnabled,
    displaySuffix: sessionModeDisplaySuffix(
      sessionMode,
      modeState.defaultMode,
      modeState.defaultModeSource,
      freeflowInactive || !skillsEnabled,
    ),
    inheritedValue: modeState.defaultMode,
    inheritedSource: modeState.defaultModeSource,
  };

  return [
    freeflowItem,
    interactionItem,
    skillsItem,
    sessionModeItem,
    {
      id: "freeflow.session.reset",
      label: "Reset session overrides",
      description: "Clear Freeflow, Interaction Contract, Skills, and mode overrides for this Pi session.",
      kind: "enum",
      value: "available",
      values: ["reset"],
      valueLabels: { reset: "Reset all session overrides" },
      valueDescriptions: { reset: "Return every session setting to its configured value." },
      format: () => "available",
      transient: true,
    },
  ];
}

function freeflowItems(
  rawConfig: Record<string, unknown>,
  modeState?: Awaited<ReturnType<typeof readModeState>>,
  options: {
    scope?: ConfigScope;
    layers?: Awaited<ReturnType<typeof readFreeflowConfigLayers>>;
  } = {},
): SettingsItem[] {
  const scope = options.scope ?? "repository";
  const layers = options.layers;
  const { localConfig, core, sources } = resolveSettingsCoreView(rawConfig, layers);

  const freeflowItem = createScopedBooleanItem({
    scope,
    rawConfig,
    localConfig,
    id: "freeflow.enabled",
    label: "Freeflow",
    description: "Master switch for the Interaction Contract and Freeflow skills in this checkout.",
    path: ["enabled"],
    effectiveValue: core.enabled,
    effectiveSource: sources.enabled,
    defaultValue: DEFAULT_FREEFLOW_ENABLED,
  });
  const interactionItem = createScopedBooleanItem({
    scope,
    rawConfig,
    localConfig,
    id: "freeflow.interactionContract",
    label: "Interaction Contract",
    description: "Apply Freeflow's compact turn-interpretation and collaboration guidance.",
    path: ["interactionContract"],
    effectiveValue: core.interactionContract,
    effectiveSource: sources.interactionContract,
    defaultValue: DEFAULT_INTERACTION_CONTRACT_ENABLED,
  });
  const skillsItem = createScopedBooleanItem({
    scope,
    rawConfig,
    localConfig,
    id: "freeflow.skills.enabled",
    label: "Skills",
    description: "Expose Freeflow skills and load Workflow once on the first turn.",
    path: ["skills", "enabled"],
    effectiveValue: core.skills.enabled,
    effectiveSource: sources.skillsEnabled,
    defaultValue: DEFAULT_SKILLS_ENABLED,
  });

  const repositoryModeValue = validModeOrUndefined(rawConfig.defaultMode);
  const repositoryDefaultMode = repositoryModeValue ?? "workflow";
  const repositoryDefaultSource: ConfigSource = repositoryModeValue ? "repository" : "builtin";
  const localDefaultMode = validModeOrUndefined(localConfig.defaultMode);
  const defaultModeItem = createScopedDefaultModeItem({
    scope,
    repositoryDefaultMode,
    repositoryDefaultSource,
    localDefaultMode,
    effectiveValue: core.defaultMode,
    effectiveSource: sources.defaultMode,
  });

  const freeflowInactive = !core.enabled;
  const skillsEnabled = core.skills.enabled;
  interactionItem.inactive = freeflowInactive;
  skillsItem.inactive = freeflowInactive;
  defaultModeItem.inactive = freeflowInactive;
  defaultModeItem.displaySuffix = coreDisplaySuffix(defaultModeItem, freeflowInactive || !skillsEnabled);
  const sessionMode = modeState?.currentMode ?? "default";
  const sessionModeItem: SettingsItem = {
    id: "freeflow.sessionMode",
    label: "Session mode",
    description:
      "Temporary mode override for this Pi session. Use configured default clears the override without changing either config file.",
    kind: "enum",
    value: sessionMode,
    values: ["default", ...MODE_VALUES],
    valueLabels: {
      ...MODE_LABELS,
      default: "Use configured default",
    },
    valueDescriptions: {
      default: `${core.defaultMode} from ${sources.defaultMode}`,
      ...MODE_DESCRIPTIONS,
    },
    inactive: freeflowInactive || !skillsEnabled,
    displaySuffix: sessionModeDisplaySuffix(
      sessionMode,
      core.defaultMode,
      sources.defaultMode,
      freeflowInactive || !skillsEnabled,
    ),
  };

  const routerItems = outputRouterItems(rawConfig, freeflowInactive);
  const routerEnabled = groupEnabled(routerItems, "outputRouter.enabled");

  return [
    freeflowItem,
    interactionItem,
    skillsItem,
    sessionModeItem,
    defaultModeItem,
    {
      id: "outputRouter.group",
      label: "Output Router",
      description:
        "Shared repository settings for routed evidence tools, native output safety net, vault storage, script transforms, and observed tool routing.",
      kind: "group",
      value: routerEnabled,
      inactive: freeflowInactive,
      displaySuffix: "(repository)",
      children: routerItems,
    },
  ];
}

function migrateLegacyRouterConfig(config: Record<string, unknown>) {
  const outputRouter = isRecord(config.outputRouter) ? config.outputRouter : undefined;
  if (!outputRouter) return;
  if (config.scriptTransform !== undefined && outputRouter.scriptTransform === undefined) {
    outputRouter.scriptTransform = config.scriptTransform;
    delete config.scriptTransform;
  }
  if (config.observedRouting !== undefined && outputRouter.observedRouting === undefined) {
    outputRouter.observedRouting = config.observedRouting;
    delete config.observedRouting;
  }

  const thresholds = isRecord(outputRouter.thresholds) ? outputRouter.thresholds : {};
  if (outputRouter.largeOutputBytes !== undefined && thresholds.largeOutputBytes === undefined) {
    thresholds.largeOutputBytes = outputRouter.largeOutputBytes;
    outputRouter.thresholds = thresholds;
    delete outputRouter.largeOutputBytes;
  }
  if (outputRouter.largeOutputLines !== undefined && thresholds.largeOutputLines === undefined) {
    thresholds.largeOutputLines = outputRouter.largeOutputLines;
    outputRouter.thresholds = thresholds;
    delete outputRouter.largeOutputLines;
  }

  const vault = isRecord(outputRouter.vault) ? outputRouter.vault : {};
  if (outputRouter.vaultRoot !== undefined && vault.root === undefined) {
    vault.root = outputRouter.vaultRoot;
    outputRouter.vault = vault;
    delete outputRouter.vaultRoot;
  }
  if (outputRouter.vaultRetentionDays !== undefined && !isRecord(vault.retention)) {
    vault.retention = {
      strategy: "ttl",
      ttlDays: outputRouter.vaultRetentionDays,
    };
    outputRouter.vault = vault;
    delete outputRouter.vaultRetentionDays;
  }

  const hints = isRecord(outputRouter.hints) ? outputRouter.hints : {};
  if (outputRouter.generatedPaths !== undefined && hints.generatedPathGlobs === undefined) {
    hints.generatedPathGlobs = outputRouter.generatedPaths;
    outputRouter.hints = hints;
    delete outputRouter.generatedPaths;
  }
  if (outputRouter.noisyCommandHints !== undefined && hints.noisyCommandPatterns === undefined) {
    hints.noisyCommandPatterns = outputRouter.noisyCommandHints;
    outputRouter.hints = hints;
    delete outputRouter.noisyCommandHints;
  }
}

function pruneKnownDefaults(config: Record<string, unknown>) {
  const defaultPaths: Array<{ path: string[]; value: unknown }> = [
    { path: ["enabled"], value: DEFAULT_FREEFLOW_ENABLED },
    {
      path: ["interactionContract"],
      value: DEFAULT_INTERACTION_CONTRACT_ENABLED,
    },
    { path: ["skills", "enabled"], value: DEFAULT_SKILLS_ENABLED },
    { path: ["outputRouter", "enabled"], value: DEFAULT_OUTPUT_ROUTER_ENABLED },
    {
      path: ["outputRouter", "postToolRouting"],
      value: DEFAULT_POST_TOOL_ROUTING,
    },
    { path: ["outputRouter", "storagePolicy"], value: DEFAULT_STORAGE_POLICY },
    {
      path: ["outputRouter", "thresholds", "largeOutputBytes"],
      value: DEFAULT_ROUTER_THRESHOLDS.largeOutputBytes,
    },
    {
      path: ["outputRouter", "thresholds", "largeOutputLines"],
      value: DEFAULT_ROUTER_THRESHOLDS.largeOutputLines,
    },
    { path: ["outputRouter", "vault", "root"], value: DEFAULT_VAULT_ROOT },
    {
      path: ["outputRouter", "vault", "retention", "ttlDays"],
      value: DEFAULT_VAULT_RETENTION.ttlDays,
    },
    {
      path: ["outputRouter", "scriptTransform", "enabled"],
      value: DEFAULT_SCRIPT_TRANSFORM_CONFIG.enabled,
    },
    {
      path: ["outputRouter", "scriptTransform", "sandbox"],
      value: DEFAULT_SCRIPT_TRANSFORM_CONFIG.sandbox,
    },
    {
      path: ["outputRouter", "scriptTransform", "languages"],
      value: DEFAULT_SCRIPT_TRANSFORM_CONFIG.languages,
    },
    {
      path: ["outputRouter", "scriptTransform", "network"],
      value: DEFAULT_SCRIPT_TRANSFORM_CONFIG.network,
    },
    {
      path: ["outputRouter", "scriptTransform", "rawScriptPersistence"],
      value: DEFAULT_SCRIPT_TRANSFORM_CONFIG.rawScriptPersistence,
    },
    {
      path: ["outputRouter", "scriptTransform", "limits", "timeoutMs"],
      value: DEFAULT_SCRIPT_TRANSFORM_CONFIG.limits.timeoutMs,
    },
    {
      path: ["outputRouter", "scriptTransform", "limits", "maxInputBytes"],
      value: DEFAULT_SCRIPT_TRANSFORM_CONFIG.limits.maxInputBytes,
    },
    {
      path: ["outputRouter", "scriptTransform", "limits", "maxOutputBytes"],
      value: DEFAULT_SCRIPT_TRANSFORM_CONFIG.limits.maxOutputBytes,
    },
    {
      path: ["outputRouter", "observedRouting", "enabled"],
      value: DEFAULT_OBSERVED_ROUTING_CONFIG.enabled,
    },
    {
      path: ["outputRouter", "observedRouting", "onRoutingFailure"],
      value: DEFAULT_OBSERVED_ROUTING_CONFIG.onRoutingFailure,
    },
    {
      path: ["outputRouter", "observedRouting", "mcp", "servers"],
      value: DEFAULT_OBSERVED_ROUTING_CONFIG.mcp.servers,
    },
    {
      path: ["outputRouter", "observedRouting", "web", "enabled"],
      value: DEFAULT_OBSERVED_ROUTING_CONFIG.web.enabled,
    },
    {
      path: ["outputRouter", "observedRouting", "fetch", "enabled"],
      value: DEFAULT_OBSERVED_ROUTING_CONFIG.fetch.enabled,
    },
    {
      path: ["outputRouter", "observedRouting", "codeSearch", "enabled"],
      value: DEFAULT_OBSERVED_ROUTING_CONFIG.codeSearch.enabled,
    },
  ];

  for (const item of defaultPaths) {
    if (valuesEqual(getPath(config, item.path), item.value)) {
      deletePath(config, item.path);
    }
  }

  for (const producer of ["web", "fetch", "codeSearch"]) {
    const enabledPath = ["outputRouter", "observedRouting", producer, "enabled"];
    const persistencePath = ["outputRouter", "observedRouting", producer, "persistence"];
    if (getPath(config, enabledPath) !== true && getPath(config, persistencePath) === "none") {
      deletePath(config, persistencePath);
    }
  }

  const servers = getPath(config, ["outputRouter", "observedRouting", "mcp", "servers"]);
  if (isRecord(servers) && Object.keys(servers).length === 0) {
    deletePath(config, ["outputRouter", "observedRouting", "mcp", "servers"]);
  }
}

async function ensureLocalConfigIgnored(cwd: string) {
  let gitPath: string;
  try {
    const result = await execFileAsync("git", ["-C", cwd, "rev-parse", "--git-path", "info/exclude"]);
    gitPath = result.stdout.trim();
  } catch {
    return;
  }

  const tracked = await execFileAsync("git", ["-C", cwd, "ls-files", "--", ".freeflow/local.json"]);
  if (tracked.stdout.trim()) {
    throw new Error(
      ".freeflow/local.json is tracked by git; remove it from the index before writing personal overrides.",
    );
  }

  try {
    await execFileAsync("git", ["-C", cwd, "check-ignore", "-q", "--", ".freeflow/local.json"]);
    return;
  } catch {
    // Add a local exclude when the repository does not already ignore the file.
  }

  const excludePath = isAbsolute(gitPath) ? gitPath : resolve(cwd, gitPath);
  let existing = "";
  try {
    existing = await readFile(excludePath, "utf8");
  } catch {
    // The git metadata path may not exist yet in a minimal repository.
  }
  const rule = ".freeflow/local.json";
  if (existing.split(/\r?\n/).includes(rule)) return;
  await mkdir(dirname(excludePath), { recursive: true });
  const prefix = existing && !existing.endsWith("\n") ? "\n" : "";
  await appendFile(excludePath, `${prefix}${rule}\n`, "utf8");
}

async function updateConfig(
  cwd: string,
  item: SettingsItem,
  value: unknown,
  scope: ConfigScope = item.configScope ?? "repository",
) {
  if (scope === "local") {
    if (!item.path?.length) {
      throw new Error(`${item.label} is a settings group, not a writable setting.`);
    }
    const current = await readFreeflowLocalConfig(cwd);
    const next = cloneJson(current) as Record<string, unknown>;
    const configValue = configValueForChoice(item, value);
    const previousValue = getPath(current, item.path);
    if (configValue === undefined || isEmptyValue(configValue)) {
      if (previousValue === undefined) return;
      deletePath(next, item.path);
    } else {
      setPath(next, item.path, configValue);
    }
    const path = join(cwd, ".freeflow/local.json");
    await ensureLocalConfigIgnored(cwd);
    if (Object.keys(next).length === 0) {
      await rm(path, { force: true });
      return;
    }
    await mkdir(join(cwd, ".freeflow"), { recursive: true });
    await writeFile(path, `${JSON.stringify(next, null, 2)}\n`, "utf8");
    return;
  }

  const current = await readFreeflowConfig(cwd);
  const next = cloneJson(current) as Record<string, unknown>;
  setConfigValue(next, item, value);
  migrateLegacyRouterConfig(next);
  pruneKnownDefaults(next);
  await mkdir(join(cwd, ".freeflow"), { recursive: true });
  await writeFile(join(cwd, ".freeflow/config.json"), `${JSON.stringify(next, null, 2)}\n`, "utf8");
}

function valueForDisplay(item: SettingsItem): string {
  let value: string;
  if (item.configScope === "local" || item.configScope === "session") {
    value = formatCoreValue(effectiveItemValue(item));
  } else if (item.kind === "boolean") {
    value = booleanValue(item.value);
  } else if (item.kind === "group") {
    const status = typeof item.value === "boolean" ? booleanValue(item.value) : String(item.value ?? "");
    const count = item.children?.length ?? 0;
    value = count > 0 ? `${status} (${count})` : status;
  } else if (item.format) {
    value = item.format(item.value);
  } else {
    value = String(item.value ?? "");
  }
  return item.displaySuffix ? `${value} ${item.displaySuffix}` : value;
}

function walkSettingsItems(items: SettingsItem[], visitor: (item: SettingsItem) => void) {
  for (const item of items) {
    visitor(item);
    if (item.children) walkSettingsItems(item.children, visitor);
  }
}

function findSettingsItem(items: SettingsItem[], id: string): SettingsItem | undefined {
  for (const item of items) {
    if (item.id === id) return item;
    const child = item.children ? findSettingsItem(item.children, id) : undefined;
    if (child) return child;
  }
  return undefined;
}

function refreshSettingsDerivedState(items: SettingsItem[]) {
  const freeflowItem = findSettingsItem(items, "freeflow.enabled");
  const freeflowInactive = freeflowItem ? effectiveItemValue(freeflowItem) !== true : false;
  const skillsItem = findSettingsItem(items, "freeflow.skills.enabled");
  const skillsEnabled = skillsItem ? effectiveItemValue(skillsItem) === true : true;
  const routerEnabled = findSettingsItem(items, "outputRouter.enabled")?.value === true;
  const sessionModeItem = findSettingsItem(items, "freeflow.sessionMode");
  const defaultModeItem = findSettingsItem(items, "freeflow.defaultMode");
  const routerGroup = findSettingsItem(items, "outputRouter.group");

  if (sessionModeItem) {
    const defaultMode = String(
      defaultModeItem ? effectiveItemValue(defaultModeItem) : (sessionModeItem.inheritedValue ?? "workflow"),
    );
    const defaultSource = defaultModeItem?.effectiveSource ?? sessionModeItem.inheritedSource ?? "builtin";
    sessionModeItem.inactive = freeflowInactive || !skillsEnabled;
    sessionModeItem.displaySuffix = sessionModeDisplaySuffix(
      String(sessionModeItem.value),
      defaultMode,
      defaultSource,
      freeflowInactive || !skillsEnabled,
    );
    sessionModeItem.valueDescriptions = {
      default: `${defaultMode} from ${defaultSource}`,
      ...MODE_DESCRIPTIONS,
    };
  }

  if (routerGroup) {
    routerGroup.value = routerEnabled;
    routerGroup.inactive = freeflowInactive;
  }

  walkSettingsItems(items, (candidate) => {
    if (candidate.id === "freeflow.session.reset") {
      candidate.inactive = false;
    } else if (candidate.configScope) {
      const inactive = candidate.id === "freeflow.enabled" ? false : freeflowInactive;
      const displayInactive = candidate.id === "freeflow.defaultMode" ? freeflowInactive || !skillsEnabled : inactive;
      candidate.inactive = inactive;
      candidate.displaySuffix = coreDisplaySuffix(candidate, displayInactive);
    } else if (candidate.id === "freeflow.sessionMode") {
      candidate.inactive = freeflowInactive || !skillsEnabled;
    } else if (candidate.id === "outputRouter.group") {
      candidate.inactive = freeflowInactive;
    } else if (candidate.id === "outputRouter.enabled") {
      candidate.inactive = freeflowInactive;
    } else if (candidate.id.startsWith("outputRouter.")) {
      candidate.inactive = freeflowInactive || !routerEnabled;
    } else {
      candidate.inactive = freeflowInactive;
    }
  });
}

function settingsChoices(item: SettingsItem) {
  if (item.kind === "boolean") {
    return [
      { key: "true", value: true, label: "enabled", description: "Enable this setting." },
      { key: "false", value: false, label: "disabled", description: "Disable this setting." },
    ];
  }
  if (item.kind !== "enum") return undefined;
  return (item.values ?? []).map((value) => ({
    key: value,
    value,
    label: item.valueLabels?.[value] ?? value,
    description: item.valueDescriptions?.[value],
  }));
}

function resetSessionItemState(items: SettingsItem[]) {
  walkSettingsItems(items, (item) => {
    if (item.configScope === "session") {
      item.value = LOCAL_INHERIT;
      item.effectiveValue = item.inheritedValue;
      item.effectiveSource = item.inheritedSource ?? "builtin";
    } else if (item.id === "freeflow.sessionMode") {
      item.value = "default";
    }
  });
}

function settingsEntries(
  items: SettingsItem[],
  rootItems: SettingsItem[],
  onChange: OpenSettingsOptions["onChange"],
): SettingsEntry[] {
  return items.map((item) => ({
    id: item.id,
    label: item.label,
    description: item.description,
    currentValue: () => valueForDisplay(item),
    inactive: () => item.inactive === true,
    currentChoiceKey: () => String(item.value),
    choices: settingsChoices(item),
    children: item.children ? () => settingsEntries(item.children!, rootItems, onChange) : undefined,
    edit:
      !item.children && !["boolean", "enum", "group"].includes(item.kind)
        ? {
            initialValue: () => valueForDisplay(item),
            parse: (text: string) => (item.parse ? item.parse(text) : text),
          }
        : undefined,
    commit:
      item.kind === "group"
        ? undefined
        : async (value: unknown) => {
            if (valuesEqual(item.value, value)) return { changed: false, reloadRequired: false };
            const outcome = await onChange(item, value);
            if (outcome.changed) {
              updateScopedItemState(item, value);
              if (item.id === "freeflow.session.reset") {
                resetSessionItemState(rootItems);
              } else if (!item.transient) {
                item.value = value;
              }
              refreshSettingsDerivedState(rootItems);
            }
            return outcome;
          },
  }));
}

async function openSettings(options: OpenSettingsOptions): Promise<SettingsSessionResult> {
  if (typeof options.ctx?.ui?.custom !== "function") {
    options.ctx?.ui?.notify?.(
      `${options.title} requires Pi TUI mode. Use the status command for a compact summary.`,
      "warning",
    );
    return { changed: false, configChanged: false, failed: false };
  }

  const entries = settingsEntries(options.items, options.items, options.onChange);
  const initialChoice = options.initialChoice
    ? entries.find((entry) => entry.id === options.initialChoice?.id)
    : undefined;
  let component: PiSettingsComponent | undefined;
  await options.ctx.ui.custom((tui: any, theme: any, _keybindings: unknown, done: (value?: undefined) => void) => {
    component = new PiSettingsComponent({
      title: options.title,
      entries,
      initialChoice,
      theme: theme ?? {},
      requestRender: () => tui.requestRender(),
      notify: (message, level) => options.ctx?.ui?.notify?.(message, level),
      done,
    });
    return component;
  });

  await component?.waitForWrites();
  return component?.sessionResult() ?? { changed: false, configChanged: false, failed: false };
}

function outputRouterStatusText(rawConfig: Record<string, unknown>): string {
  const settingsConfig = normalizedSettingsConfig(rawConfig);
  const actual = normalizeFreeflowConfig(rawConfig).config;
  const freeflowEnabled = rawConfig.enabled !== false;
  const router = actual.outputRouter;
  const configured = settingsConfig;
  const generatedPaths = router.hints?.generatedPathGlobs?.length ?? 0;
  const noisyHints = router.hints?.noisyCommandPatterns?.length ?? 0;
  return [
    `Output Router: ${freeflowEnabled && router.enabled ? "enabled" : "disabled"}${freeflowEnabled ? "" : " (inactive: Freeflow off)"}`,
    `script transform: ${freeflowEnabled && configured.scriptTransform.enabled ? "enabled" : "disabled"}${freeflowEnabled && router.enabled ? "" : " (inactive)"}`,
    `observed routing: ${freeflowEnabled && configured.observedRouting.enabled ? "enabled" : "disabled"}${freeflowEnabled && router.enabled ? "" : " (inactive)"}`,
    `native safety net: ${freeflowEnabled ? router.postToolRouting : "off"}`,
    `storage: ${router.storagePolicy}`,
    `generated paths: ${generatedPaths}`,
    `noisy command hints: ${noisyHints}`,
  ].join("; ");
}

function freeflowStatusText(state: Awaited<ReturnType<typeof readCapabilityState>>): string {
  if (!state.configured) {
    return state.configExists
      ? `Freeflow: inactive (invalid config: ${state.parseError ?? "unknown parse error"}); run /setup-freeflow or fix .freeflow/config.json`
      : "Freeflow: inactive (repo not set up); run /setup-freeflow";
  }
  const sessionSuffix = (source: ConfigSource) => (source === "session" ? " (session override)" : "");
  return [
    `Freeflow: ${state.enabled ? "enabled" : "disabled"}${sessionSuffix(state.configSources.enabled as ConfigSource)}`,
    `interaction contract: ${state.interactionContract.effective ? "enabled" : "disabled"}${sessionSuffix(
      state.configSources.interactionContract as ConfigSource,
    )}`,
    `skills: ${state.skills.effective ? "enabled" : "disabled (workflow modes inactive)"}${sessionSuffix(
      state.configSources.skillsEnabled as ConfigSource,
    )}`,
    `output router: ${state.outputRouter.enabled ? "enabled" : "disabled"}`,
  ].join("; ");
}

const NON_TUI_SETTINGS_GUIDANCE =
  "Freeflow settings require Pi TUI mode. Use /freeflow status to inspect current state; supported non-TUI changes are /freeflow enable, /freeflow disable, and /freeflow mode <conversation|workflow|strict-workflow|reset>.";
const NON_TUI_MODE_GUIDANCE =
  "Freeflow mode selector requires Pi TUI mode. Use /freeflow mode conversation, /freeflow mode workflow, /freeflow mode strict-workflow, or /freeflow mode reset.";

function nonTuiGuidance(ctx: any, message: string) {
  if (ctx?.hasUI === false) throw new Error(message);
  ctx?.ui?.notify?.(message, "warning");
  return { changed: false, reloaded: false, error: "tui_required" };
}

async function finalizeSettingsSession(
  session: SettingsSessionResult,
  ctx: any,
  afterChange: (changed: boolean) => Promise<void> | void,
  savedMessage: string,
  reloadWarning = "Run /reload for Freeflow changes to fully apply.",
) {
  if (!session.configChanged) return false;

  await afterChange(true);
  if (session.failed) return false;

  ctx.ui.notify(savedMessage, "info");
  if (typeof ctx.reload !== "function") {
    ctx.ui.notify(reloadWarning, "warning");
    return false;
  }

  await ctx.reload();
  return true;
}

async function finalizeSessionSettings(
  session: SettingsSessionResult,
  ctx: any,
  afterChange: (changed: boolean) => Promise<void> | void,
) {
  if (!session.changed) return false;

  await afterChange(true);
  if (session.failed) return false;
  if (!session.configChanged) {
    ctx.ui.notify("Freeflow session overrides updated.", "info");
    return false;
  }

  ctx.ui.notify("Freeflow session overrides updated. Reloading skills and resources...", "info");
  if (typeof ctx.reload !== "function") {
    ctx.ui.notify("Run /reload for Freeflow session overrides to fully apply.", "warning");
    return false;
  }

  await ctx.reload();
  return true;
}

function actionIsMutation(action: string): boolean {
  return action === "" || action === "settings" || ["enable", "on", "true", "disable", "off", "false"].includes(action);
}

async function maybeBlockLayerMutation(action: string, ctx: any, layerName: string) {
  if (!actionIsMutation(action)) return false;
  const state = await readCapabilityState(ctx.cwd);
  if (!state.configured) {
    ctx.ui.notify(
      `Freeflow is installed but this repo is not set up. Run /setup-freeflow before configuring ${layerName}.`,
      "warning",
    );
    return true;
  }
  if (!state.enabled) {
    ctx.ui.notify(
      `Freeflow is disabled for this repo. Use /freeflow enable before configuring ${layerName}.`,
      "warning",
    );
    return true;
  }
  return false;
}

export async function handleFreeflowCommand(
  args: string | undefined,
  ctx: any,
  afterChange: (changed: boolean) => Promise<void> | void,
  pi: any,
) {
  const input = (args ?? "settings").trim().toLowerCase() || "settings";
  const [action, ...rest] = input.split(/\s+/);
  const actionValue = rest.join(" ");
  const nonTui = ctx?.mode && ctx.mode !== "tui";
  if (nonTui && action === "mode" && !actionValue) {
    return nonTuiGuidance(ctx, NON_TUI_MODE_GUIDANCE);
  }
  const settingsSelector =
    action === "settings" &&
    (!actionValue || ["session", "local", "personal", "repo", "repository", "shared"].includes(actionValue));
  if (nonTui && settingsSelector) {
    return nonTuiGuidance(ctx, NON_TUI_SETTINGS_GUIDANCE);
  }

  const [layers, state, modeState] = await Promise.all([
    readFreeflowConfigLayers(ctx.cwd),
    readCapabilityState(ctx.cwd),
    readModeState(ctx.cwd),
  ]);
  const configState = layers.repository;
  const raw = configState.valid ? configState.parsed : {};

  if (action === "status") {
    ctx.ui.notify(freeflowStatusText(state), "info");
    return { changed: false, reloaded: false };
  }

  if (!configState.valid) {
    ctx.ui.notify(freeflowStatusText(state), "warning");
    return { changed: false, reloaded: false, error: "not_configured" };
  }
  if (layers.local.exists && !layers.local.valid) {
    ctx.ui.notify(
      `.freeflow/local.json is invalid; repair or remove it before changing Freeflow settings. ${layers.local.parseError ?? ""}`.trim(),
      "warning",
    );
    return { changed: false, reloaded: false, error: "invalid_local_config" };
  }

  if (action === "mode") {
    if (actionValue) {
      const result = await handleModeCommand(actionValue, ctx, pi);
      return { changed: result.changed, reloaded: false, error: result.error };
    }
    if (!state.enabled || !state.skills.effective) {
      const result = await handleModeCommand(undefined, ctx, pi);
      return { changed: false, reloaded: false, error: result.error };
    }
    if (typeof ctx?.ui?.custom !== "function") {
      const result = await handleModeCommand(undefined, ctx, pi);
      return { changed: false, reloaded: false, error: result.error };
    }

    const item = freeflowItems(raw, modeState, {
      scope: "local",
      layers,
    }).find((candidate) => candidate.id === "freeflow.sessionMode")!;
    const session = await openSettings({
      title: "Freeflow Mode",
      items: [item],
      initialChoice: item,
      ctx,
      onChange: async (_item, value) => {
        const result = await handleModeCommand(String(value), ctx, pi);
        return { changed: result.changed, reloadRequired: false };
      },
    });
    return { changed: session.changed, reloaded: false, error: session.failed ? "write_failed" : undefined };
  }

  if (["enable", "on", "true", "disable", "off", "false"].includes(action)) {
    const enabled = ["enable", "on", "true"].includes(action);
    const item = freeflowItems(raw, modeState, {
      scope: "repository",
      layers,
    }).find((candidate) => candidate.id === "freeflow.enabled")!;
    await updateConfig(ctx.cwd, item, enabled, "repository");
    await afterChange(true);
    ctx.ui.notify(`Freeflow ${enabled ? "enabled" : "disabled"}. Reloading Freeflow runtime...`, "info");
    if (typeof ctx.reload === "function") {
      await ctx.reload();
      return { changed: true, reloaded: true };
    }
    ctx.ui.notify("Run /reload for Freeflow changes to fully apply.", "warning");
    return { changed: true, reloaded: false };
  }

  if (action && action !== "settings") {
    ctx.ui.notify(
      "Usage: /freeflow, /freeflow settings [local|repo], /freeflow status, /freeflow mode [conversation|workflow|strict-workflow|reset], /freeflow enable, or /freeflow disable",
      "warning",
    );
    return { changed: false, reloaded: false, error: "invalid_action" };
  }

  let settingsScope: ConfigScope = "local";
  if (actionValue === "session") {
    settingsScope = "session";
  } else if (["repo", "repository", "shared"].includes(actionValue)) {
    settingsScope = "repository";
  } else if (actionValue && !["local", "personal"].includes(actionValue)) {
    ctx.ui.notify(
      "Usage: /freeflow settings, /freeflow settings session, /freeflow settings local, or /freeflow settings repo",
      "warning",
    );
    return { changed: false, reloaded: false, error: "invalid_scope" };
  }

  const items =
    settingsScope === "session"
      ? sessionFreeflowItems(state, modeState)
      : freeflowItems(raw, modeState, { scope: settingsScope, layers });
  const session = await openSettings({
    title:
      settingsScope === "session"
        ? "Freeflow Settings · Session overrides"
        : settingsScope === "local"
          ? "Freeflow Settings · Personal overrides"
          : "Freeflow Repository Settings · modifies .freeflow/config.json",
    items,
    ctx,
    onChange: async (item, value) => {
      if (item.id === "freeflow.sessionMode") {
        const result = await handleModeCommand(String(value), ctx, pi);
        return { changed: result.changed, reloadRequired: false };
      }
      if (item.id === "freeflow.session.reset") {
        const result = await resetSessionOverrides(ctx, pi);
        return { changed: result.changed, reloadRequired: result.reloadRequired };
      }
      if (item.configScope === "session") {
        const keyById = {
          "freeflow.enabled": "enabled",
          "freeflow.interactionContract": "interactionContract",
          "freeflow.skills.enabled": "skillsEnabled",
        } as const;
        const key = keyById[item.id as keyof typeof keyById];
        const override = value === LOCAL_INHERIT ? null : value === "true";
        const result = await setSessionCoreOverride(key, override, ctx, pi);
        return { changed: result.changed, reloadRequired: result.reloadRequired === true };
      }
      await updateConfig(ctx.cwd, item, value, item.configScope ?? "repository");
      return { changed: true, reloadRequired: true };
    },
  });

  if (settingsScope === "session") {
    const reloaded = await finalizeSessionSettings(session, ctx, afterChange);
    return { changed: session.changed, reloaded, error: session.failed ? "write_failed" : undefined };
  }

  const savedTarget = settingsScope === "local" ? "personal overrides" : "repository settings";
  const reloaded = await finalizeSettingsSession(
    session,
    ctx,
    afterChange,
    `Freeflow ${savedTarget} saved. Reloading Freeflow runtime...`,
  );
  return { changed: session.changed, reloaded, error: session.failed ? "write_failed" : undefined };
}

export async function handleOutputRouterCommand(
  args: string | undefined,
  ctx: any,
  afterChange: (changed: boolean) => Promise<void> | void,
) {
  const action = (args ?? "").trim().toLowerCase();
  const raw = await readFreeflowConfig(ctx.cwd);

  if (await maybeBlockLayerMutation(action, ctx, "Output Router")) {
    return { changed: false, reloaded: false, error: "freeflow_inactive" };
  }

  if (action === "status") {
    const state = await readCapabilityState(ctx.cwd);
    const prefix = !state.configured || !state.enabled ? `${freeflowStatusText(state)}; ` : "";
    ctx.ui.notify(`${prefix}${outputRouterStatusText(raw)}`, !state.configured || !state.enabled ? "warning" : "info");
    return { changed: false, reloaded: false };
  }

  if (["enable", "on", "true", "disable", "off", "false"].includes(action)) {
    const enabled = ["enable", "on", "true"].includes(action);
    const item = outputRouterItems(raw).find((candidate) => candidate.id === "outputRouter.enabled")!;
    await updateConfig(ctx.cwd, item, enabled);
    await afterChange(true);
    ctx.ui.notify(`Output Router ${enabled ? "enabled" : "disabled"}. Reloading Freeflow runtime...`, "info");
    if (typeof ctx.reload === "function") {
      await ctx.reload();
      return { changed: true, reloaded: true };
    }
    ctx.ui.notify("Run /reload for Output Router changes to fully apply.", "warning");
    return { changed: true, reloaded: false };
  }

  if (action && action !== "settings") {
    ctx.ui.notify("Usage: /output-router, /output-router settings, or /output-router status", "warning");
    return { changed: false, reloaded: false, error: "invalid_action" };
  }

  const session = await openSettings({
    title: "Output Router Settings",
    items: outputRouterItems(raw),
    ctx,
    onChange: async (item, value) => {
      await updateConfig(ctx.cwd, item, value);
      return { changed: true, reloadRequired: true };
    },
  });

  const reloaded = await finalizeSettingsSession(
    session,
    ctx,
    afterChange,
    "Output Router settings saved. Reloading Freeflow runtime...",
    "Run /reload for Output Router changes to fully apply.",
  );
  return { changed: session.changed, reloaded, error: session.failed ? "write_failed" : undefined };
}