@amsterdamdatalabs/adl-agent-control-darwin-arm64 0.1.4

package/packages/agent-settings/src/deploy/legacy-lock.ts

@@ -0,0 +1,286 @@
+/**
+ * Takeover of what the pre-agent-settings engine (packages/agent-skills'
+ * repo-local installer, lockVersion 2) already wrote into a target repo.
+ *
+ * That engine recorded what it wrote only in its own
+ * `.agents/adl-repo.lock.json` (or whatever `deploy-profile.json`'s
+ * `legacyLock` names). This package's own `.agents/agent-settings.lock.json`
+ * (lock.ts) knows nothing about any of that, so left alone, deploy would see
+ * every one of those files/entries as foreign and refuse to touch them
+ * (reported as a conflict) instead of updating them to the current asset.
+ *
+ * Takeover rule (Tarun, 2026-09-28, chat approval "yes lets take over
+ * adl-azdo"): something the legacy lock recorded whose CURRENT content still
+ * hashes to what that lock recorded is adl-written -> deploy treats it
+ * exactly as if its own previous run had written it (folds it into the
+ * ownership set a surface's merge/overwrite logic already consults), so the
+ * normal deploy updates it to the current asset instead of refusing it as a
+ * conflict. A hash that does not match (hand-edited since, or never ours)
+ * stays foreign — reported, untouched, no different from something deploy
+ * never wrote.
+ *
+ * Four record shapes, one per artifact kind this package owns:
+ *  - whole-file (agent files under `assets/agents`, and the lean-ctx
+ *    `config.toml`/`layout.toml`): legacy `files[<path>].sha256` against the
+ *    current file's raw-byte sha256.
+ *  - MCP JSON-surface server entries (`.mcp.json`, `.cursor/mcp.json`,
+ *    `.kimi-code/mcp.json`, `opencode.json`): legacy
+ *    `merged[<file>].entries[]` holds one `{type:"key", path:[<containerKey>,
+ *    <name>], sha256}` per server; hashed with `legacyValueHash`, a
+ *    key-order-independent JSON hash ported verbatim from the deleted
+ *    engine's `packages/agent-skills/src/internal/json-merge.ts`
+ *    (`stableStringify`) — proved against this repo's own committed
+ *    `.mcp.json` in legacy-lock.test.ts.
+ *  - the codex managed TOML block (`.codex/config.toml`): legacy
+ *    `toml[<file>].sha256` against the sha256 of the current file's managed
+ *    block (markers included, whichever marker id it currently carries),
+ *    also proved in legacy-lock.test.ts against this repo's own committed
+ *    `.codex/config.toml`.
+ *  - `.agents/.gitignore`: legacy `gitignore[<file>]` has no sha256 field at
+ *    all — it records `{created, lines, appended}`. Taken over when
+ *    `created === true` and the current file's content equals `appended`
+ *    verbatim, or (fallback) `lines.join("\n") + "\n"`.
+ *
+ * Once at least one entry has actually been taken over in a given deploy
+ * call, that call's own footprint in the legacy lock is stale — ownership
+ * has now fully moved to `.agents/agent-settings.lock.json` — so
+ * `stripLegacyOwnership` removes exactly the entries that were taken over
+ * (never a blanket wipe: an entry that stayed foreign because its hash
+ * mismatched is left exactly as the legacy lock recorded it) and rewrites
+ * the legacy lock, deleting it entirely once `files`, `merged`, `toml` and
+ * `gitignore` are all empty. agent-skills and agent-hooks own every other
+ * entry in the same lock (skills files; hook entries in
+ * `.claude/settings.json`, `.codex/hooks.json`, `.cursor/hooks.json`) and are
+ * never touched here.
+ */
+import { createHash } from "node:crypto";
+import { existsSync, readFileSync, unlinkSync, writeFileSync } from "node:fs";
+
+export const sha256Hex = (input: string | Buffer): string => createHash("sha256").update(input).digest("hex");
+
+/**
+ * Key-order-independent serialisation, ported verbatim from the deleted
+ * engine's `packages/agent-skills/src/internal/json-merge.ts` —
+ * `stableStringify`, the exact function that computed every sha256 in a
+ * legacy lock's `merged` section. An entry's identity must not change just
+ * because a host or a user rewrote the file and reordered its keys.
+ */
+export function stableStringify(value: unknown): string {
+  if (Array.isArray(value)) return `[${value.map(stableStringify).join(",")}]`;
+  if (value && typeof value === "object") {
+    return `{${Object.keys(value as Record<string, unknown>)
+      .sort()
+      .map((k) => `${JSON.stringify(k)}:${stableStringify((value as Record<string, unknown>)[k])}`)
+      .join(",")}}`;
+  }
+  return JSON.stringify(value);
+}
+
+/** Content hash of a JSON value, exactly as the legacy engine recorded it. */
+export const legacyValueHash = (value: unknown): string => sha256Hex(stableStringify(value));
+
+export type LegacyJsonPath = readonly (string | number)[];
+
+export interface LegacyJsonMergeEntry {
+  readonly type: string;
+  readonly path: LegacyJsonPath;
+  readonly sha256: string;
+}
+
+export interface LegacyMergedRecord {
+  readonly entries?: readonly LegacyJsonMergeEntry[];
+  readonly [key: string]: unknown;
+}
+
+export interface LegacyGitignoreRecord {
+  readonly created?: boolean;
+  readonly lines?: readonly string[];
+  readonly appended?: string;
+}
+
+export interface LegacyLockDoc {
+  readonly files?: Readonly<Record<string, { readonly sha256: string }>>;
+  readonly merged?: Readonly<Record<string, LegacyMergedRecord>>;
+  readonly toml?: Readonly<Record<string, { readonly sha256: string } | undefined>>;
+  readonly gitignore?: Readonly<Record<string, LegacyGitignoreRecord>>;
+  readonly [key: string]: unknown;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/** Reads and parses a legacy lock at `path`, or `undefined` when it does not exist. Fails loud on unparsable or non-object content. */
+export function readLegacyLock(path: string): LegacyLockDoc | undefined {
+  if (!existsSync(path)) return undefined;
+  let doc: unknown;
+  try {
+    doc = JSON.parse(readFileSync(path, "utf8"));
+  } catch (cause) {
+    throw new Error(`legacy lock is not valid JSON: ${path} (${(cause as Error).message})`);
+  }
+  if (!isRecord(doc)) {
+    throw new Error(`legacy lock has an unrecognized shape: ${path}`);
+  }
+  return doc as LegacyLockDoc;
+}
+
+/** The legacy lock's recorded whole-file sha256 for `file` under `files`, or `undefined` when unrecorded. */
+export function legacyFileHash(doc: LegacyLockDoc | undefined, file: string): string | undefined {
+  return doc?.files?.[file]?.sha256;
+}
+
+/** True when `content`'s raw-byte sha256 matches the legacy lock's whole-file record for `file`. */
+export function legacyFileTakeover(content: Buffer | string, doc: LegacyLockDoc | undefined, file: string): boolean {
+  const recorded = legacyFileHash(doc, file);
+  return recorded !== undefined && sha256Hex(content) === recorded;
+}
+
+function pathKey(path: LegacyJsonPath): string {
+  return JSON.stringify(path);
+}
+
+/** The legacy lock's recorded sha256 for a merged-JSON entry at exactly `path` within `merged[file].entries`, or `undefined` when unrecorded. */
+export function legacyMergedEntryHash(doc: LegacyLockDoc | undefined, file: string, path: LegacyJsonPath): string | undefined {
+  const entries = doc?.merged?.[file]?.entries ?? [];
+  const want = pathKey(path);
+  return entries.find((e) => pathKey(e.path) === want)?.sha256;
+}
+
+export interface McpJsonTakeover {
+  /** Server names in `existing[containerKey]` whose current value hashes to what the legacy lock recorded for `[containerKey, name]`. */
+  readonly ownedServers: readonly string[];
+  readonly matched: boolean;
+}
+
+const EMPTY_MCP_TAKEOVER: McpJsonTakeover = { ownedServers: [], matched: false };
+
+/**
+ * Existing servers in a JSON MCP surface's current on-disk server map whose
+ * content hash matches the legacy lock's record for that exact server. Used
+ * to fold recovered ownership into `previousOwned` before calling
+ * mcp-merge.ts's `mergeServerMap`, so a legacy-written server updates to the
+ * current asset instead of being reported as a same-name conflict.
+ */
+export function legacyTakeoverForMcpJsonSurface(existing: Record<string, unknown> | undefined, doc: LegacyLockDoc | undefined, file: string, containerKey: string): McpJsonTakeover {
+  if (!doc || !existing) return EMPTY_MCP_TAKEOVER;
+  const servers = existing[containerKey];
+  if (!isRecord(servers)) return EMPTY_MCP_TAKEOVER;
+
+  const owned: string[] = [];
+  for (const [name, value] of Object.entries(servers)) {
+    const recorded = legacyMergedEntryHash(doc, file, [containerKey, name]);
+    if (recorded !== undefined && recorded === legacyValueHash(value)) owned.push(name);
+  }
+  return { ownedServers: owned, matched: owned.length > 0 };
+}
+
+const BLOCK_OPEN_RE = /^# >>> (\S+) \(managed by [^)]*\) >>>$/;
+
+/** The current managed block in a codex-toml-block file's text, markers included, whichever marker id it currently carries — or `undefined` when no managed block is present. Mirrors mcp-merge.ts's own block-finding, kept independent so this module has no dependency on it. */
+export function findManagedTomlBlock(text: string): string | undefined {
+  const lines = text.length > 0 ? text.split("\n") : [];
+  if (lines.length > 0 && lines[lines.length - 1] === "") lines.pop();
+  const startIdx = lines.findIndex((line) => BLOCK_OPEN_RE.test(line));
+  if (startIdx === -1) return undefined;
+  const markerId = BLOCK_OPEN_RE.exec(lines[startIdx] ?? "")?.[1] ?? "";
+  const closeRe = new RegExp(`^# <<< ${markerId} <<<$`);
+  const endIdx = lines.findIndex((line, i) => i > startIdx && closeRe.test(line));
+  if (endIdx === -1) return undefined;
+  return `${lines.slice(startIdx, endIdx + 1).join("\n")}\n`;
+}
+
+/** True when the current managed block in `existingText` hashes to what the legacy lock recorded under `toml[file].sha256`. */
+export function legacyTakeoverForCodexBlock(existingText: string | undefined, doc: LegacyLockDoc | undefined, file: string): boolean {
+  const recorded = doc?.toml?.[file]?.sha256;
+  if (recorded === undefined || existingText === undefined) return false;
+  const block = findManagedTomlBlock(existingText);
+  return block !== undefined && sha256Hex(block) === recorded;
+}
+
+/** True when `content` equals the legacy engine's recorded gitignore text (`appended`, or `lines` joined as a fallback) and it recorded `created: true`. */
+export function legacyTakeoverForGitignore(content: string, doc: LegacyLockDoc | undefined, file: string): boolean {
+  const record = doc?.gitignore?.[file];
+  if (record === undefined || record.created !== true) return false;
+  if (typeof record.appended === "string" && content === record.appended) return true;
+  if (Array.isArray(record.lines) && content === `${record.lines.join("\n")}\n`) return true;
+  return false;
+}
+
+export interface LegacyMergedRemoval {
+  readonly file: string;
+  readonly paths: readonly LegacyJsonPath[];
+}
+
+export interface LegacyRemoval {
+  readonly files?: readonly string[];
+  readonly mergedEntries?: readonly LegacyMergedRemoval[];
+  readonly toml?: readonly string[];
+  readonly gitignore?: readonly string[];
+}
+
+function isEmptyRecord(value: unknown): boolean {
+  return isRecord(value) && Object.keys(value).length === 0;
+}
+
+/**
+ * Removes exactly the entries named in `removal` from a legacy lock and
+ * rewrites it at `lockPath` — never a blanket wipe: an entry that stayed
+ * foreign (hash mismatch, never taken over) is not passed in `removal` and
+ * is left exactly as recorded. Deletes the file entirely when `files`,
+ * `merged`, `toml` and `gitignore` are then all empty — sibling packages
+ * (agent-skills, agent-hooks) own everything else in the same lock and are
+ * never touched here. Returns `false` (never writes) when `removal` names
+ * nothing actually present in `doc`.
+ */
+export function stripLegacyOwnership(doc: LegacyLockDoc, lockPath: string, removal: LegacyRemoval): boolean {
+  const files = { ...(doc.files ?? {}) };
+  const merged = { ...(doc.merged ?? {}) };
+  const toml = { ...(doc.toml ?? {}) };
+  const gitignore = { ...(doc.gitignore ?? {}) };
+  let touched = false;
+
+  for (const file of removal.files ?? []) {
+    if (file in files) {
+      delete files[file];
+      touched = true;
+    }
+  }
+
+  for (const { file, paths } of removal.mergedEntries ?? []) {
+    const record = merged[file];
+    if (record === undefined) continue;
+    const drop = new Set(paths.map(pathKey));
+    const remainingEntries = (record.entries ?? []).filter((e) => !drop.has(pathKey(e.path)));
+    if (remainingEntries.length === (record.entries ?? []).length) continue;
+    touched = true;
+    if (remainingEntries.length === 0) delete merged[file];
+    else merged[file] = { ...record, entries: remainingEntries };
+  }
+
+  for (const file of removal.toml ?? []) {
+    if (file in toml) {
+      delete toml[file];
+      touched = true;
+    }
+  }
+
+  for (const file of removal.gitignore ?? []) {
+    if (file in gitignore) {
+      delete gitignore[file];
+      touched = true;
+    }
+  }
+
+  if (!touched) return false;
+
+  const next: LegacyLockDoc = { ...doc, files, merged, toml, gitignore };
+  const nothingLeft = isEmptyRecord(next.files) && isEmptyRecord(next.merged) && isEmptyRecord(next.toml) && isEmptyRecord(next.gitignore);
+
+  if (nothingLeft) {
+    unlinkSync(lockPath);
+  } else {
+    writeFileSync(lockPath, `${JSON.stringify(next, null, 2)}\n`);
+  }
+  return true;
+}

package/packages/agent-settings/src/deploy/list.ts

@@ -0,0 +1,135 @@
+/**
+ * Lists every MCP server available under assets/mcp.json AND every agent
+ * available under assets/agents/, merged with what is currently deployed in
+ * a target repo's surfaces — one line per item, labelled `mcp:<server>` or
+ * `agent:<name>`, covering both "available" and "deployed" state at once
+ * (mirrors packages/agent-skills/src/list.ts's shape).
+ */
+import { existsSync, readdirSync } from "node:fs";
+import { basename, join } from "node:path";
+import { extensionFor } from "./agent-render.js";
+import { loadAgentSources, type AgentDef } from "./agent-toml.js";
+import { agentOwned, leanCtxOwned, mcpServerOwned, readLock } from "./lock.js";
+import { readDeployedMcpServerNames } from "./mcp-inspect.js";
+import { loadMcpSource, type McpServerSpec } from "./mcp-source.js";
+import { type DeployProfile, loadProfile } from "./profile.js";
+
+export type ItemOwner = "adl" | "user" | "conflict" | "-";
+
+export interface ListEntry {
+  readonly kind: "mcp" | "agent" | "lean-ctx";
+  readonly name: string;
+  readonly available: boolean;
+  readonly deployedIn: readonly string[];
+  readonly owner: ItemOwner;
+  readonly line: string;
+}
+
+export interface ListResult {
+  readonly entries: readonly ListEntry[];
+  readonly lines: readonly string[];
+}
+
+export interface ListOptions {
+  readonly assetsRoot: string; // packages/agent-settings package root (holds assets/mcp.json and assets/agents/)
+  readonly targetRepo: string;
+  readonly profile?: DeployProfile;
+  readonly servers?: readonly McpServerSpec[];
+  readonly agents?: readonly AgentDef[];
+}
+
+function formatLine(label: string, entry: Pick<ListEntry, "available" | "deployedIn" | "owner">): string {
+  const available = entry.available ? "available" : "-";
+  const deployed = entry.deployedIn.length > 0 ? [...entry.deployedIn].sort().join(",") : "-";
+  return `${label}  ${available}  deployed:${deployed}  owner:${entry.owner}`;
+}
+
+export function listSettings(options: ListOptions): ListResult {
+  const profile = options.profile ?? loadProfile();
+  const servers = options.servers ?? loadMcpSource();
+  const agents = options.agents ?? loadAgentSources(join(options.assetsRoot, profile.agents.source));
+  const lock = readLock(options.targetRepo);
+
+  const entries: ListEntry[] = [];
+
+  // --- MCP ---
+  const sourceServerNames = new Set(servers.map((s) => s.name));
+  const perMcpSurface = profile.mcp.surfaces.map((surface) => ({ surface, names: new Set(readDeployedMcpServerNames(options.targetRepo, surface)) }));
+  const allMcpNames = new Set<string>(sourceServerNames);
+  for (const { names } of perMcpSurface) for (const n of names) allMcpNames.add(n);
+
+  for (const name of [...allMcpNames].sort()) {
+    const deployedIn: string[] = [];
+    let anyOwned = false;
+    let anyUnowned = false;
+    for (const { surface, names } of perMcpSurface) {
+      if (!names.has(name)) continue;
+      deployedIn.push(surface.name);
+      if (mcpServerOwned(lock, surface.file, name) || lock.mcp[surface.file]?.kind === "block") anyOwned = true;
+      else anyUnowned = true;
+    }
+    const available = sourceServerNames.has(name);
+    let owner: ItemOwner = "-";
+    if (deployedIn.length > 0) {
+      if (anyOwned && anyUnowned) owner = "conflict";
+      else if (anyOwned) owner = "adl";
+      else owner = available ? "conflict" : "user";
+    }
+    const base = { kind: "mcp" as const, name, available, deployedIn: deployedIn.sort(), owner };
+    entries.push({ ...base, line: formatLine(`mcp:${name}`, base) });
+  }
+
+  // --- Agents ---
+  const sourceAgentNames = new Set(agents.map((a) => a.name));
+  const perAgentSurface = profile.agents.surfaces.map((surface) => {
+    const ext = extensionFor(surface);
+    const folderAbs = join(options.targetRepo, surface.folder);
+    const names = new Set(
+      existsSync(folderAbs)
+        ? readdirSync(folderAbs, { withFileTypes: true })
+            .filter((e) => e.isFile() && e.name.endsWith(`.${ext}`))
+            .map((e) => e.name.slice(0, -(ext.length + 1)))
+        : [],
+    );
+    return { surface, ext, names };
+  });
+  const allAgentNames = new Set<string>(sourceAgentNames);
+  for (const { names } of perAgentSurface) for (const n of names) allAgentNames.add(n);
+
+  for (const name of [...allAgentNames].sort()) {
+    const deployedIn: string[] = [];
+    let anyOwned = false;
+    let anyUnowned = false;
+    for (const { surface, names } of perAgentSurface) {
+      if (!names.has(name)) continue;
+      deployedIn.push(surface.name);
+      if (agentOwned(lock, surface.folder, name)) anyOwned = true;
+      else anyUnowned = true;
+    }
+    const available = sourceAgentNames.has(name);
+    let owner: ItemOwner = "-";
+    if (deployedIn.length > 0) {
+      if (anyOwned && anyUnowned) owner = "conflict";
+      else if (anyOwned) owner = "adl";
+      else owner = available ? "conflict" : "user";
+    }
+    const base = { kind: "agent" as const, name, available, deployedIn: deployedIn.sort(), owner };
+    entries.push({ ...base, line: formatLine(`agent:${name}`, base) });
+  }
+
+  // --- lean-ctx ---
+  if (profile.leanCtx !== undefined) {
+    const leanCtxAssetsDir = join(options.assetsRoot, profile.leanCtx.source);
+    for (const file of profile.leanCtx.files) {
+      const targetAbs = join(options.targetRepo, file.target);
+      const deployed = existsSync(targetAbs);
+      const owned = leanCtxOwned(lock, file.target);
+      const available = existsSync(join(leanCtxAssetsDir, file.asset));
+      const owner: ItemOwner = deployed ? (owned ? "adl" : "conflict") : "-";
+      const base = { kind: "lean-ctx" as const, name: file.target, available, deployedIn: deployed ? [file.target] : [], owner };
+      entries.push({ ...base, line: formatLine(`lean-ctx:${basename(file.target)}`, base) });
+    }
+  }
+
+  return { entries, lines: entries.map((e) => e.line) };
+}

package/packages/agent-settings/src/deploy/lock.ts

@@ -0,0 +1,112 @@
+/**
+ * `<repo>/.agents/agent-settings.lock.json` — the record of exactly what
+ * THIS package's own deploy wrote into a target repository, mirroring
+ * packages/agent-skills' manifest.ts and packages/agent-hooks' lock.ts.
+ *
+ * Two independent record kinds, since MCP and agents have different removal
+ * units:
+ *  - `mcp`: target file -> either the MCP server NAMES this deploy wrote
+ *    into that file's server map (claude-json/cursor-json/kimi-json/
+ *    opencode-json — a per-key JSON merge, same shape as agent-hooks'
+ *    ownedCommands), or `{ block: true }` for codex-toml-block, whose whole
+ *    marker-delimited span is regenerated every run so no per-server
+ *    breakdown is needed.
+ *  - `agents`: target folder -> the agent NAMES this deploy wrote as files
+ *    in that folder (one file per agent, so this is the removal unit).
+ *  - `leanCtx`: target path -> `true` for each repo-local lean-ctx file
+ *    (config.toml, layout.toml, .agents/.gitignore) this deploy wrote —
+ *    one whole file is the removal unit, same as agents but keyed directly
+ *    by target path since there is no per-file "container".
+ *
+ * A name/file missing from a later run's lock (because it fell out of
+ * assets/) is removed from the target on that run; anything not recorded
+ * here was never written by us and is never touched.
+ *
+ * `leanCtx` is optional on read: a lock written before this section existed
+ * has no `leanCtx` key, and is treated as owning nothing yet (`{}`), not as
+ * a malformed lock.
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+
+export const LOCK_RELATIVE_PATH = ".agents/agent-settings.lock.json";
+const LOCK_SCHEMA = 1;
+
+export interface McpJsonLockEntry {
+  readonly kind: "json";
+  /** MCP server names this deploy owns in this file's server map. */
+  readonly servers: readonly string[];
+}
+
+export interface McpBlockLockEntry {
+  readonly kind: "block";
+  readonly owned: true;
+}
+
+export type McpLockEntry = McpJsonLockEntry | McpBlockLockEntry;
+
+export interface SettingsLock {
+  readonly schema: number;
+  readonly mcp: Readonly<Record<string, McpLockEntry>>;
+  readonly agents: Readonly<Record<string, readonly string[]>>;
+  readonly leanCtx: Readonly<Record<string, boolean>>;
+}
+
+const EMPTY_LOCK: SettingsLock = { schema: LOCK_SCHEMA, mcp: {}, agents: {}, leanCtx: {} };
+
+export function lockPathFor(targetRepo: string): string {
+  return join(targetRepo, LOCK_RELATIVE_PATH);
+}
+
+export function readLock(targetRepo: string): SettingsLock {
+  const path = lockPathFor(targetRepo);
+  if (!existsSync(path)) return EMPTY_LOCK;
+
+  let doc: unknown;
+  try {
+    doc = JSON.parse(readFileSync(path, "utf8"));
+  } catch (cause) {
+    throw new Error(`agent-settings lock is not valid JSON: ${path} (${(cause as Error).message})`);
+  }
+  const record = doc as Partial<SettingsLock> | null;
+  if (
+    typeof record !== "object" ||
+    record === null ||
+    record.schema !== LOCK_SCHEMA ||
+    typeof record.mcp !== "object" ||
+    record.mcp === null ||
+    typeof record.agents !== "object" ||
+    record.agents === null ||
+    (record.leanCtx !== undefined && (typeof record.leanCtx !== "object" || record.leanCtx === null))
+  ) {
+    throw new Error(`agent-settings lock has an unrecognized shape: ${path}`);
+  }
+  return {
+    schema: LOCK_SCHEMA,
+    mcp: record.mcp as Record<string, McpLockEntry>,
+    agents: record.agents as Record<string, readonly string[]>,
+    leanCtx: (record.leanCtx as Record<string, boolean> | undefined) ?? {},
+  };
+}
+
+export function writeLock(targetRepo: string, lock: SettingsLock): void {
+  const path = lockPathFor(targetRepo);
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, `${JSON.stringify({ schema: LOCK_SCHEMA, mcp: lock.mcp, agents: lock.agents, leanCtx: lock.leanCtx }, null, 2)}\n`);
+}
+
+/** True iff the lock records `serverName` as owned in `file`'s json-merge entry. */
+export function mcpServerOwned(lock: SettingsLock, file: string, serverName: string): boolean {
+  const entry = lock.mcp[file];
+  return entry !== undefined && entry.kind === "json" && entry.servers.includes(serverName);
+}
+
+/** True iff the lock records `agentName` as an adl-owned file in `folder`. */
+export function agentOwned(lock: SettingsLock, folder: string, agentName: string): boolean {
+  return (lock.agents[folder] ?? []).includes(agentName);
+}
+
+/** True iff the lock records `targetPath` as an adl-owned lean-ctx file. */
+export function leanCtxOwned(lock: SettingsLock, targetPath: string): boolean {
+  return lock.leanCtx[targetPath] === true;
+}