@edspencer/paddock 0.71.1 → 0.72.0

package/packages/server/dist/instance-config.js

@@ -38,7 +38,8 @@ import { DEFAULT_ATTACHMENTS, sanitizeAllowedTypes } from "./attachments-config.
 import { DEFAULT_CURATION } from "./curation-config.js";
 import { DEFAULT_ENVIRONMENT_PROMPT } from "./environment-prompt.js";
 import { CONFIG_SCHEMA_VERSION, SCHEMA_VERSION_KEY } from "./schema-version.js";
-import { DEFAULT_TRANSCRIPTS_MODE } from "./transcripts.js";
+import { DEFAULT_PROFILE, POSTURE_KEYS, PROFILE_NAMES, isKnownProfile, posture as postureFor, } from "./profiles.js";
+import { DEFAULT_TRANSCRIPTS_MODE, isKnownTranscriptsMode, } from "./transcripts.js";
 import { DEFAULT_CREDENTIALS_MODE } from "./claude-credentials.js";
 import { DEFAULT_INSTRUCTIONS_MODE } from "./claude-instructions.js";
 import { DEFAULT_HOOKS_MODE } from "./claude-settings.js";
@@ -54,7 +55,7 @@ export const GROUPS = [
     { id: "transcription", label: "Transcription" },
     { id: "git", label: "Git identity" },
     { id: "logging", label: "Logging" },
-    { id: "advanced", label: "Advanced (read-only)", description: "Process / filesystem bindings. Change these via env/redeploy, not the UI." },
+    { id: "advanced", label: "Advanced (read-only)", description: "The instance's posture profile, its process / filesystem bindings, and what it shares with the Claude Code CLI on this machine. Change these via env/redeploy, not the UI." },
 ];
 // --- coercion helpers -------------------------------------------------------
 const asBool = (raw) => typeof raw === "boolean" ? { ok: true, value: raw } : { ok: false, error: "must be a boolean" };
