@adhdev/daemon-core 0.9.82-rc.49 → 0.9.82-rc.490

package/src/config/mesh-json-config.ts

@@ -0,0 +1,376 @@
+/**
+ * Repo-shared declarative mesh config — `.adhdev/mesh.json`
+ *
+ * A repo-committed, machine-independent file carrying ONLY the repo-shared
+ * coordinator-prompt config and operating notes:
+ *
+ *   - coordinator       — systemPromptOverride (local wins, else repo) and
+ *                         systemPromptAppend (repo append + local append BOTH
+ *                         stack, repo first).
+ *   - operatingNotes    — repo-declared baseline notes merged with the runtime
+ *                         ledger notes; on duplicate text the ledger note wins.
+ *   - limits            — advisory-only (`maxNoteChars`, `maxNotes`,
+ *                         `coordinator.maxPromptChars`); recorded, never enforced in v1.
+ *
+ * POLICY IS NOT HERE. RepoMeshPolicy (the 15 scheduling/approval fields) is
+ * MACHINE-LOCAL only — it lives in meshes.json and is never sourced from, merged
+ * with, or overlaid by a repo file. There is no `policy` zone and no
+ * `policy.scheduling` overlay in mesh.json; the scheduler reads the stored
+ * machine-local policy directly. The repo file shapes the coordinator prompt and
+ * operating notes, nothing else.
+ *
+ * The coordinator/operatingNotes merge is **in-memory only**: the on-disk
+ * machine-local `meshes.json` is never mutated by this module.
+ *
+ * FILE SEPARATION: refine / worktree-bootstrap / change-impact configs live in
+ * their OWN `.adhdev/*` files with their own loaders — they are NOT inlined into
+ * mesh.json. `loadRepoSettings` (config/repo-settings.ts) assembles all of them
+ * into one object for consumers.
+ *
+ * SECURITY: declarative only. JSON/YAML is parsed; arbitrary JS (.js) is NOT
+ * supported, so loading a config can never execute code.
+ */
+
+import { existsSync, readFileSync } from 'fs';
+import { join } from 'path';
+import * as yaml from 'js-yaml';
+import type {
+    RepoMeshCoordinatorConfig,
+    LocalMeshEntry,
+} from '../repo-mesh-types.js';
+import type { CoordinatorOperatingNote } from '../mesh/coordinator-prompt.js';
+
+// ─── Types (declarative config zones) ───────────
+
+export interface RepoMeshDeclarativeCoordinatorConfig {
+    /** Full mesh-level system prompt override. Same semantics as
+     *  RepoMeshCoordinatorConfig.systemPromptOverride; LOCAL-WINS. */
+    systemPromptOverride?: string;
+    /** Mesh-level append stacked after the base prompt. Both the repo append
+     *  and the machine-local append apply; the repo append comes first. */
+    systemPromptAppend?: string;
+    /** Advisory only in v1 — recorded but never enforced. */
+    maxPromptChars?: number;
+}
+
+export interface RepoMeshDeclarativeLimits {
+    /** Advisory only in v1 — recorded but never enforced. */
+    maxNoteChars?: number;
+    /** Advisory only in v1 — recorded but never enforced. */
+    maxNotes?: number;
+}
+
+/**
+ * Parsed + normalized `.adhdev/mesh.json` shape. Every field is optional except
+ * version so a repo can declare only the zone(s) it cares about. Policy is NOT a
+ * zone here — it is machine-local (meshes.json) only.
+ */
+export interface RepoMeshDeclarativeConfig {
+    version: 1;
+    coordinator?: RepoMeshDeclarativeCoordinatorConfig;
+    operatingNotes?: CoordinatorOperatingNote[];
+    limits?: RepoMeshDeclarativeLimits;
+}
+
+export interface RepoMeshJsonConfigLoadResult {
+    config?: RepoMeshDeclarativeConfig;
+    /** Relative location matched, or 'unavailable'/'invalid' marker. */
+    source: string;
+    sourceType: 'repo_file' | 'unavailable' | 'invalid';
+    /** Absolute path of the matched file, when one was read. */
+    path?: string;
+    error?: string;
+}
+
+// MESH_JSON_CONFIG_LOCATIONS is retained for backward compatibility: it is the
+// shared list of `.adhdev/mesh.*` filenames the loader probes (and other modules
+// reference for diagnostics). The file now carries only coordinator + operating
+// notes; there is no scheduling overlay.
+export const MESH_JSON_CONFIG_LOCATIONS = [
+    '.adhdev/mesh.json',
+    '.adhdev/mesh.yaml',
+    '.adhdev/mesh.yml',
+];
+
+export const MESH_JSON_CONFIG_SCHEMA = {
+    $schema: 'https://json-schema.org/draft/2020-12/schema',
+    title: 'ADHDev Repo Mesh Declarative Config',
+    type: 'object',
+    additionalProperties: false,
+    required: ['version'],
+    properties: {
+        version: { const: 1 },
+        coordinator: {
+            type: 'object',
+            additionalProperties: false,
+            properties: {
+                systemPromptOverride: { type: 'string' },
+                systemPromptAppend: { type: 'string' },
+                maxPromptChars: { type: 'number', minimum: 1 },
+            },
+        },
+        operatingNotes: {
+            type: 'array',
+            maxItems: 200,
+            items: {
+                type: 'object',
+                additionalProperties: false,
+                required: ['text'],
+                properties: {
+                    text: { type: 'string', minLength: 1 },
+                    category: { enum: ['provider_quirk', 'pattern_to_avoid', 'recovery_lesson'] },
+                    createdAt: { type: 'string' },
+                    sourceCoordinator: { type: 'string' },
+                },
+            },
+        },
+        limits: {
+            type: 'object',
+            additionalProperties: false,
+            properties: {
+                maxNoteChars: { type: 'number', minimum: 1 },
+                maxNotes: { type: 'number', minimum: 1 },
+            },
+        },
+    },
+} as const;
+
+// ─── Shared helpers ─────────────────────────────
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+    return !!value && typeof value === 'object' && !Array.isArray(value);
+}
+
+function parseConfigText(path: string, text: string): unknown {
+    if (/\.json$/i.test(path)) return JSON.parse(text);
+    return yaml.load(text);
+}
+
+// ─── Declarative config: Parse / Normalize ──────
+
+function normalizeOperatingNote(value: unknown): CoordinatorOperatingNote | null {
+    if (!isRecord(value)) return null;
+    const text = typeof value.text === 'string' ? value.text.trim() : '';
+    if (!text) return null;
+    const category = value.category === 'provider_quirk' || value.category === 'pattern_to_avoid' || value.category === 'recovery_lesson'
+        ? value.category
+        : undefined;
+    return {
+        text,
+        ...(category ? { category } : {}),
+        ...(typeof value.createdAt === 'string' ? { createdAt: value.createdAt } : {}),
+        ...(typeof value.sourceCoordinator === 'string' ? { sourceCoordinator: value.sourceCoordinator } : {}),
+    };
+}
+
+/**
+ * Validate + normalize a parsed `.adhdev/mesh.json` object into a typed
+ * RepoMeshDeclarativeConfig. Returns the config plus any non-fatal warnings;
+ * `valid` is false only when the document is structurally unusable (not an
+ * object / wrong version). Unknown top-level keys are tolerated (dropped) so a
+ * newer repo file authored against a future schema still loads its known zones.
+ */
+export function normalizeRepoMeshDeclarativeConfig(parsed: unknown): {
+    valid: boolean;
+    config?: RepoMeshDeclarativeConfig;
+    errors: string[];
+} {
+    const errors: string[] = [];
+    if (!isRecord(parsed)) return { valid: false, errors: ['config must be an object'] };
+    if (parsed.version !== 1) {
+        return { valid: false, errors: [`version must be 1 (got ${JSON.stringify(parsed.version)})`] };
+    }
+
+    const config: RepoMeshDeclarativeConfig = { version: 1 };
+
+    if (parsed.coordinator !== undefined) {
+        if (isRecord(parsed.coordinator)) {
+            const coord: RepoMeshDeclarativeCoordinatorConfig = {};
+            const c = parsed.coordinator;
+            if (typeof c.systemPromptOverride === 'string') coord.systemPromptOverride = c.systemPromptOverride;
+            if (typeof c.systemPromptAppend === 'string') coord.systemPromptAppend = c.systemPromptAppend;
+            if (Number.isFinite(Number(c.maxPromptChars))) coord.maxPromptChars = Number(c.maxPromptChars);
+            config.coordinator = coord;
+        } else {
+            errors.push('coordinator must be an object when provided');
+        }
+    }
+
+    if (parsed.operatingNotes !== undefined) {
+        if (Array.isArray(parsed.operatingNotes)) {
+            const notes = parsed.operatingNotes
+                .map(normalizeOperatingNote)
+                .filter((n): n is CoordinatorOperatingNote => n !== null);
+            if (notes.length) config.operatingNotes = notes;
+        } else {
+            errors.push('operatingNotes must be an array when provided');
+        }
+    }
+
+    if (parsed.limits !== undefined) {
+        if (isRecord(parsed.limits)) {
+            const limits: RepoMeshDeclarativeLimits = {};
+            if (Number.isFinite(Number(parsed.limits.maxNoteChars))) limits.maxNoteChars = Number(parsed.limits.maxNoteChars);
+            if (Number.isFinite(Number(parsed.limits.maxNotes))) limits.maxNotes = Number(parsed.limits.maxNotes);
+            if (Object.keys(limits).length) config.limits = limits;
+        } else {
+            errors.push('limits must be an object when provided');
+        }
+    }
+
+    return { valid: true, config, errors };
+}
+
+// ─── Declarative config: Loader ─────────────────
+
+/**
+ * Load the repo-shared declarative mesh config for a coordinator workspace.
+ *
+ * Resolution: the coordinator node workspace is checked first; if it carries no
+ * `.adhdev/mesh.json`, the calling process cwd is tried as a fallback (per the
+ * design: "workspace path = coordinator node workspace's .adhdev/mesh.json,
+ * else calling cwd"). The first existing file across both bases (and the
+ * json/yaml/yml variants) wins.
+ *
+ * Read/parse errors never throw — they resolve to a sourceType:'invalid'
+ * result so a broken repo file degrades to "no repo base" instead of blocking
+ * coordinator launch.
+ */
+export function loadRepoMeshJsonConfig(workspace?: string): RepoMeshJsonConfigLoadResult {
+    const bases: string[] = [];
+    const ws = typeof workspace === 'string' ? workspace.trim() : '';
+    if (ws) bases.push(ws);
+    let cwd = '';
+    try { cwd = process.cwd(); } catch { /* cwd unavailable in some sandboxes */ }
+    if (cwd && cwd !== ws) bases.push(cwd);
+
+    for (const base of bases) {
+        for (const relative of MESH_JSON_CONFIG_LOCATIONS) {
+            const configPath = join(base, relative);
+            if (!existsSync(configPath)) continue;
+            try {
+                const parsed = parseConfigText(configPath, readFileSync(configPath, 'utf-8'));
+                const result = normalizeRepoMeshDeclarativeConfig(parsed);
+                if (!result.valid || !result.config) {
+                    return { source: relative, sourceType: 'invalid', path: configPath, error: result.errors.join('; ') };
+                }
+                return { config: result.config, source: relative, sourceType: 'repo_file', path: configPath };
+            } catch (error: any) {
+                return { source: relative, sourceType: 'invalid', path: configPath, error: error?.message || String(error) };
+            }
+        }
+    }
+    return {
+        source: 'unavailable',
+        sourceType: 'unavailable',
+        error: `No repo mesh config found. Checked: ${MESH_JSON_CONFIG_LOCATIONS.join(', ')}`,
+    };
+}
+
+// ─── Declarative config: Merge (coordinator + operating notes) ─────
+
+/**
+ * Effective coordinator config. systemPromptOverride: local wins, else repo.
+ * systemPromptAppend: repo append + local append BOTH stack (repo first). Other
+ * coordinator fields (providerType, preferredNodeId, …) are carried from the
+ * machine-local config unchanged.
+ */
+export function mergeEffectiveCoordinatorConfig(
+    repoCoord: RepoMeshDeclarativeCoordinatorConfig | undefined,
+    localCoord: RepoMeshCoordinatorConfig | undefined,
+): RepoMeshCoordinatorConfig {
+    const out: RepoMeshCoordinatorConfig = { ...(localCoord || {}) };
+
+    const localOverride = localCoord?.systemPromptOverride?.trim();
+    const repoOverride = repoCoord?.systemPromptOverride?.trim();
+    if (localOverride) {
+        out.systemPromptOverride = localCoord!.systemPromptOverride;
+    } else if (repoOverride) {
+        out.systemPromptOverride = repoCoord!.systemPromptOverride;
+    } else {
+        delete out.systemPromptOverride;
+    }
+
+    const repoAppend = repoCoord?.systemPromptAppend?.trim() ? repoCoord!.systemPromptAppend!.trim() : '';
+    // The machine-local append may live on the new field or the legacy alias.
+    const localAppendRaw = (localCoord?.systemPromptAppend ?? localCoord?.systemPromptSuffix);
+    const localAppend = localAppendRaw?.trim() ? localAppendRaw.trim() : '';
+    const stacked = [repoAppend, localAppend].filter(Boolean).join('\n\n');
+    if (stacked) {
+        out.systemPromptAppend = stacked;
+        // The stacked value already folds in any legacy suffix; drop the alias so
+        // buildCoordinatorSystemPrompt doesn't risk double-applying it.
+        delete out.systemPromptSuffix;
+    }
+
+    return out;
+}
+
+/**
+ * Effective operating notes = repo-declared baseline ⊕ runtime ledger notes.
+ * Dedup by trimmed text with the LEDGER note winning (repo duplicates dropped),
+ * so a runtime note's freshest wording/category survives. Order: repo baseline
+ * first, then ledger notes. Returns undefined when nothing usable remains so the
+ * prompt's "## Operating Notes" section is omitted exactly as before.
+ */
+export function mergeEffectiveOperatingNotes(
+    repoNotes: CoordinatorOperatingNote[] | undefined,
+    ledgerNotes: CoordinatorOperatingNote[] | undefined,
+): CoordinatorOperatingNote[] | undefined {
+    const usable = (notes: CoordinatorOperatingNote[] | undefined): CoordinatorOperatingNote[] =>
+        Array.isArray(notes) ? notes.filter(n => n && typeof n.text === 'string' && n.text.trim()) : [];
+    const repo = usable(repoNotes);
+    const ledger = usable(ledgerNotes);
+    const ledgerTexts = new Set(ledger.map(n => n.text.trim()));
+    const repoKept = repo.filter(n => !ledgerTexts.has(n.text.trim()));
+    const merged = [...repoKept, ...ledger];
+    return merged.length ? merged : undefined;
+}
+
+/**
+ * Produce an in-memory effective mesh by layering the repo declarative config
+ * UNDER the machine-local mesh entry — coordinator zone ONLY. Policy is
+ * machine-local and is left exactly as the stored mesh carries it (never sourced
+ * from the repo file). Returns a new object; the input mesh and on-disk
+ * meshes.json are never mutated. operatingNotes are merged separately at launch
+ * (they ride the prompt context, not the mesh).
+ */
+export function applyRepoMeshConfig<T extends Pick<LocalMeshEntry, 'coordinator'>>(
+    mesh: T,
+    repoConfig: RepoMeshDeclarativeConfig | null | undefined,
+): T {
+    if (!repoConfig) return mesh;
+    return {
+        ...mesh,
+        coordinator: mergeEffectiveCoordinatorConfig(repoConfig.coordinator, mesh.coordinator),
+    };
+}
+
+// ─── Declarative config: Export scaffold ────────
+
+/**
+ * Build a `.adhdev/mesh.json` DRAFT from a machine-local mesh entry. This is a
+ * scaffold for the operator to review and commit — NOT an automatic migration.
+ * It captures the coordinator prompt override/append so a repo can adopt the
+ * current machine's prompt customization as the shared base. Policy is NOT
+ * exported — it is machine-local only and has no place in mesh.json. Operating
+ * notes are intentionally NOT exported either: those are runtime ledger lessons,
+ * and a repo should declare baseline notes deliberately.
+ */
+export function buildMeshJsonConfigScaffold(
+    mesh: Pick<LocalMeshEntry, 'coordinator'>,
+): RepoMeshDeclarativeConfig {
+    const scaffold: RepoMeshDeclarativeConfig = { version: 1 };
+    const coord: RepoMeshDeclarativeCoordinatorConfig = {};
+    const override = mesh.coordinator?.systemPromptOverride;
+    if (typeof override === 'string' && override.trim()) coord.systemPromptOverride = override;
+    const append = mesh.coordinator?.systemPromptAppend ?? mesh.coordinator?.systemPromptSuffix;
+    if (typeof append === 'string' && append.trim()) coord.systemPromptAppend = append;
+    if (Object.keys(coord).length) scaffold.coordinator = coord;
+    return scaffold;
+}
+
+/** Serialize a scaffold to the canonical 2-space JSON draft text. */
+export function serializeMeshJsonConfigScaffold(config: RepoMeshDeclarativeConfig): string {
+    return JSON.stringify(config, null, 2);
+}

