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

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

@@ -0,0 +1,129 @@
+/**
+ * Writes every agent under assets/agents/*.toml into a target repository's
+ * five agent surfaces, per the deploy profile (profile.ts) and each
+ * surface's renderer (agent-render.ts). Never touches a file it did not
+ * itself write, per the lock (lock.ts): a same-name agent file the target
+ * repo already owns is left untouched and reported as a conflict, and an
+ * agent dropped from assets/ is removed only when the lock shows this
+ * deploy wrote it.
+ *
+ * Fails loud: a missing assets dir/target repo or an invalid profile all
+ * throw. There is no partial-success return value.
+ */
+import { existsSync, mkdirSync, readFileSync, statSync, unlinkSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { extensionFor, renderAgent } from "./agent-render.js";
+import { loadAgentSources, type AgentDef } from "./agent-toml.js";
+import { legacyFileTakeover, type LegacyLockDoc, readLegacyLock, stripLegacyOwnership } from "./legacy-lock.js";
+import { agentOwned, readLock, writeLock } from "./lock.js";
+import { type DeployProfile, loadProfile } from "./profile.js";
+
+export interface DeployAgentsOptions {
+  readonly assetsDir: string;
+  readonly targetRepo: string;
+  readonly profile?: DeployProfile;
+  readonly agents?: readonly AgentDef[];
+}
+
+export interface AgentConflict {
+  readonly folder: string;
+  readonly agent: string;
+  readonly reason: string;
+}
+
+export interface DeployAgentsResult {
+  readonly written: readonly string[];
+  readonly unchanged: readonly string[];
+  readonly removed: readonly string[];
+  readonly conflicts: readonly AgentConflict[];
+  readonly lockPath: string;
+}
+
+export function deployAgents(options: DeployAgentsOptions): DeployAgentsResult {
+  const { assetsDir, targetRepo } = options;
+
+  if (!existsSync(assetsDir) || !statSync(assetsDir).isDirectory()) {
+    throw new Error(`agent-settings agents assets directory not found: ${assetsDir}`);
+  }
+  if (!existsSync(targetRepo) || !statSync(targetRepo).isDirectory()) {
+    throw new Error(`deploy target is not a directory: ${targetRepo}`);
+  }
+
+  const profile = options.profile ?? loadProfile();
+  const agents = options.agents ?? loadAgentSources(assetsDir);
+  if (agents.length === 0) throw new Error(`agent-settings agents assets directory has no agents: ${assetsDir}`);
+
+  const lock = readLock(targetRepo);
+  const legacyLockPath = profile.legacyLock !== undefined ? join(targetRepo, profile.legacyLock) : undefined;
+  const legacyDoc: LegacyLockDoc | undefined = legacyLockPath !== undefined ? readLegacyLock(legacyLockPath) : undefined;
+  const newAgentEntries: Record<string, readonly string[]> = {};
+  const written: string[] = [];
+  const unchanged: string[] = [];
+  const removed: string[] = [];
+  const conflicts: AgentConflict[] = [];
+  const legacyFileRemovals: string[] = [];
+  let anyLegacyTakeover = false;
+
+  for (const surface of profile.agents.surfaces) {
+    const ext = extensionFor(surface);
+    const kept: string[] = [];
+
+    for (const def of agents) {
+      const relPath = `${surface.folder}/${def.name}.${ext}`;
+      const absPath = join(targetRepo, relPath);
+      const exists = existsSync(absPath);
+      let managedByUs = agentOwned(lock, surface.folder, def.name);
+
+      if (exists && !managedByUs && legacyFileTakeover(readFileSync(absPath), legacyDoc, relPath)) {
+        managedByUs = true;
+        legacyFileRemovals.push(relPath);
+        anyLegacyTakeover = true;
+      }
+
+      if (exists && !managedByUs) {
+        conflicts.push({ folder: surface.folder, agent: def.name, reason: "a user-owned agent file already exists with this name; deploy left it untouched" });
+        continue;
+      }
+
+      const content = renderAgent(surface, def);
+      if (exists && readFileSync(absPath, "utf8") === content) {
+        unchanged.push(relPath);
+      } else {
+        mkdirSync(join(targetRepo, surface.folder), { recursive: true });
+        writeFileSync(absPath, content);
+        written.push(relPath);
+      }
+      kept.push(def.name);
+    }
+
+    const previouslyOwned = lock.agents[surface.folder] ?? [];
+    for (const name of previouslyOwned) {
+      if (kept.includes(name)) continue;
+      const relPath = `${surface.folder}/${name}.${ext}`;
+      const absPath = join(targetRepo, relPath);
+      if (existsSync(absPath)) unlinkSync(absPath);
+      removed.push(relPath);
+    }
+
+    newAgentEntries[surface.folder] = kept.sort();
+  }
+
+  writeLock(targetRepo, { schema: 1, mcp: lock.mcp, agents: newAgentEntries, leanCtx: lock.leanCtx });
+
+  // Once anything was actually taken over, this package's own footprint in
+  // the legacy lock's `files` section for these exact agent paths is stale:
+  // ownership has fully moved to .agents/agent-settings.lock.json just
+  // written above. A legacy lock present but untouched by any takeover (no
+  // hash matched, or this repo never had one) is left exactly as found.
+  if (anyLegacyTakeover && legacyDoc !== undefined && legacyLockPath !== undefined) {
+    stripLegacyOwnership(legacyDoc, legacyLockPath, { files: legacyFileRemovals });
+  }
+
+  return {
+    written: written.sort(),
+    unchanged: unchanged.sort(),
+    removed: removed.sort(),
+    conflicts: conflicts.sort((a, b) => `${a.folder}/${a.agent}`.localeCompare(`${b.folder}/${b.agent}`)),
+    lockPath: join(targetRepo, ".agents/agent-settings.lock.json"),
+  };
+}

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

@@ -0,0 +1,201 @@
+/**
+ * This package's own doctor: checks the DEPLOYED state of a target
+ * repository against assets/mcp.json and assets/agents/ — present,
+ * matches what deploy would write, and owned by us where the lock says it
+ * should be. Reports one issue per problem, `severity: 'error'` for
+ * anything that blocks correctness (missing, hand-modified, same-name
+ * conflict, stale lock entry) and `severity: 'info'` for a same-name
+ * unrelated user item that is not a problem, just not ours. `ok` reflects
+ * only `severity: 'error'` issues.
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { extensionFor, renderAgent } from "./agent-render.js";
+import { loadAgentSources, type AgentDef } from "./agent-toml.js";
+import { agentOwned, leanCtxOwned, mcpServerOwned, readLock, type SettingsLock } from "./lock.js";
+import { readDeployedMcpServerNames, readDeployedMcpServerValue } from "./mcp-inspect.js";
+import { renderMcpJsonEntry } from "./mcp-render.js";
+import { loadMcpSource, type McpServerSpec } from "./mcp-source.js";
+import { type DeployProfile, loadProfile } from "./profile.js";
+
+export interface DoctorIssue {
+  readonly severity: "error" | "info";
+  readonly path: string;
+  readonly reason: string;
+}
+
+export interface DoctorResult {
+  readonly ok: boolean;
+  readonly issues: readonly DoctorIssue[];
+}
+
+function toResult(issues: readonly DoctorIssue[]): DoctorResult {
+  return { ok: issues.every((i) => i.severity !== "error"), issues };
+}
+
+export interface DoctorMcpOptions {
+  readonly targetRepo: string;
+  readonly profile?: DeployProfile;
+  readonly servers?: readonly McpServerSpec[];
+  readonly lock?: SettingsLock;
+}
+
+export function doctorMcp(options: DoctorMcpOptions): DoctorResult {
+  const profile = options.profile ?? loadProfile();
+  const servers = options.servers ?? loadMcpSource();
+  const lock = options.lock ?? readLock(options.targetRepo);
+  const issues: DoctorIssue[] = [];
+  const bySpecName = new Map(servers.map((s) => [s.name, s]));
+
+  for (const surface of profile.mcp.surfaces) {
+    const deployedNames = new Set(readDeployedMcpServerNames(options.targetRepo, surface));
+    const lockEntry = lock.mcp[surface.file];
+    const lockOwnsBlock = lockEntry?.kind === "block";
+    const lockOwnedNames = new Set(lockEntry?.kind === "json" ? lockEntry.servers : []);
+
+    for (const spec of servers) {
+      const path = `${surface.file}#${spec.name}`;
+      const present = deployedNames.has(spec.name);
+      const ownedByUs = surface.format === "toml-block" ? lockOwnsBlock : lockOwnedNames.has(spec.name);
+
+      if (!present) {
+        issues.push({ severity: "error", path, reason: ownedByUs ? "deploy-written MCP server is missing from the target repo" : "expected MCP server has not been deployed" });
+        continue;
+      }
+      if (!ownedByUs) {
+        issues.push({ severity: "error", path, reason: "a user-owned MCP server with this name conflicts with an asset server; not managed by deploy" });
+        continue;
+      }
+      if (surface.format !== "toml-block") {
+        const actual = readDeployedMcpServerValue(options.targetRepo, surface, spec.name);
+        const expected = renderMcpJsonEntry(surface.entry, spec);
+        if (JSON.stringify(actual) !== JSON.stringify(expected)) {
+          issues.push({ severity: "error", path, reason: "deploy-written MCP server was modified since deploy" });
+        }
+      }
+    }
+
+    for (const name of lockOwnedNames) {
+      if (bySpecName.has(name)) continue;
+      issues.push({ severity: "error", path: `${surface.file}#${name}`, reason: "deploy-written MCP server is no longer in assets/mcp.json; run deploy to remove it" });
+    }
+
+    for (const name of deployedNames) {
+      if (bySpecName.has(name)) continue;
+      if (lockOwnedNames.has(name)) continue;
+      issues.push({ severity: "info", path: `${surface.file}#${name}`, reason: "user-owned MCP server (not part of agent-settings assets)" });
+    }
+
+    // M6: Codex only reads .codex/config.toml for trusted projects, and
+    // Kimi skips .kimi-code/mcp.json until "Trust this folder" is
+    // accepted. Neither is observable from this repo checkout, so this is
+    // always informational — never a doctor failure.
+    if (surface.name === "codex") {
+      issues.push({ severity: "info", path: surface.file, reason: 'Codex only reads this file for trusted projects; a repo the user has not trusted may not see these servers even though this file is correct.' });
+    }
+    if (surface.name === "kimi") {
+      issues.push({ severity: "info", path: surface.file, reason: 'Kimi Code skips project MCP config until "Trust this folder" is accepted; it may not see these servers even though this file is correct.' });
+    }
+  }
+
+  return toResult(issues);
+}
+
+export interface DoctorAgentsOptions {
+  readonly assetsDir: string;
+  readonly targetRepo: string;
+  readonly profile?: DeployProfile;
+  readonly agents?: readonly AgentDef[];
+  readonly lock?: SettingsLock;
+}
+
+export function doctorAgents(options: DoctorAgentsOptions): DoctorResult {
+  const profile = options.profile ?? loadProfile();
+  const agents = options.agents ?? loadAgentSources(options.assetsDir);
+  const lock = options.lock ?? readLock(options.targetRepo);
+  const issues: DoctorIssue[] = [];
+  const byName = new Map(agents.map((a) => [a.name, a]));
+
+  for (const surface of profile.agents.surfaces) {
+    const ext = extensionFor(surface);
+    const lockOwned = new Set(lock.agents[surface.folder] ?? []);
+
+    for (const def of agents) {
+      const relPath = `${surface.folder}/${def.name}.${ext}`;
+      const absPath = join(options.targetRepo, relPath);
+      const exists = existsSync(absPath);
+      const ownedByUs = lockOwned.has(def.name);
+
+      if (!exists) {
+        issues.push({ severity: "error", path: relPath, reason: ownedByUs ? "deploy-written agent is missing from the target repo" : "expected agent has not been deployed" });
+        continue;
+      }
+      if (!ownedByUs) {
+        issues.push({ severity: "error", path: relPath, reason: "a user-owned agent file with this name conflicts with an asset agent; not managed by deploy" });
+        continue;
+      }
+      const expected = renderAgent(surface, def);
+      if (readFileSync(absPath, "utf8") !== expected) {
+        issues.push({ severity: "error", path: relPath, reason: "deploy-written agent file was modified since deploy" });
+      }
+    }
+
+    for (const name of lockOwned) {
+      if (byName.has(name)) continue;
+      issues.push({ severity: "error", path: `${surface.folder}/${name}.${ext}`, reason: "deploy-written agent is no longer in assets/agents; run deploy to remove it" });
+    }
+  }
+
+  return toResult(issues);
+}
+
+export interface DoctorLeanCtxOptions {
+  readonly assetsDir: string;
+  readonly targetRepo: string;
+  readonly profile?: DeployProfile;
+  readonly lock?: SettingsLock;
+}
+
+export function doctorLeanCtx(options: DoctorLeanCtxOptions): DoctorResult {
+  const profile = options.profile ?? loadProfile();
+  if (profile.leanCtx === undefined) {
+    throw new Error("deploy profile has no leanCtx section");
+  }
+  const lock = options.lock ?? readLock(options.targetRepo);
+  const issues: DoctorIssue[] = [];
+  const lockOwnedTargets = new Set(Object.keys(lock.leanCtx).filter((target) => lock.leanCtx[target] === true));
+
+  for (const file of profile.leanCtx.files) {
+    const assetAbs = join(options.assetsDir, file.asset);
+    const targetAbs = join(options.targetRepo, file.target);
+    const exists = existsSync(targetAbs);
+    const ownedByUs = leanCtxOwned(lock, file.target);
+
+    if (!exists) {
+      issues.push({ severity: "error", path: file.target, reason: ownedByUs ? "deploy-written lean-ctx file is missing from the target repo" : "expected lean-ctx file has not been deployed" });
+      continue;
+    }
+    if (!ownedByUs) {
+      issues.push({ severity: "error", path: file.target, reason: "a user-owned file conflicts with a lean-ctx asset path; not managed by deploy" });
+      continue;
+    }
+    const expected = readFileSync(assetAbs, "utf8");
+    if (readFileSync(targetAbs, "utf8") !== expected) {
+      issues.push({ severity: "error", path: file.target, reason: "deploy-written lean-ctx file was modified since deploy" });
+    }
+  }
+
+  for (const target of lockOwnedTargets) {
+    if (profile.leanCtx.files.some((f) => f.target === target)) continue;
+    issues.push({ severity: "error", path: target, reason: "deploy-written lean-ctx file is no longer in the deploy profile; run deploy to remove it" });
+  }
+
+  return toResult(issues);
+}
+
+export function mergeDoctorResults(results: readonly DoctorResult[]): DoctorResult {
+  const issues = results.flatMap((r) => r.issues);
+  return toResult(issues);
+}
+
+export { mcpServerOwned, agentOwned, leanCtxOwned };

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

@@ -0,0 +1,33 @@
+export { deployMcp, type DeployMcpOptions, type DeployMcpResult, type McpFileConflict } from "./mcp-deploy.js";
+export { deployAgents, type DeployAgentsOptions, type DeployAgentsResult, type AgentConflict } from "./agents-deploy.js";
+export { deployLeanCtx, type DeployLeanCtxOptions, type DeployLeanCtxResult, type LeanCtxConflict } from "./lean-ctx-deploy.js";
+export {
+  doctorMcp,
+  doctorAgents,
+  doctorLeanCtx,
+  mergeDoctorResults,
+  type DoctorIssue,
+  type DoctorResult,
+  type DoctorMcpOptions,
+  type DoctorAgentsOptions,
+  type DoctorLeanCtxOptions,
+} from "./doctor.js";
+export { listSettings, type ListOptions, type ListResult, type ListEntry, type ItemOwner } from "./list.js";
+export { deploySettings, doctorSettings, type SettingsTargetOptions, type DeploySettingsResult } from "./settings.js";
+export { lockPathFor, readLock, writeLock, mcpServerOwned, agentOwned, leanCtxOwned, LOCK_RELATIVE_PATH, type SettingsLock, type McpLockEntry } from "./lock.js";
+export {
+  DEFAULT_PROFILE_PATH,
+  DEFAULT_PROFILE_SCHEMA_PATH,
+  loadProfile,
+  validateProfileDocument,
+  type DeployProfile,
+  type McpSurface,
+  type AgentSurface,
+  type LeanCtxFile,
+  type LeanCtxProfileSection,
+  type ProfileIssue,
+} from "./profile.js";
+export { loadMcpSource, DEFAULT_MCP_SOURCE_PATH, type McpServerSpec } from "./mcp-source.js";
+export { loadAgentSources, parseAgentToml, type AgentDef } from "./agent-toml.js";
+export { renderAgent, extensionFor } from "./agent-render.js";
+export { stringifyPretty } from "./json-pretty.js";

package/packages/agent-settings/src/deploy/json-pretty.ts

@@ -0,0 +1,66 @@
+/**
+ * A JSON serializer matching the formatting this repo's own committed
+ * `.mcp.json` and `opencode.json` already carry: 2-space indent, objects
+ * always expanded one key per line, but an array of scalars (string /
+ * number / boolean / null) collapses onto one line when that line fits
+ * within `printWidth` columns and expands one element per line otherwise —
+ * e.g. `"args": ["mcp", "serve"]` stays inline while
+ * `"args": ["serve", "--tools", "<a 90-char string>"]` wraps.
+ *
+ * This is NOT how plain `JSON.stringify(x, null, 2)` renders (it always
+ * expands a multi-element array one per line regardless of width) — that
+ * plain behaviour is exactly what `.cursor/mcp.json` and
+ * `.kimi-code/mcp.json` use instead (mcp-render.ts calls
+ * `JSON.stringify` directly for those two surfaces). Which formatter a
+ * surface uses is a fact about that already-committed file, not a policy
+ * choice, so it is pinned per format in mcp-merge.ts rather than exposed as
+ * a profile option.
+ */
+const DEFAULT_PRINT_WIDTH = 80;
+const INDENT_UNIT = "  ";
+
+type Json = string | number | boolean | null | readonly Json[] | { readonly [key: string]: Json | undefined };
+
+function isScalar(value: Json): value is string | number | boolean | null {
+  return value === null || typeof value !== "object";
+}
+
+function stringifyArray(value: readonly Json[], indentLevel: number, currentColumn: number, printWidth: number): string {
+  if (value.length === 0) return "[]";
+
+  if (value.every(isScalar)) {
+    const oneLine = `[${value.map((v) => JSON.stringify(v)).join(", ")}]`;
+    if (currentColumn + oneLine.length <= printWidth) return oneLine;
+  }
+
+  const innerIndent = INDENT_UNIT.repeat(indentLevel + 1);
+  const closingIndent = INDENT_UNIT.repeat(indentLevel);
+  const items = value.map((v) => `${innerIndent}${stringify(v, indentLevel + 1, innerIndent.length, printWidth)}`);
+  return `[\n${items.join(",\n")}\n${closingIndent}]`;
+}
+
+function stringifyObject(value: { readonly [key: string]: Json | undefined }, indentLevel: number, printWidth: number): string {
+  const keys = Object.keys(value).filter((k) => value[k] !== undefined);
+  if (keys.length === 0) return "{}";
+
+  const innerIndent = INDENT_UNIT.repeat(indentLevel + 1);
+  const closingIndent = INDENT_UNIT.repeat(indentLevel);
+  const items = keys.map((key) => {
+    const prefix = `${innerIndent}${JSON.stringify(key)}: `;
+    return `${prefix}${stringify(value[key] as Json, indentLevel + 1, prefix.length, printWidth)}`;
+  });
+  return `{\n${items.join(",\n")}\n${closingIndent}}`;
+}
+
+function stringify(value: Json, indentLevel: number, currentColumn: number, printWidth: number): string {
+  if (Array.isArray(value)) return stringifyArray(value, indentLevel, currentColumn, printWidth);
+  if (value !== null && typeof value === "object") {
+    return stringifyObject(value as { readonly [key: string]: Json | undefined }, indentLevel, printWidth);
+  }
+  return JSON.stringify(value);
+}
+
+/** Serializes `value` the way this repo's committed `.mcp.json` / `opencode.json` are formatted (see header). Always ends without a trailing newline; callers append one when writing to disk. */
+export function stringifyPretty(value: Json, printWidth: number = DEFAULT_PRINT_WIDTH): string {
+  return stringify(value, 0, 0, printWidth);
+}

package/packages/agent-settings/src/deploy/lean-ctx-deploy.ts

@@ -0,0 +1,138 @@
+/**
+ * Writes the repo-local lean-ctx config files (config.toml, layout.toml)
+ * and .agents/.gitignore from assets/lean-ctx/, per profile.leanCtx —
+ * verbatim byte copies, no per-surface rendering: L3 (Tarun, 2026-09-28)
+ * ships each asset exactly as it is; this module never edits the allowlist
+ * or any other content inside config.toml.
+ *
+ * Same ownership rule as mcp/agents (lock.ts): a pre-existing file at a
+ * target path the lock does not record is a conflict, left untouched and
+ * reported; a target dropped from profile.leanCtx.files is removed only if
+ * the lock shows this deploy wrote it.
+ *
+ * Fails loud: a missing assets dir/target repo, a profile with no leanCtx
+ * section, or a missing source asset file all throw. There is no
+ * partial-success return value.
+ */
+import { existsSync, mkdirSync, readFileSync, statSync, unlinkSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { legacyFileTakeover, legacyTakeoverForGitignore, type LegacyLockDoc, readLegacyLock, stripLegacyOwnership } from "./legacy-lock.js";
+import { leanCtxOwned, readLock, writeLock } from "./lock.js";
+import { type DeployProfile, loadProfile } from "./profile.js";
+
+export interface DeployLeanCtxOptions {
+  readonly assetsDir: string; // packages/agent-settings/assets/lean-ctx
+  readonly targetRepo: string;
+  readonly profile?: DeployProfile;
+}
+
+export interface LeanCtxConflict {
+  readonly target: string;
+  readonly reason: string;
+}
+
+export interface DeployLeanCtxResult {
+  readonly written: readonly string[];
+  readonly unchanged: readonly string[];
+  readonly removed: readonly string[];
+  readonly conflicts: readonly LeanCtxConflict[];
+  readonly lockPath: string;
+}
+
+export function deployLeanCtx(options: DeployLeanCtxOptions): DeployLeanCtxResult {
+  const { assetsDir, targetRepo } = options;
+
+  if (!existsSync(assetsDir) || !statSync(assetsDir).isDirectory()) {
+    throw new Error(`agent-settings lean-ctx assets directory not found: ${assetsDir}`);
+  }
+  if (!existsSync(targetRepo) || !statSync(targetRepo).isDirectory()) {
+    throw new Error(`deploy target is not a directory: ${targetRepo}`);
+  }
+
+  const profile = options.profile ?? loadProfile();
+  if (profile.leanCtx === undefined) {
+    throw new Error("deploy profile has no leanCtx section");
+  }
+
+  const lock = readLock(targetRepo);
+  const legacyLockPath = profile.legacyLock !== undefined ? join(targetRepo, profile.legacyLock) : undefined;
+  const legacyDoc: LegacyLockDoc | undefined = legacyLockPath !== undefined ? readLegacyLock(legacyLockPath) : undefined;
+  const written: string[] = [];
+  const unchanged: string[] = [];
+  const removed: string[] = [];
+  const conflicts: LeanCtxConflict[] = [];
+  const newLeanCtxEntries: Record<string, boolean> = {};
+  const kept: string[] = [];
+  const legacyFileRemovals: string[] = [];
+  const legacyGitignoreRemovals: string[] = [];
+  let anyLegacyTakeover = false;
+
+  for (const file of profile.leanCtx.files) {
+    const assetAbs = join(assetsDir, file.asset);
+    if (!existsSync(assetAbs)) {
+      throw new Error(`agent-settings lean-ctx asset not found: ${assetAbs}`);
+    }
+    const content = readFileSync(assetAbs, "utf8");
+    const targetAbs = join(targetRepo, file.target);
+    const exists = existsSync(targetAbs);
+    let managedByUs = leanCtxOwned(lock, file.target);
+
+    if (exists && !managedByUs) {
+      const currentContent = readFileSync(targetAbs, "utf8");
+      // Whole-file record (config.toml/layout.toml) first; the legacy engine
+      // recorded .agents/.gitignore differently (created/lines/appended, no
+      // sha256), so fall back to that comparison for whichever target it is.
+      if (legacyFileTakeover(currentContent, legacyDoc, file.target)) {
+        managedByUs = true;
+        legacyFileRemovals.push(file.target);
+        anyLegacyTakeover = true;
+      } else if (legacyTakeoverForGitignore(currentContent, legacyDoc, file.target)) {
+        managedByUs = true;
+        legacyGitignoreRemovals.push(file.target);
+        anyLegacyTakeover = true;
+      }
+    }
+
+    if (exists && !managedByUs) {
+      conflicts.push({ target: file.target, reason: "a user-owned file already exists at this path; deploy left it untouched" });
+      continue;
+    }
+
+    if (exists && readFileSync(targetAbs, "utf8") === content) {
+      unchanged.push(file.target);
+    } else {
+      mkdirSync(dirname(targetAbs), { recursive: true });
+      writeFileSync(targetAbs, content);
+      written.push(file.target);
+    }
+    newLeanCtxEntries[file.target] = true;
+    kept.push(file.target);
+  }
+
+  for (const target of Object.keys(lock.leanCtx)) {
+    if (kept.includes(target)) continue;
+    const targetAbs = join(targetRepo, target);
+    if (existsSync(targetAbs)) unlinkSync(targetAbs);
+    removed.push(target);
+  }
+
+  writeLock(targetRepo, { schema: 1, mcp: lock.mcp, agents: lock.agents, leanCtx: newLeanCtxEntries });
+
+  // Once anything was actually taken over, this package's own footprint in
+  // the legacy lock (these exact `files` entries and/or the `.agents/.gitignore`
+  // `gitignore` entry) is stale: ownership has fully moved to
+  // .agents/agent-settings.lock.json just written above. A legacy lock
+  // present but untouched by any takeover (no hash matched, or this repo
+  // never had one) is left exactly as found.
+  if (anyLegacyTakeover && legacyDoc !== undefined && legacyLockPath !== undefined) {
+    stripLegacyOwnership(legacyDoc, legacyLockPath, { files: legacyFileRemovals, gitignore: legacyGitignoreRemovals });
+  }
+
+  return {
+    written: written.sort(),
+    unchanged: unchanged.sort(),
+    removed: removed.sort(),
+    conflicts: conflicts.sort((a, b) => a.target.localeCompare(b.target)),
+    lockPath: join(targetRepo, ".agents/agent-settings.lock.json"),
+  };
+}