@@ -284,6 +285,21 @@ export const FIELDS = [
     // Logging.
     { key: "logLevel", group: "logging", label: "Log level", type: "enum", enumValues: LOG_LEVELS, envVars: ["LOG_LEVEL"], default: "info", editable: true, coerce: oneOf(LOG_LEVELS) },
     // Advanced — read-only display (process / filesystem bindings).
+    //
+    // The posture profile (#878) leads the group because it is the row that
+    // EXPLAINS the others: it supplies the default for the five `claude.` modes
+    // below and for seven of the Capabilities toggles above, and every field it is
+    // actually responsible for is reported with `fromProfile` so the UI can say so
+    // on the row itself.
+    //
+    // READ-ONLY, and not for the usual advanced-group reason. A writable profile
+    // row would set exactly the five `claude.` keys below — the ones that are
+    // read-only because their symlinks are planted at agent-registration time, so
+    // a live toggle silently does nothing until the next boot. Making the profile
+    // editable would reintroduce that through the back door, and worse: one
+    // control that no-ops five levers at once. Change it in `paddock.config.yaml`
+    // or `PADDOCK_PROFILE` and restart, which is what the value here reflects.
+    { key: "profile", group: "advanced", label: "Posture profile", help: "The named security/capability posture this instance resolved at boot. It sets the default for the Claude sharing modes below and most of the Capabilities toggles; anything set explicitly in this file or the environment still wins over it.", type: "enum", enumValues: PROFILE_NAMES, envVars: ["PADDOCK_PROFILE"], default: DEFAULT_PROFILE, editable: false },
     { key: "port", group: "advanced", label: "Port", type: "number", envVars: ["PORT"], default: 7233, editable: false },
     { key: "host", group: "advanced", label: "Host", type: "string", envVars: ["HOST", "PADDOCK_HOST"], default: "127.0.0.1", editable: false },
     { key: "dataDir", group: "advanced", label: "Data dir", type: "string", envVars: ["PADDOCK_DATA_DIR"], default: null, editable: false },
@@ -396,6 +412,32 @@ function readConfigFileSnapshot(configPath) {
 export function instanceConfigVersion(configPath) {
     return readConfigFileSnapshot(configPath).version;
 }
+/**
+ * The transcripts mode a RESTART would resolve — read from the config FILE,
+ * falling back to the profile's default when the file is silent about it.
+ *
+ * NOT `cfg.claude.transcripts`, which is what THIS process froze at boot. The
+ * two differ for the whole window between a successful `own → host` migration
+ * (#882) and the restart it asks for, and that window is precisely when a
+ * second POST arrives: without this the idempotency check would see `own`,
+ * decide nothing had happened, and re-run a migration that already had.
+ *
+ * The environment is deliberately not consulted. `PADDOCK_CLAUDE_TRANSCRIPTS`
+ * beats the file, so when it is set the true answer to "what would a restart
+ * resolve" is the env var — but a caller in that situation is already refusing
+ * with `env_shadowed`, and folding it in here would make a shadowed instance
+ * look permanently migrated.
+ */
+export function pendingTranscriptsMode(cfg) {
+    const file = readConfigFileSnapshot(instanceConfigPath(cfg));
+    const raw = file.data ? readPath(file.data, "claude.transcripts") : undefined;
+    if (typeof raw === "string" && isKnownTranscriptsMode(raw))
+        return raw;
+    const fallback = postureFor(cfg.profile).transcripts;
+    return typeof fallback === "string" && isKnownTranscriptsMode(fallback)
+        ? fallback
+        : DEFAULT_TRANSCRIPTS_MODE;
+}
 /** Structural equality for the value shapes a field can hold (scalars + string lists). */
 function valuesEqual(a, b) {
     if (Array.isArray(a) || Array.isArray(b)) {
@@ -445,7 +487,72 @@ export function instanceConfigPath(cfg) {
  *    friends are canonicalised, `port` is `Number()`-ed), so comparing them
  *    against raw file text would manufacture divergence that isn't there.
  */
+/**
+ * What this field falls back to when nothing sets it — which, for the twelve
+ * posture keys, is whatever the instance's profile says rather than the static
+ * `default` on the spec (#878).
+ *
+ * Not cosmetic: `default` is also what `pendingRestart` is computed against. A
+ * config file that simply omits `selfMcpEnabled` is *agreeing* with the profile,
+ * and scoring it against a hardcoded `false` would report a pending restart on a
+ * file that changes nothing.
+ *
+ * The mapping is by name — every posture field's key IS its `Posture` key,
+ * modulo the `claude.` prefix — so a lever added to both `FIELDS` and `Posture`
+ * is picked up here with no third list to keep in sync.
+ */
+function defaultFor(f, p) {
+    const k = postureKeyOf(f);
+    return k === null ? f.default : p[k];
+}
+/**
+ * The {@link Posture} key a field is a lever for, or `null` if the profile has
+ * no opinion about it. The mapping is by name — every posture field's key IS its
+ * `Posture` key, modulo the `claude.` prefix — so a lever added to both `FIELDS`
+ * and `Posture` is picked up with no third list to keep in sync.
+ */
+function postureKeyOf(f) {
+    const k = f.key.startsWith("claude.") ? f.key.slice("claude.".length) : f.key;
+    return POSTURE_KEYS.includes(k) ? k : null;
+}
+/**
+ * Whether the PROFILE is what put this field's effective value there (#878) — a
+ * claim the UI renders as a chip on the row, so it has to be true.
+ *
+ * Every clause here exists to stop the chip appearing on a value the profile did
+ * not choose, because a row that blames the profile for something the operator
+ * set themselves is worse than a row that says nothing:
+ *
+ *  - **not a posture key** — the profile is silent on port, auth, models, …
+ *  - **not env-shadowed** — `PADDOCK_CLAUDE_INSTRUCTIONS=own` under
+ *    `profile: balanced` resolves `own`, and the profile wanted `host`. The env
+ *    var beat it; the existing `env` chip is the honest label for that row.
+ *  - **not set in the file** — an explicit `claude: {hooks: host}` beats the
+ *    profile too (specific beats general — see `profiles.ts`), even when it
+ *    happens to agree.
+ *  - **value actually matches the posture** — belt-and-braces against a lever
+ *    that is in `POSTURE_KEYS` but whose loader never consulted the profile.
+ *    That is a real bug class, and the failure mode without this clause is the
+ *    screen confidently mislabelling it.
+ *
+ * `fileUnknown` covers the one state where we genuinely cannot tell: the config
+ * file exists but no longer parses. It parsed at boot (config.ts throws
+ * otherwise, so the process would not be running), which means the file in force
+ * is one we cannot read — so we decline to attribute rather than guess.
+ */
+function isFromProfile(f, p, value, envShadowed, file) {
+    const k = postureKeyOf(f);
+    if (k === null || envShadowed)
+        return false;
+    const fileUnknown = file.data === null && file.version !== null;
+    if (fileUnknown)
+        return false;
+    if (readPath(file.data ?? {}, f.key) != null)
+        return false;
+    return valuesEqual(value, p[k]);
+}
 export function buildInstanceConfig(cfg) {
+    const p = postureFor(cfg.profile);
     const groups = GROUPS.map((g) => ({
         id: g.id,
         label: g.label,
@@ -468,12 +575,12 @@ export function buildInstanceConfig(cfg) {
             // Absent, or present-but-null (`debounceMs:` with nothing after it), both
             // mean "no override" — `fileOr`/`fileOpt` degrade a null to the default.
             const fileRaw = readPath(file.data, f.key);
-            pendingValue = fileRaw == null ? (f.default ?? null) : coerceForDisplay(f, fileRaw);
+            pendingValue = fileRaw == null ? (defaultFor(f, p) ?? null) : coerceForDisplay(f, fileRaw);
             // A field the frozen config leaves unset IS its built-in default (that is
             // what `default` documents), so normalise before comparing — otherwise
             // e.g. `models`, unset and therefore null, would read as forever diverging
             // from the catalog list the file's absence implies.
-            const effective = value === null ? (f.default ?? null) : value;
+            const effective = value === null ? (defaultFor(f, p) ?? null) : value;
             pendingRestart = !valuesEqual(pendingValue, effective);
             if (pendingRestart)
                 restartRequired = true;
@@ -488,11 +595,12 @@ export function buildInstanceConfig(cfg) {
             value,
             pendingValue,
             pendingRestart,
-            default: f.default,
+            default: defaultFor(f, p),
             editable: f.editable,
             sensitive: f.sensitive ?? false,
             envOverridden: shadow !== undefined,
             envVar: shadow,
+            fromProfile: isFromProfile(f, p, value, shadow !== undefined, file),
         };
         groupById.get(f.group)?.fields.push(dto);
     }
@@ -611,3 +719,118 @@ export function writeInstanceConfig(configPath, pairs) {
     fs.writeFileSync(tmp, serialized, "utf8");
     fs.renameSync(tmp, configPath);
 }
+/**
+ * Fields whose effective value is a NORMALISED form of whatever the file said —
+ * paths get `abs()` + `canonical()` at boot, so `dataDir: ./data` legitimately
+ * resolves to `/home/you/data`. Comparing those two would manufacture a
+ * "your file value is not in effect" warning on a file that is working fine, so
+ * for these keys the file's mere presence settles provenance.
+ */
+const NORMALISED_AT_BOOT = new Set([
+    "dataDir",
+    "projectsRoot",
+    "stateDir",
+    "herdctlConfigPath",
+    "webDist",
+]);
+/**
+ * Did the file's value survive into the resolved config?
+ *
+ * Looser than {@link valuesEqual} for scalars on purpose: every file value goes
+ * through `String()` in `fileOr`/`fileOpt` before it is parsed, so a hand-typed
+ * `port: "7300"` and a resolved `7300` are the same decision, not a divergence.
+ */
+function fileValueTookEffect(written, effective) {
+    if (valuesEqual(written, effective))
+        return true;
+    if (written == null || effective == null)
+        return false;
+    if (typeof written === "object" || typeof effective === "object")
+        return false;
+    return String(written) === String(effective);
+}
+/**
+ * Where the profile NAME came from. Mirrors `resolveProfileName`'s precedence
+ * exactly — a non-blank `PADDOCK_PROFILE` wins outright, and notably does NOT
+ * fall through to the file when it names something unrecognised.
+ */
+function resolveProfileProvenance(name, fileData, configPath) {
+    const envRaw = process.env.PADDOCK_PROFILE?.trim();
+    const fileVal = fileData?.profile;
+    const fileRaw = fileVal === undefined || fileVal === null ? "" : String(fileVal).trim();
+    const raw = envRaw || fileRaw;
+    if (!raw)
+        return { name, source: "default" };
+    const origin = envRaw ? "PADDOCK_PROFILE" : configPath;
+    if (isKnownProfile(raw.toLowerCase())) {
+        return { name, source: envRaw ? "env" : "file", origin };
+    }
+    return { name, source: "default", unrecognised: { value: raw, origin } };
+}
+/**
+ * Resolve every field in {@link FIELDS} against a loaded config, reporting the
+ * layer each value came from.
+ *
+ * Built on the same descriptor table the Config screen uses rather than a
+ * parallel list, so a lever added for the UI is printed by the CLI for free and
+ * the two can never disagree about what a default is. What it does NOT reuse is
+ * `buildInstanceConfig`'s DTO: that answers "what would a restart change?", which
+ * needs the file compared against the process. This answers "where did each of
+ * these values come from?", which needs the file compared against the LAYERS.
+ *
+ * No value here is a secret — {@link FIELDS} excludes them by construction — but
+ * `sensitive` rides along so a caller can decide what to put on a terminal that
+ * ends up pasted into an issue.
+ */
+export function resolveConfigReport(cfg) {
+    const configPath = instanceConfigPath(cfg);
+    const file = readConfigFileSnapshot(configPath);
+    const p = postureFor(cfg.profile);
+    const fields = FIELDS.map((f) => {
+        const shadow = envOverride(f.envVars, f.envShadowWhenDefined);
+        const raw = readPath(cfg, f.key);
+        const fallback = defaultFor(f, p) ?? null;
+        const value = raw === undefined || raw === null ? fallback : raw;
+        const fileRaw = file.data ? readPath(file.data, f.key) : undefined;
+        const fileSets = fileRaw !== undefined && fileRaw !== null;
+        // The layer a field falls back to when nothing names it: the profile for a
+        // posture key, the built-in default for everything else.
+        const bare = f.key.startsWith("claude.") ? f.key.slice("claude.".length) : f.key;
+        const isPosture = POSTURE_KEYS.includes(bare);
+        const unset = isPosture
+            ? { source: "profile", origin: cfg.profile }
+            : { source: "default" };
+        let resolved;
+        if (shadow !== undefined) {
+            resolved = { source: "env", origin: shadow, ...(fileSets ? { shadowedFileValue: fileRaw } : {}) };
+        }
+        else if (fileSets) {
+            resolved =
+                NORMALISED_AT_BOOT.has(f.key) || fileValueTookEffect(coerceForDisplay(f, fileRaw), value)
+                    ? { source: "file", origin: configPath }
+                    : { ...unset, shadowedFileValue: fileRaw };
+        }
+        else {
+            resolved = unset;
+        }
+        return {
+            key: f.key,
+            group: f.group,
+            label: f.label,
+            help: f.help,
+            type: f.type,
+            value,
+            sensitive: f.sensitive ?? false,
+            ejectable: (f.editable || isPosture) && f.sensitive !== true,
+            ...resolved,
+        };
+    });
+    return {
+        dataDir: cfg.dataDir,
+        configPath,
+        configFileExists: file.version !== null,
+        ...(file.error ? { configFileError: file.error } : {}),
+        profile: resolveProfileProvenance(cfg.profile, file.data, configPath),
+        fields,
+    };
+}

package/packages/server/dist/last-activity.d.ts

@@ -12,6 +12,27 @@ export interface SessionWithActivity extends DiscoveredSession {
     /** ISO 8601 timestamp of the last real message; absent if none was datable. */
     lastMessageAt?: string;
 }
+/**
+ * Does this record represent a human or the agent actually saying something?
+ *
+ * The exclusions are the point of the whole issue, not defensive noise. A
+ * resume, a permission-mode change or a background agent finishing all append
+ * records to a transcript **without any turn having happened**, and counting
+ * those as activity reintroduces the same bug one layer up: a chat nobody has
+ * touched in a week, freshly stamped, back at the top of the list.
+ *
+ * Exported because the `own → host` migration preview (#882) counts the same
+ * records to show a diverged chat's two copies side by side. A second copy of
+ * this rule would drift, and the two numbers would then disagree on screen
+ * about what a message is.
+ */
+export declare function isConversationRecord(rec: {
+    type?: unknown;
+    isMeta?: unknown;
+    origin?: {
+        kind?: unknown;
+    };
+}): boolean;
 /**
  * Timestamp of the last real message in a project chat's transcript.
  *

package/packages/server/dist/last-activity.js

@@ -52,8 +52,13 @@ const cache = new Map();
  * records to a transcript **without any turn having happened**, and counting
  * those as activity reintroduces the same bug one layer up: a chat nobody has
  * touched in a week, freshly stamped, back at the top of the list.
+ *
+ * Exported because the `own → host` migration preview (#882) counts the same
+ * records to show a diverged chat's two copies side by side. A second copy of
+ * this rule would drift, and the two numbers would then disagree on screen
+ * about what a message is.
  */
-function isConversation(rec) {
+export function isConversationRecord(rec) {
     // Drops `summary` title entries and every `type: "system"` control line
     // (local-command records, permission-mode changes, hook output).
     if (rec.type !== "user" && rec.type !== "assistant")
@@ -103,7 +108,7 @@ function scanBackwards(text, whole) {
         catch {
             continue;
         }
-        if (!isConversation(rec))
+        if (!isConversationRecord(rec))
             continue;
         const ts = rec.timestamp;
         if (typeof ts === "string" && !Number.isNaN(Date.parse(ts)))

package/packages/server/dist/profiles.d.ts

@@ -0,0 +1,154 @@
+/**
+ * Named config profiles (#878) — `paranoid` / `balanced` / `yolo`.
+ *
+ * Paddock has a dozen independent security/capability levers, each with its own
+ * code default. A profile is the single place to express *posture* — "locked
+ * down" / "full capability" — instead of hand-setting twelve `PADDOCK_*` vars.
+ *
+ * ## Why this is a resolved key, not something an installer writes
+ *
+ * Config resolves as code default < YAML file < `PADDOCK_*` env. A profile
+ * implemented as "the installer materialises concrete values into
+ * `paddock.config.yaml`" only ever touches the FILE layer — so it only works on
+ * the one distribution that runs an installer. Docker and bare `node dist` would
+ * keep falling through to code defaults and the distributions would stay
+ * divergent, which is the actual complaint #878 opens with. Resolving `profile`
+ * at every layer — file, env, and a code default underneath both — is what makes
+ * every distribution converge on the same posture.
+ *
+ * ## Where a profile sits in the precedence chain
+ *
+ * A profile supplies the DEFAULT that each lever's loader falls back to. It does
+ * not become a config layer of its own. So the full chain is:
+ *
+ *     code-default profile  <  resolved profile  <  individual file key  <  individual env var
+ *
+ * The consequence worth stating out loud, because it inverts this codebase's
+ * otherwise universal env-beats-file rule: **an individual key in the YAML file
+ * beats `PADDOCK_PROFILE` in the env.** `PADDOCK_PROFILE=paranoid` with
+ * `claude: {hooks: host}` in a mounted file resolves hooks to `host`.
+ *
+ * That is deliberate — specific beats general. `PADDOCK_PROFILE` is a statement
+ * about the dozen levers you did NOT mention; a key you wrote by hand is a
+ * statement about the one you did. The alternative makes the env var a blunt
+ * instrument that silently discards deliberate per-key config, which is a worse
+ * failure than the surprise of a file winning. (Env still beats file for the same
+ * key, exactly as everywhere else: `PADDOCK_CLAUDE_HOOKS` beats
+ * `claude.hooks`.)
+ *
+ * ## Posture keys only
+ *
+ * Profiles govern the `claude:` inheritance modes, `maxSpawnDepth`, and the
+ * capability toggles — and define ALL of them (see `POSTURE_KEYS`, pinned by a
+ * test). They are silent on operational keys (port, data dir, bind host, auth,
+ * models, drive mode, curation/recovery/attachments, git author). Switching
+ * profile must never change your port or clobber your auth config.
+ *
+ * ## Two guardrails
+ *
+ * - Profiles stay orthogonal to bind address and auth. `yolo` must NOT open the
+ *   bind or relax auth — network exposure remains its own explicit decision,
+ *   already gated by the dangerous-allow-open opt-in. Otherwise "yolo" quietly
+ *   becomes "yolo, reachable from the whole network".
+ * - `host` resolves against whatever `~/.claude` actually exists: rich on a
+ *   workstation, typically empty in a container. **The profile sets the levers,
+ *   the environment sets the blast radius** — which is why the permissive
+ *   profiles are far more reasonable in a disposable container than on a primary
+ *   machine.
+ */
+import type { CredentialsMode } from "./claude-credentials.js";
+import type { HooksMode } from "./claude-settings.js";
+import type { InstructionsMode } from "./claude-instructions.js";
+import type { McpServersMode } from "./claude-mcp.js";
+import type { TranscriptsMode } from "./transcripts.js";
+/** The three built-in profiles, in ascending order of capability. */
+export declare const PROFILE_NAMES: readonly ["paranoid", "balanced", "yolo"];
+export type ProfileName = (typeof PROFILE_NAMES)[number];
+/**
+ * The code-default profile (#878).
+ *
+ * `balanced` rather than `paranoid` because of the **superset principle**:
+ * paddock is a presentation layer over the Claude Code CLI, so its capability
+ * surface should be a superset of what the plain CLI already gives you. A user
+ * whose CLI has MCP servers configured (and plugin-provided MCP servers, which
+ * additionally need `instructions: host`) reasonably expects those to work here;
+ * defaulting them off is experienced as a capability regression versus the tool
+ * paddock wraps.
+ */
+export declare const DEFAULT_PROFILE: ProfileName;
+/**
+ * The posture surface: every lever a profile governs, and the only ones it may.
+ *
+ * Adding a capability lever means adding it here AND giving all three profiles a
+ * value for it — `profiles.test.ts` fails until you do. That is the point of the
+ * invariant: today a new toggle just gets a code default and the postures are
+ * never revisited, so they silently drift out of date.
+ */
+export interface Posture {
+    /** `claude.transcripts` — share the host's transcript store. */
+    transcripts: TranscriptsMode;
+    /** `claude.credentials` — read the host's Claude login. */
+    credentials: CredentialsMode;
+    /** `claude.instructions` — inherit the host's CLAUDE.md hierarchy. */
+    instructions: InstructionsMode;
+    /** `claude.hooks` — inherit the host's hook definitions. */
+    hooks: HooksMode;
+    /** `claude.mcpServers` — inherit the host's configured MCP servers. */
+    mcpServers: McpServersMode;
+    /** How deep an agent may spawn sub-agents. */
+    maxSpawnDepth: number;
+    /** The read-only self-management MCP. */
+    selfMcpEnabled: boolean;
+    /** The self-management MCP WRITE tools. */
+    selfMcpWriteEnabled: boolean;
+    /** The self-management MCP PROJECT tools (`create_project`). */
+    selfMcpProjectsEnabled: boolean;
+    /** Programmatic schedule mutation. */
+    scheduleMutationEnabled: boolean;
+    /** The hook-management MCP tools. */
+    hooksMcpEnabled: boolean;
+    /** The Playwright browser MCP. */
+    browserMcp: boolean;
+}
+/**
+ * Every posture key, as data — so a test can assert that all three profiles
+ * cover exactly this set. Kept in sync with `Posture` by that same test: a key
+ * added to the interface but not here fails to typecheck against
+ * `Record<keyof Posture, …>` at the `PROFILES` declaration below.
+ */
+export declare const POSTURE_KEYS: readonly ["transcripts", "credentials", "instructions", "hooks", "mcpServers", "maxSpawnDepth", "selfMcpEnabled", "selfMcpWriteEnabled", "selfMcpProjectsEnabled", "scheduleMutationEnabled", "hooksMcpEnabled", "browserMcp"];
+/**
+ * The three postures. All three define the same key set, differing only in
+ * values — so a diff between two columns is a diff in posture, never in
+ * coverage.
+ *
+ * Two choices here are argued rather than assumed:
+ *
+ * - **`hooks: own` in `balanced`.** Host hooks are shell commands that fire
+ *   AUTOMATICALLY on every matching tool call — inherited arbitrary code
+ *   execution. That is a different risk class from MCP servers, which are tools
+ *   an agent deliberately chooses to call. So `hooks` does not ride along with
+ *   the other `host` modes; it is `host` only under `yolo`.
+ * - **`browserMcp: false` in `balanced`.** It needs a browser installed on the
+ *   box. Enabling it by default on a host without one leads agents to fall back
+ *   to scripting a system browser instead, which is worse than not having it.
+ */
+export declare const PROFILES: Record<ProfileName, Posture>;
+/** Whether `v` names a built-in profile. */
+export declare function isKnownProfile(v: string): v is ProfileName;
+/**
+ * Resolve the profile NAME from env > file > {@link DEFAULT_PROFILE}.
+ *
+ * An unrecognised name falls back to the default rather than failing the boot —
+ * the rule every other enum in `config.ts` follows (`driveMode`, the `claude:`
+ * modes, whisper `mode`). The direction is defensible here in a way it is not
+ * for a single lever: the fallback is `balanced`, so a typo can only ever land
+ * you on the same posture a config-less instance already has, never on `yolo`.
+ *
+ * Deliberately NOT tsconfig-style `extends`: a closed set of names, one level,
+ * no chains, no path resolution. The inheritance is fine; arbitrary-file
+ * inheritance graphs are what make `extends` unpleasant.
+ */
+export declare function resolveProfileName(fileVal: unknown, env?: NodeJS.ProcessEnv): ProfileName;
+/** The posture a profile name expands to. */
+export declare function posture(name: ProfileName): Posture;