package/src/config/recent-activity.ts

@@ -92,12 +92,18 @@ export function buildSessionReadStateKey(sessionId: string, providerSessionId?:
 
 export function getSessionSeenAt(state: DaemonState, sessionId: string, providerSessionId?: string | null): number {
     const providerKey = buildSessionReadStateKey(sessionId, providerSessionId);
-    return state.sessionReads?.[providerKey] || state.sessionReads?.[sessionId] || 0;
+    return Math.max(state.sessionReads?.[providerKey] || 0, state.sessionReads?.[sessionId] || 0);
 }
 
 export function getSessionSeenMarker(state: DaemonState, sessionId: string, providerSessionId?: string | null): string {
     const providerKey = buildSessionReadStateKey(sessionId, providerSessionId);
-    return state.sessionReadMarkers?.[providerKey] || state.sessionReadMarkers?.[sessionId] || '';
+    const providerSeenAt = state.sessionReads?.[providerKey] || 0;
+    const sessionSeenAt = state.sessionReads?.[sessionId] || 0;
+    const providerMarker = state.sessionReadMarkers?.[providerKey] || '';
+    const sessionMarker = state.sessionReadMarkers?.[sessionId] || '';
+    if (sessionSeenAt > providerSeenAt && sessionMarker) return sessionMarker;
+    if (providerSeenAt > sessionSeenAt && providerMarker) return providerMarker;
+    return providerMarker || sessionMarker;
 }
 
 export function getSessionNotificationDismissal(state: DaemonState, sessionId: string, providerSessionId?: string | null): string {

package/src/config/registry-resolver.ts

@@ -0,0 +1,100 @@
+/**
+ * Registry / provider-distribution URL resolver.
+ *
+ * Single source of truth for the ADHDev provider *registry* base URL and the
+ * provider *tarball* (GitHub) URL. Self-hosters can repoint both away from the
+ * vendor defaults so the daemon never phones home to `api.adhf.dev` /
+ * `github.com/vilmire/adhdev-providers`.
+ *
+ * Resolution priority (highest first):
+ *   1. Explicit config field    — `config.registryUrl` / `config.providerTarballUrl`
+ *   2. Environment variable      — `ADHDEV_REGISTRY_URL` / `ADHDEV_PROVIDER_TARBALL_URL`
+ *   3. Vendor default            — existing URLs (unchanged for default users)
+ *
+ * Default users get byte-identical behavior: the vendor defaults equal the
+ * literals these functions replaced.
+ */
+
+/** Vendor default registry base URL (no trailing slash). */
+export const DEFAULT_REGISTRY_BASE_URL = 'https://api.adhf.dev/api/v1/registry';
+
+/** Vendor default provider tarball URL (GitHub main branch archive). */
+export const DEFAULT_PROVIDER_TARBALL_URL =
+    'https://github.com/vilmire/adhdev-providers/archive/refs/heads/main.tar.gz';
+
+/** Env var that overrides the registry base URL. */
+export const REGISTRY_URL_ENV_VAR = 'ADHDEV_REGISTRY_URL';
+
+/** Env var that overrides the provider tarball URL. */
+export const PROVIDER_TARBALL_URL_ENV_VAR = 'ADHDEV_PROVIDER_TARBALL_URL';
+
+function cleanString(value: unknown): string | undefined {
+    return typeof value === 'string' && value.trim() ? value.trim() : undefined;
+}
+
+function stripTrailingSlashes(url: string): string {
+    return url.replace(/\/+$/, '');
+}
+
+/**
+ * Resolve the provider registry base URL.
+ *
+ * @param configuredUrl explicit config value (config.registryUrl); highest priority.
+ * @param env process env source (defaults to process.env; injectable for tests).
+ * @returns the resolved base URL with any trailing slash stripped, so callers
+ *   can safely append `/providers`, `/providers/<type>`, etc.
+ */
+export function resolveRegistryBaseUrl(
+    configuredUrl?: string | null,
+    env: NodeJS.ProcessEnv = process.env,
+): string {
+    const resolved =
+        cleanString(configuredUrl) ??
+        cleanString(env[REGISTRY_URL_ENV_VAR]) ??
+        DEFAULT_REGISTRY_BASE_URL;
+    return stripTrailingSlashes(resolved);
+}
+
+/**
+ * Resolve the provider tarball (archive) URL.
+ *
+ * @param configuredUrl explicit config value (config.providerTarballUrl); highest priority.
+ * @param env process env source (defaults to process.env; injectable for tests).
+ */
+export function resolveProviderTarballUrl(
+    configuredUrl?: string | null,
+    env: NodeJS.ProcessEnv = process.env,
+): string {
+    return (
+        cleanString(configuredUrl) ??
+        cleanString(env[PROVIDER_TARBALL_URL_ENV_VAR]) ??
+        DEFAULT_PROVIDER_TARBALL_URL
+    );
+}
+
+/** Parsed tarball request target for callers that issue raw hostname/path requests. */
+export interface TarballRequestTarget {
+    /** Full resolved tarball URL. */
+    url: string;
+    /** Hostname component (e.g. `github.com`). */
+    hostname: string;
+    /** Path component including any query string (e.g. `/vilmire/...tar.gz`). */
+    path: string;
+}
+
+/**
+ * Resolve the provider tarball URL and split it into `{ url, hostname, path }`
+ * for callers that build raw `https.request` options (e.g. HEAD ETag probes).
+ */
+export function resolveProviderTarballTarget(
+    configuredUrl?: string | null,
+    env: NodeJS.ProcessEnv = process.env,
+): TarballRequestTarget {
+    const url = resolveProviderTarballUrl(configuredUrl, env);
+    const parsed = new URL(url);
+    return {
+        url,
+        hostname: parsed.hostname,
+        path: parsed.pathname + (parsed.search || ''),
+    };
+}

package/src/config/repo-settings.ts

@@ -0,0 +1,111 @@
+/**
+ * Repo Settings — one unified loader over the repo-committed `.adhdev/*` config
+ * files (the "single source" assembly point).
+ *
+ * DESIGN (option B — file separation preserved): the repo keeps its declarative
+ * config in SEPARATE files, each with its own dedicated loader:
+ *
+ *   .adhdev/mesh.json               → loadRepoMeshJsonConfig  (coordinator + operatingNotes)
+ *   .adhdev/refine.json             → loadMeshRefineConfig     (Refinery validation)
+ *   .adhdev/worktree_bootstrap.json → loadMeshWorktreeBootstrapConfig
+ *   .adhdev/change-impact.json      → loadChangeImpactConfig
+ *
+ * Nothing is inlined into mesh.json. `loadRepoSettings` simply CALLS each
+ * dedicated loader and assembles the results into one `RepoSettings` object so a
+ * consumer can read every repo-shared setting through a single call instead of
+ * threading four loaders. The per-file loaders remain the source of truth (and
+ * stay independently usable); this is a convenience aggregator, not a new schema.
+ *
+ * IMPORTANT — policy is NOT here. RepoMeshPolicy (the 15 scheduling/approval
+ * fields) is MACHINE-LOCAL only: it lives in meshes.json and is never sourced
+ * from or merged with a repo file. mesh.json carries only coordinator prompt
+ * config + operating notes (+ advisory limits).
+ *
+ * The refine/worktree-bootstrap loaders also honor a machine-local INLINE seam
+ * (mesh.refineConfig / mesh.policy.worktreeBootstrap, etc.) — that seam is for
+ * machine-local config and is unchanged here; mesh.json gains no such zone.
+ */
+
+import {
+    loadRepoMeshJsonConfig,
+    type RepoMeshDeclarativeCoordinatorConfig,
+    type RepoMeshDeclarativeLimits,
+    type RepoMeshJsonConfigLoadResult,
+} from './mesh-json-config.js';
+import {
+    loadMeshRefineConfig,
+    type MeshRefineConfigLoadResult,
+} from '../mesh/refine-config.js';
+import {
+    loadMeshWorktreeBootstrapConfig,
+    type WorktreeBootstrapConfigLoadResult,
+} from '../mesh/worktree-bootstrap-config.js';
+import {
+    loadChangeImpactConfig,
+    type ChangeImpactConfigLoadResult,
+} from '../git/change-impact-config.js';
+import type { CoordinatorOperatingNote } from '../mesh/coordinator-prompt.js';
+
+export interface LoadRepoSettingsOptions {
+    /** Workspace path whose `.adhdev/*` files are resolved (mesh.json / refine / bootstrap). */
+    workspace: string;
+    /**
+     * Machine-local mesh entry, consulted ONLY for the INLINE seam of the
+     * refine / worktree-bootstrap loaders (mesh.refineConfig etc.). Optional —
+     * omit it and only the repo files are considered. NEVER used to source policy.
+     */
+    mesh?: any;
+    /**
+     * Repo root for change-impact resolution. Defaults to `workspace` when omitted
+     * (change-impact compares the daemon build commit against the workspace HEAD).
+     */
+    repoRoot?: string;
+}
+
+/**
+ * The assembled repo-shared settings. Each sub-config carries its own load
+ * result (source / sourceType / error) so a consumer can tell "absent" from
+ * "invalid" per file. `coordinator` / `operatingNotes` / `limits` are lifted out
+ * of the mesh.json load result for convenience; `meshJson` keeps the full result
+ * (e.g. for the `sourceType === 'invalid'` warning on coordinator launch).
+ */
+export interface RepoSettings {
+    /** Repo-shared coordinator prompt config (override/append) from `.adhdev/mesh.json`. */
+    coordinator?: RepoMeshDeclarativeCoordinatorConfig;
+    /** Repo-declared baseline operating notes from `.adhdev/mesh.json`. */
+    operatingNotes?: CoordinatorOperatingNote[];
+    /** Advisory-only limits from `.adhdev/mesh.json` (recorded, not enforced in v1). */
+    limits?: RepoMeshDeclarativeLimits;
+    /** Full `.adhdev/mesh.json` declarative load result (coordinator/operatingNotes source). */
+    meshJson: RepoMeshJsonConfigLoadResult;
+    /** `.adhdev/refine.json` Refinery validation config load result. */
+    refine: MeshRefineConfigLoadResult;
+    /** `.adhdev/worktree_bootstrap.json` bootstrap config load result. */
+    worktreeBootstrap: WorktreeBootstrapConfigLoadResult;
+    /** `.adhdev/change-impact.json` change-impact config load result. */
+    changeImpact: ChangeImpactConfigLoadResult;
+}
+
+/**
+ * Load every repo-committed `.adhdev/*` setting for a workspace and assemble them
+ * into one object. Each dedicated loader degrades to an `unavailable`/`invalid`
+ * load result rather than throwing, so this never throws on a missing or broken
+ * file — a consumer inspects the per-sub-config `sourceType`.
+ */
+export function loadRepoSettings(opts: LoadRepoSettingsOptions): RepoSettings {
+    const workspace = typeof opts.workspace === 'string' ? opts.workspace : '';
+    const mesh = opts.mesh;
+    const repoRoot = typeof opts.repoRoot === 'string' && opts.repoRoot ? opts.repoRoot : workspace;
+
+    const meshJson = loadRepoMeshJsonConfig(workspace);
+
+    return {
+        coordinator: meshJson.config?.coordinator,
+        operatingNotes: meshJson.config?.operatingNotes,
+        limits: meshJson.config?.limits,
+        meshJson,
+        refine: loadMeshRefineConfig(mesh, workspace),
+        worktreeBootstrap: loadMeshWorktreeBootstrapConfig(mesh, workspace),
+        changeImpact: loadChangeImpactConfig(repoRoot),
+    };
+}