@amsterdamdatalabs/adl-agent-control-linux-x64 0.1.7 → 0.1.9

package/packages/agent-settings/assets/lean-ctx/layout.toml

@@ -1,5 +1,7 @@
+# >>> adl managed (do not edit within this block) >>>
 # lean-ctx layout pin (GL #623) — managed by lean-ctx, do not edit.
 # Marks this install as committed to the XDG four-dir layout so a stray
 # ~/.lean-ctx never re-collapses config/data/state/cache. Remove via
 # `lean-ctx doctor` only if you intentionally revert to a single-dir layout.
 mode = "xdg"
+# <<< adl managed <<<

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

@@ -23,6 +23,8 @@ export interface DeployAgentsOptions {
   readonly targetRepo: string;
   readonly profile?: DeployProfile;
   readonly agents?: readonly AgentDef[];
+  /** Computes the exact same written/unchanged/removed/conflicts result without writing anything (independent review, 2026-09-29, finding 6). */
+  readonly dryRun?: boolean;
 }
 
 export interface AgentConflict {
@@ -41,6 +43,7 @@ export interface DeployAgentsResult {
 
 export function deployAgents(options: DeployAgentsOptions): DeployAgentsResult {
   const { assetsDir, targetRepo } = options;
+  const dryRun = options.dryRun === true;
 
   if (!existsSync(assetsDir) || !statSync(assetsDir).isDirectory()) {
     throw new Error(`agent-settings agents assets directory not found: ${assetsDir}`);
@@ -89,8 +92,10 @@ export function deployAgents(options: DeployAgentsOptions): DeployAgentsResult {
       if (exists && readFileSync(absPath, "utf8") === content) {
         unchanged.push(relPath);
       } else {
-        mkdirSync(join(targetRepo, surface.folder), { recursive: true });
-        writeFileSync(absPath, content);
+        if (!dryRun) {
+          mkdirSync(join(targetRepo, surface.folder), { recursive: true });
+          writeFileSync(absPath, content);
+        }
         written.push(relPath);
       }
       kept.push(def.name);
@@ -101,21 +106,21 @@ export function deployAgents(options: DeployAgentsOptions): DeployAgentsResult {
       if (kept.includes(name)) continue;
       const relPath = `${surface.folder}/${name}.${ext}`;
       const absPath = join(targetRepo, relPath);
-      if (existsSync(absPath)) unlinkSync(absPath);
+      if (!dryRun && existsSync(absPath)) unlinkSync(absPath);
       removed.push(relPath);
     }
 
     newAgentEntries[surface.folder] = kept.sort();
   }
 
-  writeLock(targetRepo, { schema: 1, mcp: lock.mcp, agents: newAgentEntries, leanCtx: lock.leanCtx });
+  if (!dryRun) 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) {
+  if (!dryRun && anyLegacyTakeover && legacyDoc !== undefined && legacyLockPath !== undefined) {
     stripLegacyOwnership(legacyDoc, legacyLockPath, { files: legacyFileRemovals });
   }
 

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

@@ -12,6 +12,7 @@ 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 { resolveConfigTomlWrite, resolveGitignoreWrite, resolveLeanCtxWrite } from "./lean-ctx-merge.js";
 import { agentOwned, leanCtxOwned, mcpServerOwned, readLock, type SettingsLock } from "./lock.js";
 import { readDeployedMcpServerNames, readDeployedMcpServerValue } from "./mcp-inspect.js";
 import { renderMcpJsonEntry } from "./mcp-render.js";
@@ -175,13 +176,48 @@ export function doctorLeanCtx(options: DoctorLeanCtxOptions): DoctorResult {
       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) {
+    // Independent review, 2026-09-30, finding 6: .gitignore is exempted
+    // from this early conflict the same way deploy itself now is — a
+    // markerless, never-adl-written .agents/.gitignore is not a hard
+    // conflict; resolveGitignoreWrite's own append-not-conflict migration
+    // decides it below instead (mirrors lean-ctx-deploy.ts's own guard).
+    if (!ownedByUs && file.asset !== "gitignore") {
       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" });
+    const current = readFileSync(targetAbs, "utf8");
+    // Same merge-contract analysis deploy itself uses (lean-ctx-merge.ts):
+    // a user addition outside the managed block alone is not drift; a
+    // changed/removed/malformed managed block, or a duplicate key, is.
+    if (current !== expected) {
+      const outcome =
+        file.asset === "config.toml"
+          ? resolveConfigTomlWrite(expected, current, ownedByUs)
+          : file.asset === "gitignore"
+            ? resolveGitignoreWrite(expected, current, ownedByUs)
+            : resolveLeanCtxWrite(expected, current, ownedByUs);
+      if (outcome.action === "write") {
+        // Tarun, 2026-09-30 (merge-contract correction, same day):
+        // "adl-owned entries SELF-HEAL" — when the drift is specifically
+        // an adl-owned scalar restored to adl's own value, name it
+        // explicitly here too, the same way a healed hook is named
+        // ("restored … local changes replaced"), instead of the generic
+        // "modified since deploy" wording.
+        if (outcome.restoredScalars !== undefined && outcome.restoredScalars.length > 0) {
+          for (const scalar of outcome.restoredScalars) {
+            issues.push({
+              severity: "error",
+              path: file.target,
+              reason: `restored adl value: ${scalar.key} = ${JSON.stringify(scalar.value)} (was ${JSON.stringify(scalar.previous)}); run deploy to apply`,
+            });
+          }
+        } else {
+          issues.push({ severity: "error", path: file.target, reason: "deploy-written lean-ctx file was modified since deploy" });
+        }
+      } else if (outcome.action === "conflict") {
+        issues.push({ severity: "error", path: file.target, reason: outcome.reason });
+      }
     }
   }
 

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

@@ -1,9 +1,29 @@
 /**
  * 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.
+ * and .agents/.gitignore from assets/lean-ctx/, per profile.leanCtx. A
+ * fresh write (nothing at the target yet) is still a verbatim byte copy —
+ * no per-surface rendering — reproducing the asset exactly (the asset
+ * itself is a complete BEGIN/END-marked managed block; see
+ * lean-ctx-merge.ts).
+ *
+ * Merge contract (Tarun, 2026-09-29, merge contract; mechanism corrected
+ * by an independent review the same day — supersedes the original "L3,
+ * Tarun 2026-09-28" whole-file-verbatim rule, and this comment's own
+ * earlier per-key/array-entry description, both below): adl owns a single
+ * marked managed block per file and it SELF-HEALS as a whole the moment
+ * its content drifts from the asset. Everything OUTSIDE the markers is the
+ * user's, preserved byte-for-byte, never parsed or rewritten — see
+ * `lean-ctx-merge.ts`'s own header for exactly why (a full-file TOML parse
+ * both rejected valid user TOML and silently discarded a user's entire
+ * file on any parse failure; pure marker-text splicing cannot do either).
+ * `doctorLeanCtx` (doctor.ts) shares the same `resolveLeanCtxWrite`
+ * analysis, so "is this drift" is answered in exactly one place.
+ *
+ * A markerless file the lock already records as adl-written is a one-time
+ * MIGRATION target (wrapped in markers if its known prior content is still
+ * found verbatim; a CONFLICT, left untouched, otherwise) — never silently
+ * discarded. Malformed markers, and a key declared both inside the managed
+ * block and outside it, are conflicts too.
  *
  * 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
@@ -12,11 +32,15 @@
  *
  * 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.
+ * partial-success return value. A resolveLeanCtxWrite CONFLICT is reported
+ * in the ordinary `conflicts` array (like any other), not a throw — the
+ * caller (apps/cli's `adl install`) is the one that turns a non-empty
+ * conflicts list into a loud, non-zero-exit failure.
  */
 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 { resolveConfigTomlWrite, resolveGitignoreWrite, resolveLeanCtxWrite } from "./lean-ctx-merge.js";
 import { leanCtxOwned, readLock, writeLock } from "./lock.js";
 import { type DeployProfile, loadProfile } from "./profile.js";
 
@@ -24,6 +48,8 @@ export interface DeployLeanCtxOptions {
   readonly assetsDir: string; // packages/agent-settings/assets/lean-ctx
   readonly targetRepo: string;
   readonly profile?: DeployProfile;
+  /** Computes the exact same written/unchanged/removed/conflicts result without writing anything (target files, lock, or legacy lock) — independent review, 2026-09-29, finding 6. */
+  readonly dryRun?: boolean;
 }
 
 export interface LeanCtxConflict {
@@ -31,16 +57,26 @@ export interface LeanCtxConflict {
   readonly reason: string;
 }
 
+/** One adl-owned scalar restored to adl's own value this run (2026-09-30, Tarun's merge-contract correction: "adl-owned entries SELF-HEAL" — named explicitly, the same way a healed hook is named, never silent). */
+export interface RestoredLeanCtxScalar {
+  readonly target: string;
+  readonly key: string;
+  readonly value: unknown;
+  readonly previous: unknown;
+}
+
 export interface DeployLeanCtxResult {
   readonly written: readonly string[];
   readonly unchanged: readonly string[];
   readonly removed: readonly string[];
   readonly conflicts: readonly LeanCtxConflict[];
   readonly lockPath: string;
+  readonly restored: readonly RestoredLeanCtxScalar[];
 }
 
 export function deployLeanCtx(options: DeployLeanCtxOptions): DeployLeanCtxResult {
   const { assetsDir, targetRepo } = options;
+  const dryRun = options.dryRun === true;
 
   if (!existsSync(assetsDir) || !statSync(assetsDir).isDirectory()) {
     throw new Error(`agent-settings lean-ctx assets directory not found: ${assetsDir}`);
@@ -61,6 +97,7 @@ export function deployLeanCtx(options: DeployLeanCtxOptions): DeployLeanCtxResul
   const unchanged: string[] = [];
   const removed: string[] = [];
   const conflicts: LeanCtxConflict[] = [];
+  const restored: RestoredLeanCtxScalar[] = [];
   const newLeanCtxEntries: Record<string, boolean> = {};
   const kept: string[] = [];
   const legacyFileRemovals: string[] = [];
@@ -76,6 +113,15 @@ export function deployLeanCtx(options: DeployLeanCtxOptions): DeployLeanCtxResul
     const targetAbs = join(targetRepo, file.target);
     const exists = existsSync(targetAbs);
     let managedByUs = leanCtxOwned(lock, file.target);
+    // Set only when THIS run's legacy hash check (below) is what makes
+    // managedByUs true — that check already verified the file's exact
+    // bytes against the OLD engine's own lock, so unlike leanCtxOwned
+    // (our own lock's unverified "we wrote this at some point" record),
+    // there is no risk of undetected foreign/user content mixed in, and
+    // the file can be overwritten wholesale — the same as a fresh write,
+    // never through resolveLeanCtxWrite's cautious migration path (which
+    // exists precisely for the case this check has already ruled out).
+    let legacyVerifiedClean = false;
 
     if (exists && !managedByUs) {
       const currentContent = readFileSync(targetAbs, "utf8");
@@ -84,26 +130,71 @@ export function deployLeanCtx(options: DeployLeanCtxOptions): DeployLeanCtxResul
       // sha256), so fall back to that comparison for whichever target it is.
       if (legacyFileTakeover(currentContent, legacyDoc, file.target)) {
         managedByUs = true;
+        legacyVerifiedClean = true;
         legacyFileRemovals.push(file.target);
         anyLegacyTakeover = true;
       } else if (legacyTakeoverForGitignore(currentContent, legacyDoc, file.target)) {
         managedByUs = true;
+        legacyVerifiedClean = true;
         legacyGitignoreRemovals.push(file.target);
         anyLegacyTakeover = true;
       }
     }
 
-    if (exists && !managedByUs) {
+    // Independent review, 2026-09-30, finding 6: this guard used to apply
+    // uniformly, so a user-authored .agents/.gitignore with no markers at
+    // all (never written by us — managedByUs false) hit a hard conflict
+    // right here, before resolveGitignoreWrite ever got a chance to run
+    // its own append-not-conflict migration. .gitignore is deliberately
+    // exempted: append is always safe there (a stray, harmless duplicate
+    // ignore line at worst), unlike config.toml/layout.toml where
+    // guessing at a foreign file's structure is not.
+    if (exists && !managedByUs && file.asset !== "gitignore") {
       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) {
+    if (!exists || legacyVerifiedClean) {
+      if (!dryRun) {
+        mkdirSync(dirname(targetAbs), { recursive: true });
+        writeFileSync(targetAbs, content);
+      }
+      written.push(file.target);
+      newLeanCtxEntries[file.target] = true;
+      kept.push(file.target);
+      continue;
+    }
+
+    const currentContent = readFileSync(targetAbs, "utf8");
+    if (currentContent === content) {
+      unchanged.push(file.target);
+      newLeanCtxEntries[file.target] = true;
+      kept.push(file.target);
+      continue;
+    }
+
+    const outcome =
+      file.asset === "config.toml"
+        ? resolveConfigTomlWrite(content, currentContent, managedByUs)
+        : file.asset === "gitignore"
+          ? resolveGitignoreWrite(content, currentContent, managedByUs)
+          : resolveLeanCtxWrite(content, currentContent, managedByUs);
+    if (outcome.action === "conflict") {
+      // Still tracked as ours going forward (a fixed-up file can migrate
+      // or self-heal on a later run) but never written to now.
+      conflicts.push({ target: file.target, reason: outcome.reason });
+      newLeanCtxEntries[file.target] = true;
+      kept.push(file.target);
+      continue;
+    }
+    if (outcome.action === "unchanged") {
       unchanged.push(file.target);
     } else {
-      mkdirSync(dirname(targetAbs), { recursive: true });
-      writeFileSync(targetAbs, content);
+      if (!dryRun) writeFileSync(targetAbs, outcome.text);
       written.push(file.target);
+      for (const scalar of outcome.restoredScalars ?? []) {
+        restored.push({ target: file.target, key: scalar.key, value: scalar.value, previous: scalar.previous });
+      }
     }
     newLeanCtxEntries[file.target] = true;
     kept.push(file.target);
@@ -112,11 +203,11 @@ export function deployLeanCtx(options: DeployLeanCtxOptions): DeployLeanCtxResul
   for (const target of Object.keys(lock.leanCtx)) {
     if (kept.includes(target)) continue;
     const targetAbs = join(targetRepo, target);
-    if (existsSync(targetAbs)) unlinkSync(targetAbs);
+    if (!dryRun && existsSync(targetAbs)) unlinkSync(targetAbs);
     removed.push(target);
   }
 
-  writeLock(targetRepo, { schema: 1, mcp: lock.mcp, agents: lock.agents, leanCtx: newLeanCtxEntries });
+  if (!dryRun) 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`
@@ -124,7 +215,7 @@ export function deployLeanCtx(options: DeployLeanCtxOptions): DeployLeanCtxResul
   // .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) {
+  if (!dryRun && anyLegacyTakeover && legacyDoc !== undefined && legacyLockPath !== undefined) {
     stripLegacyOwnership(legacyDoc, legacyLockPath, { files: legacyFileRemovals, gitignore: legacyGitignoreRemovals });
   }
 
@@ -134,5 +225,6 @@ export function deployLeanCtx(options: DeployLeanCtxOptions): DeployLeanCtxResul
     removed: removed.sort(),
     conflicts: conflicts.sort((a, b) => a.target.localeCompare(b.target)),
     lockPath: join(targetRepo, ".agents/agent-settings.lock.json"),
+    restored,
   };
 }