@amsterdamdatalabs/adl-agent-control-linux-x64 0.1.12 → 0.1.26

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

@@ -1,33 +1,6 @@
-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";
+export { type DoctorResult } from "./doctor.js";
+export { listSettings } from "./list.js";
+export { deploySettings, doctorSettings, type DeploySettingsResult } from "./settings.js";
+export { loadProfile } from "./profile.js";
+export { loadMcpSource, type McpServerSpec } from "./mcp-source.js";
+export { loadAgentSources, type AgentDef } from "./agent-toml.js";

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

@@ -65,7 +65,7 @@ export const sha256Hex = (input: string | Buffer): string => createHash("sha256"
  * 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 {
+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>)
@@ -81,18 +81,18 @@ export const legacyValueHash = (value: unknown): string => sha256Hex(stableStrin
 
 export type LegacyJsonPath = readonly (string | number)[];
 
-export interface LegacyJsonMergeEntry {
+interface LegacyJsonMergeEntry {
   readonly type: string;
   readonly path: LegacyJsonPath;
   readonly sha256: string;
 }
 
-export interface LegacyMergedRecord {
+interface LegacyMergedRecord {
   readonly entries?: readonly LegacyJsonMergeEntry[];
   readonly [key: string]: unknown;
 }
 
-export interface LegacyGitignoreRecord {
+interface LegacyGitignoreRecord {
   readonly created?: boolean;
   readonly lines?: readonly string[];
   readonly appended?: string;
@@ -126,7 +126,7 @@ export function readLegacyLock(path: string): LegacyLockDoc | undefined {
 }
 
 /** 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 {
+function legacyFileHash(doc: LegacyLockDoc | undefined, file: string): string | undefined {
   return doc?.files?.[file]?.sha256;
 }
 
@@ -207,7 +207,7 @@ export function legacyTakeoverForGitignore(content: string, doc: LegacyLockDoc |
   return false;
 }
 
-export interface LegacyMergedRemoval {
+interface LegacyMergedRemoval {
   readonly file: string;
   readonly paths: readonly LegacyJsonPath[];
 }

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

@@ -6,18 +6,18 @@
  * (mirrors packages/agent-skills/src/list.ts's shape).
  */
 import { existsSync, readdirSync } from "node:fs";
-import { basename, join } from "node:path";
+import { 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 { agentOwned, 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" | "-";
+type ItemOwner = "adl" | "user" | "conflict" | "-";
 
-export interface ListEntry {
-  readonly kind: "mcp" | "agent" | "lean-ctx";
+interface ListEntry {
+  readonly kind: "mcp" | "agent";
   readonly name: string;
   readonly available: boolean;
   readonly deployedIn: readonly string[];
@@ -117,19 +117,5 @@ export function listSettings(options: ListOptions): ListResult {
     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

@@ -13,32 +13,27 @@
  *    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.
+ * The optional `leanCtx` field remains readable only so deploy can retire
+ * paths recorded by older releases. New locks never write it.
  */
 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_RELATIVE_PATH = ".agents/agent-settings.lock.json";
 const LOCK_SCHEMA = 1;
 
-export interface McpJsonLockEntry {
+interface McpJsonLockEntry {
   readonly kind: "json";
   /** MCP server names this deploy owns in this file's server map. */
   readonly servers: readonly string[];
 }
 
-export interface McpBlockLockEntry {
+interface McpBlockLockEntry {
   readonly kind: "block";
   readonly owned: true;
 }
@@ -49,10 +44,10 @@ 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>>;
+  readonly leanCtx?: Readonly<Record<string, boolean>>;
 }
 
-const EMPTY_LOCK: SettingsLock = { schema: LOCK_SCHEMA, mcp: {}, agents: {}, leanCtx: {} };
+const EMPTY_LOCK: SettingsLock = { schema: LOCK_SCHEMA, mcp: {}, agents: {} };
 
 export function lockPathFor(targetRepo: string): string {
   return join(targetRepo, LOCK_RELATIVE_PATH);
@@ -92,7 +87,7 @@ export function readLock(targetRepo: string): SettingsLock {
 /** Skips the write entirely when the serialized content is already byte-identical (independent review, 2026-09-29, finding 8: a genuine no-op run must not touch the lock file's mtime either). */
 export function writeLock(targetRepo: string, lock: SettingsLock): void {
   const path = lockPathFor(targetRepo);
-  const next = `${JSON.stringify({ schema: LOCK_SCHEMA, mcp: lock.mcp, agents: lock.agents, leanCtx: lock.leanCtx }, null, 2)}\n`;
+  const next = `${JSON.stringify({ schema: LOCK_SCHEMA, mcp: lock.mcp, agents: lock.agents }, null, 2)}\n`;
   if (existsSync(path) && readFileSync(path, "utf8") === next) return;
   mkdirSync(dirname(path), { recursive: true });
   writeFileSync(path, next);
@@ -108,8 +103,3 @@ export function mcpServerOwned(lock: SettingsLock, file: string, serverName: str
 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;
-}

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

@@ -24,7 +24,7 @@ import {
   readLegacyLock,
   stripLegacyOwnership,
 } from "./legacy-lock.js";
-import { type SettingsLock, type McpLockEntry, readLock, writeLock } from "./lock.js";
+import { type McpLockEntry, readLock, writeLock } from "./lock.js";
 import { hasForeignTopLevelTable, mergeCodexBlock, mergeServerMap } from "./mcp-merge.js";
 import { renderCodexManagedBlock, renderMcpJsonEntry } from "./mcp-render.js";
 import { loadMcpSource, type McpServerSpec } from "./mcp-source.js";
@@ -40,7 +40,7 @@ export interface DeployMcpOptions {
   readonly dryRun?: boolean;
 }
 
-export interface McpFileConflict {
+interface McpFileConflict {
   readonly file: string;
   readonly server: string;
   readonly reason: string;
@@ -50,6 +50,8 @@ export interface DeployMcpResult {
   readonly written: readonly string[];
   readonly unchanged: readonly string[];
   readonly conflicts: readonly McpFileConflict[];
+  /** Same-name entries not in the lock whose value was identical to what deploy renders: taken over, locked, never a conflict. */
+  readonly adopted: readonly { readonly file: string; readonly server: string }[];
   readonly lockPath: string;
 }
 
@@ -95,6 +97,7 @@ export function deployMcp(options: DeployMcpOptions): DeployMcpResult {
   const written: string[] = [];
   const unchanged: string[] = [];
   const conflicts: McpFileConflict[] = [];
+  const adopted: { file: string; server: string }[] = [];
   const legacyMergedRemovals: { file: string; paths: LegacyJsonPath[] }[] = [];
   const legacyTomlRemovals: string[] = [];
   let anyLegacyTakeover = false;
@@ -147,15 +150,16 @@ export function deployMcp(options: DeployMcpOptions): DeployMcpResult {
     const effectivePreviousOwned = legacyTakeover.matched ? [...new Set([...previousOwned, ...legacyTakeover.ownedServers])] : previousOwned;
     const desired = new Map<string, unknown>(servers.map((spec) => [spec.name, renderMcpJsonEntry(surface.entry, spec)]));
 
-    const { fileContent, ownedServers, conflicts: serverConflicts, changed } = mergeServerMap(existingRaw, topKey, desired, effectivePreviousOwned);
+    const { fileContent, ownedServers, conflicts: serverConflicts, adopted: serverAdopted, changed } = mergeServerMap(existingRaw, topKey, desired, effectivePreviousOwned);
     for (const c of serverConflicts) conflicts.push({ file: surface.file, server: c.server, reason: c.reason });
+    for (const server of serverAdopted) adopted.push({ file: surface.file, server });
 
     writeIfChanged(targetAbs, `${serializeJsonStyle(surface.jsonStyle as "width-aware" | "expanded", fileContent)}\n`, changed, dryRun);
     (changed ? written : unchanged).push(surface.file);
     newMcpEntries[surface.file] = { kind: "json", servers: ownedServers };
   }
 
-  if (!dryRun) writeLock(targetRepo, { schema: 1, mcp: newMcpEntries, agents: lock.agents, leanCtx: lock.leanCtx });
+  if (!dryRun) writeLock(targetRepo, { schema: 1, mcp: newMcpEntries, agents: lock.agents });
 
   // Once anything was actually taken over, this package's own footprint in
   // the legacy lock (the four MCP `merged` sections and the codex `toml`
@@ -171,8 +175,9 @@ export function deployMcp(options: DeployMcpOptions): DeployMcpResult {
     written: written.sort(),
     unchanged: unchanged.sort(),
     conflicts: conflicts.sort((a, b) => `${a.file}/${a.server}`.localeCompare(`${b.file}/${b.server}`)),
+    adopted: adopted.sort((a, b) => `${a.file}/${a.server}`.localeCompare(`${b.file}/${b.server}`)),
     lockPath: join(targetRepo, ".agents/agent-settings.lock.json"),
   };
 }
 
-export type { SettingsLock };
+;

package/packages/agent-settings/src/deploy/mcp-merge.ts

@@ -22,7 +22,9 @@
  * `.cursor/mcp.json` / `.kimi-code/mcp.json` / the `mcp` key of
  * `opencode.json` / the codex block (up to its marker line) byte-for-byte.
  */
-export interface McpServerConflict {
+import { isDeepStrictEqual } from "node:util";
+
+interface McpServerConflict {
   readonly server: string;
   readonly reason: string;
 }
@@ -32,6 +34,8 @@ export interface JsonServerMergeResult {
   /** New lock contents: the MCP server names this deploy now owns in this file's server map. */
   readonly ownedServers: readonly string[];
   readonly conflicts: readonly McpServerConflict[];
+  /** Same-name servers not recorded as ours whose value is deep-equal to what deploy renders: adopted into `ownedServers`, never a conflict. */
+  readonly adopted: readonly string[];
   readonly changed: boolean;
 }
 
@@ -40,7 +44,11 @@ export interface JsonServerMergeResult {
  * `desired` must be provided in the exact order a fresh file should list
  * servers in. A same-name server already present and NOT recorded as ours
  * in a previous run (`previousOwned`) is a conflict: left untouched,
- * reported, never claimed in `ownedServers` (M4/D5-equivalent for MCP).
+ * reported, never claimed in `ownedServers` (M4/D5-equivalent for MCP) —
+ * unless its value is deep-equal to the desired one, in which case it holds
+ * no user content and is ADOPTED (Tarun, 2026-10-01): recorded in
+ * `ownedServers` and named in `adopted`, same rule as lean-ctx's
+ * `adoptUnmarkedManagedText`. Any difference at all stays a conflict.
  */
 export function mergeServerMap(
   existing: Record<string, unknown> | undefined,
@@ -64,8 +72,19 @@ export function mergeServerMap(
 
   const conflicts: McpServerConflict[] = [];
   const owned: string[] = [];
+  const adopted: string[] = [];
   for (const [name, value] of desired) {
     if (Object.prototype.hasOwnProperty.call(newServers, name)) {
+      if (isDeepStrictEqual(newServers[name], value)) {
+        // Identical to what we would write: take it over. Re-added below at
+        // the desired position, exactly like an entry we already owned, so
+        // the next run's drop-and-re-add sees the same order (no-op).
+        delete newServers[name];
+        newServers[name] = value;
+        owned.push(name);
+        adopted.push(name);
+        continue;
+      }
       conflicts.push({ server: name, reason: "a user-owned MCP server already exists with this name; deploy left it untouched" });
       continue; // never overwrite it, never claim it in the lock
     }
@@ -76,7 +95,7 @@ export function mergeServerMap(
   base[topKey] = newServers;
   const changed = existing === undefined || JSON.stringify(existingServers) !== JSON.stringify(newServers);
 
-  return { fileContent: base, ownedServers: owned, conflicts, changed };
+  return { fileContent: base, ownedServers: owned, conflicts, adopted, changed };
 }
 
 export interface CodexBlockMergeResult {

package/packages/agent-settings/src/deploy/mcp-source.ts

@@ -14,7 +14,7 @@ export interface McpServerSpec {
   readonly args: readonly string[];
 }
 
-export const DEFAULT_MCP_SOURCE_PATH = fileURLToPath(new URL("../../assets/mcp.json", import.meta.url));
+const DEFAULT_MCP_SOURCE_PATH = fileURLToPath(new URL("../../assets/mcp.json", import.meta.url));
 
 function isServerSpec(value: unknown): value is { command: string; args: readonly string[] } {
   if (typeof value !== "object" || value === null) return false;

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

@@ -34,13 +34,13 @@ import Ajv, { type ErrorObject, type ValidateFunction } from "ajv";
 import { readFileSync } from "node:fs";
 import { fileURLToPath } from "node:url";
 
-export type McpSurfaceFormat = "json" | "toml-block";
-export type AgentSurfaceFormat = "md" | "toml";
-export type McpJsonStyle = "width-aware" | "expanded";
+type McpSurfaceFormat = "json" | "toml-block";
+type AgentSurfaceFormat = "md" | "toml";
+type McpJsonStyle = "width-aware" | "expanded";
 export type McpFromToken = "command" | "args" | "commandArgs";
 /** The full set a `from` token may name across BOTH front-matter fields and TOML fields; which subset is valid for which is enforced by the schema's two separate enums (agentFrontMatterField vs agentTomlField). */
 export type AgentFromToken = "name" | "description" | "model" | "claude_model" | "cursor_model" | "tools" | "model_reasoning_effort" | "sandbox_mode";
-export type AgentFieldStyle = "plain" | "csv-list";
+type AgentFieldStyle = "plain" | "csv-list";
 
 export interface McpEntryField {
   readonly key: string;
@@ -49,7 +49,7 @@ export interface McpEntryField {
 }
 
 /** A static (non-per-server) field in a `topLevel` TOML table — always a constant, since there is no per-server spec to draw `from`. */
-export interface McpTopLevelField {
+interface McpTopLevelField {
   readonly key: string;
   readonly const: string | boolean | number;
 }
@@ -103,40 +103,28 @@ export interface AgentSurface {
   readonly bodyField?: "developer_instructions";
 }
 
-export interface McpProfileSection {
+interface McpProfileSection {
   readonly source: string;
   readonly marker?: string;
   readonly surfaces: readonly McpSurface[];
 }
 
-export interface AgentProfileSection {
+interface AgentProfileSection {
   readonly source: string;
   readonly surfaces: readonly AgentSurface[];
 }
 
-export interface LeanCtxFile {
-  readonly asset: string;
-  readonly target: string;
-}
-
-export interface LeanCtxProfileSection {
-  readonly source: string;
-  readonly files: readonly LeanCtxFile[];
-}
-
 export interface DeployProfile {
   readonly mcp: McpProfileSection;
   readonly agents: AgentProfileSection;
-  /** Optional: absent in older/fixture profiles (e.g. tests/fixtures/two-surface-profile.json), which cover only mcp/agents. deployLeanCtx/doctorLeanCtx throw if called against a profile without this section. */
-  readonly leanCtx?: LeanCtxProfileSection;
   /** Repo-relative path to the pre-agent-settings engine's own install lock, if this repo may still carry one (see deploy-profile.schema.json and legacy-lock.ts). */
   readonly legacyLock?: string;
 }
 
-export const DEFAULT_PROFILE_PATH = fileURLToPath(new URL("../../deploy-profile.json", import.meta.url));
-export const DEFAULT_PROFILE_SCHEMA_PATH = fileURLToPath(new URL("../../deploy-profile.schema.json", import.meta.url));
+const DEFAULT_PROFILE_PATH = fileURLToPath(new URL("../../deploy-profile.json", import.meta.url));
+const DEFAULT_PROFILE_SCHEMA_PATH = fileURLToPath(new URL("../../deploy-profile.schema.json", import.meta.url));
 
-export interface ProfileIssue {
+interface ProfileIssue {
   readonly path: string;
   readonly message: string;
 }
@@ -250,18 +238,6 @@ function crossFieldChecks(doc: DeployProfile): readonly ProfileIssue[] {
     }
   });
 
-  if (doc.leanCtx !== undefined) {
-    const leanCtxTargets = new Set<string>();
-    const leanCtxAssets = new Set<string>();
-    doc.leanCtx.files.forEach((file, index) => {
-      const p = `/leanCtx/files/${index}`;
-      if (leanCtxTargets.has(file.target)) issues.push({ path: `${p}/target`, message: `duplicate leanCtx target: ${file.target}` });
-      leanCtxTargets.add(file.target);
-      if (leanCtxAssets.has(file.asset)) issues.push({ path: `${p}/asset`, message: `duplicate leanCtx asset: ${file.asset}` });
-      leanCtxAssets.add(file.asset);
-    });
-  }
-
   return issues;
 }
 
@@ -271,7 +247,7 @@ function crossFieldChecks(doc: DeployProfile): readonly ProfileIssue[] {
  * comment). Pure: never throws for a structurally-wrong `doc` (returns
  * issues instead); only a missing/malformed `schemaPath` throws.
  */
-export function validateProfileDocument(doc: unknown, schemaPath: string = DEFAULT_PROFILE_SCHEMA_PATH): readonly ProfileIssue[] {
+function validateProfileDocument(doc: unknown, schemaPath: string = DEFAULT_PROFILE_SCHEMA_PATH): readonly ProfileIssue[] {
   const validate = compileValidator(schemaPath);
   if (!validate(doc)) {
     return (validate.errors ?? []).map(formatAjvError);

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

@@ -0,0 +1,184 @@
+/** Remove repo-local lean-ctx artifacts recorded by older agent-settings locks. */
+import { existsSync, lstatSync, readFileSync, rmSync, rmdirSync, unlinkSync, writeFileSync } from "node:fs";
+import { dirname, isAbsolute, relative, resolve, sep } from "node:path";
+import {
+  legacyFileTakeover,
+  legacyTakeoverForGitignore,
+  readLegacyLock,
+  stripLegacyOwnership,
+  type LegacyLockDoc,
+} from "./legacy-lock.js";
+import { readLock, writeLock } from "./lock.js";
+
+const LOCKED_LEAN_CTX_ROOT = ".agents/lean-ctx";
+const AGENTS_GITIGNORE = ".agents/.gitignore";
+const RETIRED_GITIGNORE_LINE = /^\/(?:lean-ctx\/(?:data|cache|state|bin)\/|lean-ctx\/config\/lean-ctx\/workspace-trust\.toml)$/;
+
+export interface RetireLeanCtxOptions {
+  readonly targetRepo: string;
+  readonly legacyLockPath?: string;
+  readonly dryRun?: boolean;
+}
+
+export interface RetireLeanCtxResult {
+  readonly removed: readonly string[];
+}
+
+function isWithin(root: string, path: string): boolean {
+  const rel = relative(root, path);
+  return rel !== "" && rel !== ".." && !rel.startsWith(`..${sep}`) && !isAbsolute(rel);
+}
+
+function assertOwnedTarget(targetRepo: string, target: string): string {
+  if (target !== AGENTS_GITIGNORE && !target.startsWith(`${LOCKED_LEAN_CTX_ROOT}/`)) {
+    throw new Error(`agent-settings retirement lock contains an unexpected lean-ctx path: ${target}`);
+  }
+  const absolute = resolve(targetRepo, target);
+  if (!isWithin(resolve(targetRepo), absolute)) {
+    throw new Error(`agent-settings retirement path escapes target repo: ${target}`);
+  }
+  return absolute;
+}
+
+function assertRegularFile(path: string): void {
+  const stat = lstatSync(path);
+  if (!stat.isFile()) throw new Error(`agent-settings retirement target is not a regular file: ${path}`);
+}
+
+function removeLegacyGitignore(content: string, record: NonNullable<LegacyLockDoc["gitignore"]>[string]): string | undefined {
+  if (record.created === true) return undefined;
+  const owned = record.appended ?? (record.lines === undefined ? undefined : `${record.lines.join("\n")}\n`);
+  if (owned === undefined || !content.endsWith(owned)) {
+    throw new Error("agent-settings retirement could not isolate the legacy lean-ctx .agents/.gitignore addition");
+  }
+  const remaining = content.slice(0, -owned.length);
+  return remaining.length === 0 ? undefined : remaining;
+}
+
+function removeManagedGitignoreBlock(content: string): string | undefined {
+  const lines = content.match(/[^\n]*\n|[^\n]+$/g) ?? [];
+  const open = "# >>> adl managed (do not edit within this block) >>>\n";
+  const close = "# <<< adl managed <<<\n";
+  const starts = lines.flatMap((line, index) => line === open ? [index] : []);
+  const ends = lines.flatMap((line, index) => line === close ? [index] : []);
+  if (starts.length !== ends.length || starts.length > 1 || (starts.length === 1 && (ends[0] as number) < (starts[0] as number))) {
+    throw new Error("agent-settings retirement found malformed managed markers in .agents/.gitignore");
+  }
+  if (starts.length === 1) lines.splice(starts[0] as number, (ends[0] as number) - (starts[0] as number) + 1);
+  const remaining = lines
+    .filter((line) => !RETIRED_GITIGNORE_LINE.test(line.replace(/\r?\n$/, "")))
+    .join("");
+  return remaining.length === 0 ? undefined : remaining;
+}
+
+function pruneEmptyDirectories(targetRepo: string, start: string, dryRun: boolean): void {
+  const stop = resolve(targetRepo, LOCKED_LEAN_CTX_ROOT);
+  let current = dirname(start);
+  while (current === stop || isWithin(stop, current)) {
+    if (!dryRun) {
+      try {
+        rmdirSync(current);
+      } catch (error) {
+        const code = (error as NodeJS.ErrnoException).code;
+        if (code === "ENOENT") {
+          current = dirname(current);
+          continue;
+        }
+        if (code === "ENOTEMPTY" || code === "EEXIST") return;
+        throw error;
+      }
+    }
+    if (current === stop) return;
+    current = dirname(current);
+  }
+}
+
+/**
+ * One-time migration for the leanCtx lock field and the legacy installer
+ * records. It removes only lock-owned paths; new locks omit the retired field.
+ */
+export function retireLeanCtx(options: RetireLeanCtxOptions): RetireLeanCtxResult {
+  const { targetRepo, dryRun = false } = options;
+  const lock = readLock(targetRepo);
+  const legacy = options.legacyLockPath === undefined ? undefined : readLegacyLock(options.legacyLockPath);
+  const targets = new Set(Object.entries(lock.leanCtx ?? {}).filter(([, owned]) => owned === true).map(([target]) => target));
+  const legacyFiles: string[] = [];
+  const legacyGitignore: string[] = [];
+  const legacyReplacements = new Map<string, string | undefined>();
+
+  for (const target of Object.keys(legacy?.files ?? {})) {
+    if (!target.startsWith(`${LOCKED_LEAN_CTX_ROOT}/`)) continue;
+    const absolute = assertOwnedTarget(targetRepo, target);
+    if (!existsSync(absolute)) continue;
+    assertRegularFile(absolute);
+    if (legacyFileTakeover(readFileSync(absolute), legacy, target)) {
+      targets.add(target);
+      legacyFiles.push(target);
+    }
+  }
+
+  const legacyGitignoreRecord = legacy?.gitignore?.[AGENTS_GITIGNORE];
+  const gitignoreAbs = targets.has(AGENTS_GITIGNORE) || legacyGitignoreRecord !== undefined
+    ? assertOwnedTarget(targetRepo, AGENTS_GITIGNORE)
+    : undefined;
+  if (legacyGitignoreRecord !== undefined && gitignoreAbs !== undefined && existsSync(gitignoreAbs)) {
+    assertRegularFile(gitignoreAbs);
+    const current = readFileSync(gitignoreAbs, "utf8");
+    if (legacyTakeoverForGitignore(current, legacy, AGENTS_GITIGNORE)) {
+      legacyReplacements.set(AGENTS_GITIGNORE, removeLegacyGitignore(current, legacyGitignoreRecord));
+      legacyGitignore.push(AGENTS_GITIGNORE);
+      targets.add(AGENTS_GITIGNORE);
+    }
+  }
+
+  for (const target of targets) {
+    const absolute = assertOwnedTarget(targetRepo, target);
+    if (!existsSync(absolute) || target === AGENTS_GITIGNORE) continue;
+    assertRegularFile(absolute);
+  }
+
+  const removed: string[] = [];
+  const ownsRepoTree = [...targets].some((target) => target.startsWith(`${LOCKED_LEAN_CTX_ROOT}/`));
+  const repoTreeAbs = resolve(targetRepo, LOCKED_LEAN_CTX_ROOT);
+  if (ownsRepoTree && existsSync(repoTreeAbs)) {
+    const treeStat = lstatSync(repoTreeAbs);
+    if (!treeStat.isDirectory() || treeStat.isSymbolicLink()) {
+      throw new Error(`agent-settings retirement tree is not a real directory: ${repoTreeAbs}`);
+    }
+    if (!dryRun) rmSync(repoTreeAbs, { recursive: true });
+    removed.push(LOCKED_LEAN_CTX_ROOT);
+  }
+  for (const target of targets) {
+    const absolute = assertOwnedTarget(targetRepo, target);
+    if (target.startsWith(`${LOCKED_LEAN_CTX_ROOT}/`)) continue;
+    if (!existsSync(absolute)) {
+      if (target !== AGENTS_GITIGNORE) pruneEmptyDirectories(targetRepo, absolute, dryRun);
+      continue;
+    }
+    if (target === AGENTS_GITIGNORE) {
+      assertRegularFile(absolute);
+      const current = readFileSync(absolute, "utf8");
+      const replacement = legacyReplacements.has(target)
+        ? legacyReplacements.get(target)
+        : removeManagedGitignoreBlock(current);
+      if (replacement === undefined || replacement.length === 0) {
+        if (!dryRun) unlinkSync(absolute);
+      } else if (replacement !== current && !dryRun) {
+        writeFileSync(absolute, replacement);
+      }
+      removed.push(target);
+      continue;
+    }
+    if (!dryRun) unlinkSync(absolute);
+    removed.push(target);
+    pruneEmptyDirectories(targetRepo, absolute, dryRun);
+  }
+
+  if (!dryRun) {
+    if (lock.leanCtx !== undefined) writeLock(targetRepo, { schema: 1, mcp: lock.mcp, agents: lock.agents });
+    if (legacy !== undefined && options.legacyLockPath !== undefined && (legacyFiles.length > 0 || legacyGitignore.length > 0)) {
+      stripLegacyOwnership(legacy, options.legacyLockPath, { files: legacyFiles, gitignore: legacyGitignore });
+    }
+  }
+  return { removed: removed.sort() };
+}