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

package/packages/fleet/manifest.json

@@ -23,16 +23,33 @@
     "vscode_settings": {
       "enabled": true
     },
+    "repo_maintain": {
+      "branch_max_age_days": 7
+    },
     "scratch_reap": {
       "enabled": true,
       "idle_days": 1,
       "reap_days": 7,
       "remove_worktrees": true
     },
+    "brew_upgrade_exclude": [],
     "protected_tools": ["git", "jq"],
     "git_global_config": {
+      "credential.helper": ["", "{git-credential-manager}"],
+      "credential.https://dev.azure.com.useHttpPath": "true",
       "lfs.ssh://ssh.dev.azure.com/.sshtransfer": "never",
-      "lfs.https://ssh.dev.azure.com/.locksverify": "false"
+      "lfs.https://ssh.dev.azure.com/.locksverify": "false",
+      "push.autoSetupRemote": "true",
+      "push.default": "current",
+      "branch.autoSetupMerge": "simple",
+      "init.defaultBranch": "main",
+      "advice.addEmbeddedRepo": "false",
+      "fetch.prune": "true",
+      "pull.rebase": "false",
+      "rerere.enabled": "true",
+      "merge.conflictStyle": "zdiff3",
+      "diff.algorithm": "histogram",
+      "core.autocrlf": "false"
     }
   },
   "mac": {
@@ -42,7 +59,7 @@
         "ast-grep": {"manager": "brew", "package": "ast-grep", "executable": "ast-grep"},
         "azure-cli": {"manager": "brew", "package": "azure-cli", "executable": "az"},
         "bun": {"manager": "brew", "package": "bun", "executable": "bun"},
-        "adl-embedding": {"manager": "embedding-model", "package": "adl-embedding", "executable": "adl-embedding/model/model.bin", "version": "0.0.1", "source": "minishlab/potion-multilingual-128M", "vocab_limit": 150000, "dim": 256, "reason": "Model data is downloaded and verified into the per-user cache; it is not an Adl code component."},
+        "enact-embedding": {"manager": "embedding-model", "package": "enact-embedding", "executable": "enact-embedding/model/model.bin", "version": "0.0.1", "source": "minishlab/potion-multilingual-128M", "vocab_limit": 150000, "dim": 256, "reason": "Model data is downloaded and verified into the per-user cache; it is not an Adl code component."},
         "code-review-graph": {"manager": "pip", "package": "code-review-graph", "executable": "code-review-graph"},
         "crg": {"manager": "shim", "package": "code-review-graph", "executable": "/usr/local/bin/crg"},
         "curl": {"manager": "brew", "package": "curl", "executable": "curl"},
@@ -56,8 +73,8 @@
         "git": {"manager": "brew", "package": "git", "executable": "git"},
         "jq": {"manager": "brew", "package": "jq", "executable": "jq"},
         "just": {"manager": "brew", "package": "just", "executable": "just"},
-        "lean-ctx": {"manager": "release-archive-latest", "package": "lean-ctx", "executable": "/usr/local/bin/lean-ctx", "repo": "yvgude/lean-ctx", "asset": "lean-ctx-aarch64-apple-darwin.tar.gz", "checksums_asset": "SHA256SUMS", "archive_executable": "lean-ctx"},
         "node": {"manager": "brew", "package": "node", "executable": "node"},
+        "orca": {"manager": "brew", "package": "stablyai/orca/orca", "tap": "stablyai/orca", "executable": "orca", "reason": "Stably's Orca agent runtime (com.stablyai.orca), official tap. Cask auto_updates: reconcile installs when missing and never fights the in-app stable-channel updater. No version pinned here. Linux CLI (orca-ide) has no cask — still undeclared, see plans/GAPS-AND-FINDINGS.md."},
         "ripgrep": {"manager": "brew", "package": "ripgrep", "executable": "rg"},
         "search": {"manager": "shim", "package": "enact-docs-search", "executable": "/usr/local/bin/search"},
         "shellcheck": {"manager": "brew", "package": "shellcheck", "executable": "shellcheck"},
@@ -70,16 +87,17 @@
       "m3": {
         "administrator": "tarunrana",
         "default_agent": "agent-tarun",
+        "git_user": {"name": "Tarun Rana", "email": "tarun.rana@amsterdamdatalabs.com"},
         "home": "/Users/tarunrana",
         "minimum_free_gib": 20,
         "schedule_minute": 5,
-        "repo_location": "/Users/tarunrana/Documents/Repos",
+        "repo_location": "/Users/tarunrana/workspace",
         "brew_upgrade_all": true,
         "surface_clis": [
           {"name": "claude", "manager": "native", "command": "claude", "update_args": ["update"]},
           {"name": "codex", "manager": "brew", "command": "brew", "update_args": ["upgrade", "--cask", "codex"]},
           {"name": "kimi", "manager": "native", "command": "kimi", "update_args": ["upgrade"]},
-          {"name": "opencode", "manager": "native", "command": "opencode", "update_args": ["upgrade"]},
+          {"name": "opencode", "manager": "bun", "package": "opencode-ai", "command": "opencode"},
           {"name": "agent", "manager": "native", "command": "agent", "update_args": ["update"]}
         ],
         "tools": {
@@ -91,16 +109,17 @@
       "m5": {
         "administrator": "ranahome",
         "default_agent": "agent-tarun",
+        "git_user": {"name": "Tarun Rana", "email": "tarun.rana@amsterdamdatalabs.com"},
         "home": "/Users/ranahome",
         "minimum_free_gib": 20,
         "schedule_minute": 35,
-        "repo_location": "/Users/ranahome/Documents",
+        "repo_location": "/Users/ranahome/workspace",
         "brew_upgrade_all": true,
         "surface_clis": [
           {"name": "claude", "manager": "native", "command": "claude", "update_args": ["update"]},
           {"name": "codex", "manager": "brew", "command": "brew", "update_args": ["upgrade", "--cask", "codex"]},
           {"name": "kimi", "manager": "native", "command": "kimi", "update_args": ["upgrade"]},
-          {"name": "opencode", "manager": "native", "command": "opencode", "update_args": ["upgrade"]},
+          {"name": "opencode", "manager": "bun", "package": "opencode-ai", "command": "opencode"},
           {"name": "agent", "manager": "native", "command": "agent", "update_args": ["update"]}
         ],
         "tools": {
@@ -114,12 +133,16 @@
   "linux": {
     "common": {
       "os_upgrade": true,
+      "git_global_config": {
+        "credential.credentialStore": "cache",
+        "credential.cacheOptions": "--timeout 604800"
+      },
       "tools": {
         "agent-vault-cli": {"manager": "release-archive-latest", "package": "agent-vault", "executable": "/usr/local/bin/agent-vault", "repo": "Infisical/agent-vault", "asset": "agent-vault_{version}_linux_amd64.tar.gz", "checksums_asset": "checksums.txt", "archive_executable": "agent-vault"},
         "ast-grep": {"manager": "brew", "package": "ast-grep", "executable": "ast-grep"},
         "azure-cli": {"manager": "brew", "package": "azure-cli", "executable": "az"},
         "bun": {"manager": "brew", "package": "bun", "executable": "bun"},
-        "adl-embedding": {"manager": "embedding-model", "package": "adl-embedding", "executable": "adl-embedding/model/model.bin", "version": "0.0.1", "source": "minishlab/potion-multilingual-128M", "vocab_limit": 150000, "dim": 256, "reason": "Model data is downloaded and verified into the per-user cache; it is not an Adl code component."},
+        "enact-embedding": {"manager": "embedding-model", "package": "enact-embedding", "executable": "enact-embedding/model/model.bin", "version": "0.0.1", "source": "minishlab/potion-multilingual-128M", "vocab_limit": 150000, "dim": 256, "reason": "Model data is downloaded and verified into the per-user cache; it is not an Adl code component."},
         "code-review-graph": {"manager": "pip", "package": "code-review-graph", "executable": "code-review-graph"},
         "crg": {"manager": "shim", "package": "code-review-graph", "executable": "/usr/local/bin/crg"},
         "curl": {"manager": "brew", "package": "curl", "executable": "curl"},
@@ -133,7 +156,6 @@
         "git": {"manager": "brew", "package": "git", "executable": "git"},
         "jq": {"manager": "brew", "package": "jq", "executable": "jq"},
         "just": {"manager": "brew", "package": "just", "executable": "just"},
-        "lean-ctx": {"manager": "release-archive-latest", "package": "lean-ctx", "executable": "/usr/local/bin/lean-ctx", "repo": "yvgude/lean-ctx", "asset": "lean-ctx-x86_64-unknown-linux-gnu.tar.gz", "checksums_asset": "SHA256SUMS", "archive_executable": "lean-ctx"},
         "node": {"manager": "brew", "package": "node", "executable": "node"},
         "ripgrep": {"manager": "brew", "package": "ripgrep", "executable": "rg"},
         "search": {"manager": "shim", "package": "enact-docs-search", "executable": "/usr/local/bin/search"},
@@ -146,6 +168,7 @@
       "hostinger-vps-1": {
         "administrator": "root",
         "default_agent": "agent-tarun",
+        "git_user": {"name": "Tarun Rana", "email": "tarun.rana@amsterdamdatalabs.com"},
         "home": "/root",
         "minimum_free_gib": 25,
         "schedule_minute": 50,
@@ -154,7 +177,7 @@
         "brew_upgrade_all": true,
         "surface_clis": [
           {"name": "claude", "manager": "native", "command": "claude", "update_args": ["update"]},
-          {"name": "opencode", "manager": "native", "command": "opencode", "update_args": ["upgrade"]},
+          {"name": "opencode", "manager": "bun", "package": "opencode-ai", "command": "opencode"},
           {"name": "kimi", "manager": "native", "command": "kimi", "update_args": ["upgrade"]},
           {"name": "codex", "manager": "unknown", "report_only": true, "executable": "/root/codex"}
         ],
@@ -167,6 +190,7 @@
       "strato-vps-1": {
         "administrator": "root",
         "default_agent": "agent-tarun",
+        "git_user": {"name": "Tarun Rana", "email": "tarun.rana@amsterdamdatalabs.com"},
         "home": "/root",
         "minimum_free_gib": 25,
         "schedule_minute": 20,
@@ -174,7 +198,7 @@
         "repo_location": "/root/workspace",
         "brew_upgrade_all": true,
         "surface_clis": [
-          {"name": "opencode", "manager": "npm", "command": "opencode", "update_args": ["upgrade"]},
+          {"name": "opencode", "manager": "bun", "package": "opencode-ai", "command": "opencode"},
           {"name": "kimi", "manager": "native", "command": "kimi", "update_args": ["upgrade"]}
         ],
         "tools": {

package/packages/fleet/manifest.schema.json

@@ -8,7 +8,7 @@
   "properties": {
     "config": {
       "type": "object",
-      "required": ["schema", "repository", "branch", "interval_seconds", "update_policy", "allow_major_updates", "remove_deleted_entries", "global_surface_sweep", "kimi_hooks", "surface_policy", "global_agents", "vscode_settings", "scratch_reap", "protected_tools", "git_global_config"],
+      "required": ["schema", "repository", "branch", "interval_seconds", "update_policy", "allow_major_updates", "remove_deleted_entries", "global_surface_sweep", "kimi_hooks", "surface_policy", "global_agents", "vscode_settings", "repo_maintain", "scratch_reap", "brew_upgrade_exclude", "protected_tools", "git_global_config"],
       "properties": {
         "global_surface_sweep": {
           "type": "object",
@@ -52,6 +52,15 @@
             "enabled": {"const": true}
           }
         },
+        "repo_maintain": {
+          "type": "object",
+          "description": "The 12-hourly repository step (adl maintain). branch_max_age_days: local branches whose tip commit is older than this many days are deleted with a WARN line carrying the tip sha; integration/main/master/develop, the checked-out HEAD and any branch checked out in a worktree are never deleted.",
+          "additionalProperties": false,
+          "required": ["branch_max_age_days"],
+          "properties": {
+            "branch_max_age_days": {"type": "integer", "minimum": 1}
+          }
+        },
         "scratch_reap": {
           "type": "object",
           "description": "Reclaim scratch-worktree disk on the devices that declare scratch_repos. The regenerable-artifact tier is always on; remove_worktrees arms the destructive tier.",
@@ -64,18 +73,40 @@
             "remove_worktrees": {"type": "boolean"}
           }
         },
-        "git_global_config": {
-          "type": "object",
-          "description": "Global git config entries set for the administrator on every host; entries removed from the manifest are unset.",
-          "propertyNames": {"pattern": "^[A-Za-z][A-Za-z0-9-]*\\..+"},
-          "additionalProperties": {"type": "string"}
-        }
+        "brew_upgrade_exclude": {
+          "type": "array",
+          "description": "Homebrew formulae and casks the automatic brew upgrade step never upgrades (an outdated excluded package is logged and skipped). Not a brew pin and not a version pin. git: every Homebrew git upgrade installs an ad-hoc-signed binary at a new Cellar path, which re-prompts the osxkeychain ACL.",
+          "uniqueItems": true,
+          "items": {"type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9@._+/-]*$"}
+        },
+        "git_global_config": {"$ref": "#/$defs/git_global_config"}
       }
     },
     "mac": {"$ref": "#/$defs/platform"},
     "linux": {"$ref": "#/$defs/platform"}
   },
   "$defs": {
+    "git_global_config": {
+      "type": "object",
+      "description": "Global git config entries set for the administrator by bin/git-defaults (reconcile). A value is a string (single-valued key) or an ordered array of strings (multi-valued key, e.g. the empty-reset-then-helper pattern of credential.helper): the key is rewritten with --unset-all then --add in order when the current values differ. Keys not declared here are never touched. The only placeholder is {git-credential-manager}, resolved at run time as the administrator; when it is not installed the key is skipped with a WARN. Platform common may add keys for that platform only.",
+      "propertyNames": {"pattern": "^[A-Za-z][A-Za-z0-9-]*\\..+"},
+      "additionalProperties": {
+        "oneOf": [
+          {"type": "string"},
+          {"type": "array", "minItems": 1, "items": {"type": "string"}}
+        ]
+      }
+    },
+    "git_user": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["name", "email"],
+      "description": "user.name and user.email set in the administrator's global git config on this device. Every device carries the same identity so the human git setup is identical on every host.",
+      "properties": {
+        "name": {"type": "string", "minLength": 1},
+        "email": {"type": "string", "minLength": 1}
+      }
+    },
     "tool": {
       "type": "object",
       "additionalProperties": false,
@@ -89,6 +120,7 @@
         "sha256": {"type": "string", "pattern": "^[0-9a-f]{64}$"},
         "archive_executable": {"type": "string", "pattern": "^[^/][^\\n]*$"},
         "repo": {"type": "string", "pattern": "^[^/\\s]+/[^/\\s]+$"},
+        "tap": {"type": "string", "pattern": "^[^/\\s]+/[^/\\s]+$", "description": "brew only: tap (owner/repo) to ensure is tapped before install/upgrade — required for fully-qualified package names like stablyai/orca/orca, which Homebrew will not auto-tap. Declaring it also grants item-level brew trust (`brew trust --formula|--cask <package>`) per Homebrew ≥6 tap trust; the whole tap is never trusted."},
         "asset": {"type": "string", "pattern": "^[^/][^\\n]*$"},
         "checksums_asset": {"type": "string", "pattern": "^[^/][^\\n]*$"},
         "source": {"type": "string", "pattern": "^[^/][^\\n]*$"},
@@ -151,7 +183,12 @@
       "required": ["name", "manager"],
       "properties": {
         "name": {"type": "string", "minLength": 1},
-        "manager": {"enum": ["native", "npm", "brew", "unknown"]},
+        "manager": {"enum": ["native", "npm", "brew", "bun", "unknown"]},
+        "package": {
+          "type": "string",
+          "pattern": "^(@[a-z0-9][a-z0-9._-]*/)?[a-z0-9][a-z0-9._-]*$",
+          "description": "manager=bun only: the bare npm registry package, installed and updated with `bun add -g <package>@latest` as the device administrator. Never a version spec; versions are never pinned."
+        },
         "command": {"type": "string", "minLength": 1, "pattern": "^[^/]+$"},
         "executable": {"type": "string", "pattern": "^/"},
         "update_args": {"type": "array", "minItems": 1, "items": {"type": "string", "minLength": 1}},
@@ -161,7 +198,20 @@
         {
           "if": {"properties": {"report_only": {"const": true}}, "required": ["report_only"]},
           "then": {"required": ["executable"]},
-          "else": {"required": ["command", "update_args"]}
+          "else": {"required": ["command"]}
+        },
+        {
+          "if": {"properties": {"manager": {"const": "bun"}}, "required": ["manager"]},
+          "then": {
+            "required": ["package", "command"],
+            "properties": {"report_only": {"const": false}},
+            "not": {"required": ["update_args"]}
+          },
+          "else": {
+            "not": {"required": ["package"]},
+            "if": {"properties": {"report_only": {"const": true}}, "required": ["report_only"]},
+            "else": {"required": ["update_args"]}
+          }
         },
         {
           "if": {"properties": {"manager": {"const": "brew"}}, "required": ["manager"]},
@@ -194,6 +244,7 @@
           "required": ["tools"],
           "properties": {
             "os_upgrade": {"type": "boolean"},
+            "git_global_config": {"$ref": "#/$defs/git_global_config"},
             "tools": {"$ref": "#/$defs/tools"}
           }
         },
@@ -202,7 +253,7 @@
           "additionalProperties": {
             "type": "object",
             "additionalProperties": false,
-            "required": ["administrator", "default_agent", "home", "minimum_free_gib", "schedule_minute", "tools"],
+            "required": ["administrator", "default_agent", "git_user", "home", "minimum_free_gib", "schedule_minute", "tools"],
             "properties": {
               "administrator": {"type": "string", "minLength": 1},
               "default_agent": {
@@ -210,6 +261,7 @@
                 "pattern": "^agent-[a-z0-9-]+$",
                 "description": "The adl identity a plain `claude`/`codex` session (no `adl run --as`) acts as on this device, and the identity host automation (sync-and-reconcile, scratch-reap) uses via git-ado. Written by reconcile to the machine's single default-agent file (docs/architecture/cli-design.md, 2026-09-27 decisions)."
               },
+              "git_user": {"$ref": "#/$defs/git_user"},
               "home": {"type": "string", "pattern": "^/"},
               "minimum_free_gib": {"type": "integer", "minimum": 1},
               "schedule_minute": {"type": "integer", "minimum": 0, "maximum": 59},

package/packages/fleet/src/default-agent-file.ts

@@ -22,9 +22,9 @@
  * path computation every consumer of the READ side needs too
  * (`defaultAgentFilePath`). The read itself lives in ONE place,
  * `packages/azdo/src/lib/agent-identity.ts`'s `readDefaultAgentFile` /
- * `resolveAgentIdentity` (STATUS.md 12p, W1) —
- * every reader in this repo, including this package's own scratch-reap.ts,
- * goes through that module rather than duplicating the read here.
+ * `resolveAgentIdentity` — every reader in this repo, including this
+ * package's own scratch-reap.ts, goes through that module rather than
+ * duplicating the read here.
  *
  * `root` is an injectable filesystem root so tests can point every path here
  * at a disposable directory instead of the real system path — a test must

package/packages/fleet/src/install-adl-package.ts

@@ -10,16 +10,19 @@ import {
   readlinkSync,
   renameSync,
   rmSync,
+  statSync,
   symlinkSync,
 } from 'node:fs'
 import { dirname, isAbsolute, join, relative, resolve, sep } from 'node:path'
 
 // Exported so tests can pin this list against the packages that actually
-// import cross-package by relative path (STATUS.md 12p, finding C1) — a
-// package added to those imports but not here breaks every managed repo's
-// git hooks with "Cannot find module" the next time reconcile projects this
-// payload.
-export const payloadDirectories = ['packages/agent-skills', 'packages/repo-controls', 'packages/agent-hooks', 'packages/azdo']
+// import cross-package by relative path — a package added to those imports
+// but not here breaks every managed repo's git hooks with "Cannot find module"
+// the next time reconcile projects this payload.
+// Every package apps/cli reads from /usr/local/libexec/adl (hooks.ts, skills.ts, settings.ts,
+// repo-controls.ts: DEFAULT_LIBEXEC_DIR) plus azdo, which they import by relative path.
+// install-adl-package.test.ts pins both against the real sources.
+export const payloadDirectories = ['packages/agent-skills', 'packages/repo-controls', 'packages/agent-hooks', 'packages/agent-settings', 'packages/azdo']
 const payloadScripts = ['bin/git', 'bin/git-ado']
 const requiredFiles = [
   'bin/reconcile',
@@ -27,12 +30,13 @@ const requiredFiles = [
   'packages/agent-skills/dist/index.js',
   'packages/repo-controls/bin/adl-repo-controls.ts',
   'packages/agent-hooks/src/log/writer.ts',
+  'packages/agent-settings/deploy-profile.json',
   // repo-controls, fleet and agent-hooks each import THE one Azure DevOps
   // identity resolver/minter by relative path (`../../azdo/src/lib/...`,
   // `../../../../azdo/src/lib/...`) rather than as a package dependency, so
   // this directory must ship as a sibling of theirs under packages/ or every
   // managed repo's git hooks break with "Cannot find module" the next time
-  // reconcile projects this payload (STATUS.md 12p, finding C1).
+  // reconcile projects this payload. install-adl-package.test.ts pins this.
   'packages/azdo/src/lib/agent-identity.ts',
   'packages/azdo/src/lib/agent-token.ts',
 ]
@@ -41,6 +45,15 @@ const managedScriptMarkers = ['# Managed by adl global-tools.', '# Managed by En
 export interface InstallAdlPackageOptions {
   packageRoot: string
   systemRoot?: string
+  /**
+   * Package mode: link /usr/local/bin/adl to THIS package's own bin/adl. Hosts
+   * install the package with bun, which links `adl` into the owner's ~/.bun/bin
+   * only, yet bin/git-ado's `adl id token`, the MCP server command, the managed
+   * surface hooks and GUI-launched agents all run a bare `adl` without that
+   * shell PATH. Checkout mode (a developer build, no compiled bin/adl in the
+   * tree) leaves it off.
+   */
+  linkAdl?: boolean
 }
 
 function isPathInside(parent: string, candidate: string): boolean {
@@ -48,7 +61,7 @@ function isPathInside(parent: string, candidate: string): boolean {
   return pathFromParent === '' || (pathFromParent !== '..' && !pathFromParent.startsWith(`..${sep}`) && !isAbsolute(pathFromParent))
 }
 
-function assertPackageRoot(packageRoot: string): string {
+function assertPackageRoot(packageRoot: string, linkAdl: boolean): string {
   const root = realpathSync(packageRoot)
   const rootStat = lstatSync(root)
   if (!rootStat.isDirectory()) throw new Error(`Adl platform package root is not a directory: ${packageRoot}`)
@@ -64,13 +77,20 @@ function assertPackageRoot(packageRoot: string): string {
     }
     if (!stat.isFile()) throw new Error(`required package file is not a regular file: ${relative}`)
     if (payloadScripts.includes(relative)) {
-      if ((stat.mode & 0o111) === 0) throw new Error(`package script must be executable: ${relative}`)
+      // No exec-bit requirement: bun leaves every shipped file but the `bin`
+      // targets 0644; replaceManagedScript installs the copy 0755.
       const firstLines = readFileSync(source, 'utf8').split('\n', 3)
       if (!managedScriptMarkers.some((marker) => firstLines.includes(marker))) {
         throw new Error(`package script is missing its managed marker: ${relative}`)
       }
     }
   }
+  if (linkAdl) {
+    const adl = join(root, 'bin/adl')
+    if (!existsSync(adl) || !lstatSync(adl).isFile() || (statSync(adl).mode & 0o111) === 0) {
+      throw new Error('package adl must be an executable file: bin/adl')
+    }
+  }
   return root
 }
 
@@ -137,9 +157,45 @@ function replaceManagedScript(source: string, target: string): void {
   }
 }
 
+// A link this function made points into some install's platform package. Anything else at the
+// path is someone else's adl and is never replaced silently.
+const managedAdlLinkTarget = /\/adl-agent-control-[a-z0-9]+-[a-z0-9]+\/bin\/adl$/
+
+function adlLinkStatus(link: string, source: string): 'current' | 'replace' | 'create' {
+  if (!lstatExists(link)) return 'create'
+  if (!lstatSync(link).isSymbolicLink()) {
+    const date = new Date().toISOString().slice(0, 10).replaceAll('-', '')
+    throw new Error(
+      `refusing to replace ${link}: a different adl (a legacy compiled one from before the package existed) shadows this package. Move it aside, never delete it, then run this again: sudo mv ${link} ${link}.legacy-${date}`,
+    )
+  }
+  const current = readlinkTarget(link)
+  if (current === source) return 'current'
+  if (!managedAdlLinkTarget.test(current)) throw new Error(`refusing to replace unmanaged symlink: ${link} -> ${current}`)
+  return 'replace'
+}
+
+function linkAdlToPackage(packageRoot: string, systemRoot: string, status: 'current' | 'replace' | 'create'): void {
+  if (status === 'current') return
+  const link = join(systemRoot, 'usr/local/bin/adl')
+  mkdirSync(dirname(link), { recursive: true })
+  const tempDirectory = mkdtempSync(join(dirname(link), '.adl-package-link-'))
+  const temp = join(tempDirectory, 'adl')
+  try {
+    symlinkSync(join(packageRoot, 'bin/adl'), temp)
+    renameSync(temp, link)
+  } finally {
+    rmSync(tempDirectory, { recursive: true, force: true })
+  }
+}
+
 export function installAdlPackage(options: InstallAdlPackageOptions): void {
-  const packageRoot = assertPackageRoot(options.packageRoot)
+  const packageRoot = assertPackageRoot(options.packageRoot, options.linkAdl === true)
   const systemRoot = resolve(options.systemRoot ?? '/')
+  // Refusals come before any replacement, so a shadowing legacy adl leaves the host untouched.
+  const adlLink = options.linkAdl
+    ? adlLinkStatus(join(systemRoot, 'usr/local/bin/adl'), join(packageRoot, 'bin/adl'))
+    : undefined
   for (const relative of payloadDirectories) {
     replacePayloadSymlink(
       join(packageRoot, relative),
@@ -153,23 +209,25 @@ export function installAdlPackage(options: InstallAdlPackageOptions): void {
       join(systemRoot, 'usr/local/bin', relative.split('/').at(-1)!),
     )
   }
+  if (adlLink !== undefined) linkAdlToPackage(packageRoot, systemRoot, adlLink)
 }
 
 if (import.meta.main) {
   const args = process.argv.slice(2)
-  if (args[0] !== 'install') throw new Error('usage: install-adl-package.ts install --package-root PATH [--system-root PATH]')
+  if (args[0] !== 'install') throw new Error('usage: install-adl-package.ts install --package-root PATH [--system-root PATH] [--link-adl]')
   let packageRoot = ''
   let systemRoot = '/'
-  for (let index = 1; index < args.length; index += 2) {
+  let linkAdl = false
+  for (let index = 1; index < args.length; index += 1) {
     const option = args[index]
-    const value = args[index + 1] ?? ''
-    if (option === '--package-root') packageRoot = value
-    else if (option === '--system-root') systemRoot = value
+    if (option === '--link-adl') linkAdl = true
+    else if (option === '--package-root') packageRoot = args[++index] ?? ''
+    else if (option === '--system-root') systemRoot = args[++index] ?? ''
     else throw new Error(`unknown option: ${option}`)
   }
   if (!packageRoot) throw new Error('missing --package-root')
   try {
-    installAdlPackage({ packageRoot, systemRoot })
+    installAdlPackage({ packageRoot, systemRoot, linkAdl })
     console.log(`projected Adl package payload from ${packageRoot}`)
   } catch (error) {
     console.error(error instanceof Error ? error.message : String(error))

package/packages/fleet/src/install-embedding-model.ts

@@ -1,7 +1,7 @@
 /**
- * Global installer for the `adl-embedding` static (Model2Vec) embedding
+ * Global installer for the `enact-embedding` static (Model2Vec) embedding
  * artifact that `adl hook`'s skill-match hook loads from
- * `${XDG_CACHE_HOME:-$HOME/.cache}/adl-embedding/model/` (falling back to
+ * `${XDG_CACHE_HOME:-$HOME/.cache}/enact-embedding/model/` (falling back to
  * BM25 when absent) — see enact-repo-controls-m5's
  * `src/hooks/user-prompt-submit/vector.ts`, which this script's output must
  * satisfy exactly: `model.bin`, `tokenizer.json`, `tokenizer_config.json`,
@@ -76,7 +76,7 @@ const UPSTREAM_FILE_NAMES = ['model.safetensors', 'tokenizer.json', 'tokenizer_c
 export function resolveArtifactDir(env: Readonly<Record<string, string | undefined>>): string {
   const xdgCacheHome = env.XDG_CACHE_HOME
   const base = xdgCacheHome && xdgCacheHome.trim() !== '' ? xdgCacheHome : join(requireHome(env), '.cache')
-  return join(base, 'adl-embedding', 'model')
+  return join(base, 'enact-embedding', 'model')
 }
 
 function requireHome(env: Readonly<Record<string, string | undefined>>): string {
@@ -255,7 +255,7 @@ export interface EmbeddingModelDeps {
   readonly downloadFile: (url: string, dest: string) => void
 }
 
-export const defaultDeps: EmbeddingModelDeps = {
+const defaultDeps: EmbeddingModelDeps = {
   resolveLatestRevision: defaultResolveLatestRevision,
   fetchPathsInfo: defaultFetchPathsInfo,
   downloadFile: defaultDownloadFile,
@@ -279,13 +279,13 @@ export async function install(spec: EmbeddingModelSpec, artifactDir: string, dep
   const revision = await deps.resolveLatestRevision(spec.source)
 
   if (isInstalledAtRevision(artifactDir, revision)) {
-    console.log(`adl-embedding: already installed and verified at ${artifactDir} (${spec.source}@${revision})`)
+    console.log(`enact-embedding: already installed and verified at ${artifactDir} (${spec.source}@${revision})`)
     return
   }
 
-  const work = mkdtempSync(join(tmpdir(), 'adl-embedding-install-'))
+  const work = mkdtempSync(join(tmpdir(), 'enact-embedding-install-'))
   try {
-    console.log(`adl-embedding: installing ${spec.package} ${spec.version} (${spec.source}@${revision})`)
+    console.log(`enact-embedding: installing ${spec.package} ${spec.version} (${spec.source}@${revision})`)
 
     const pathsInfo = await deps.fetchPathsInfo(spec.source, revision, UPSTREAM_FILE_NAMES)
     const downloadedPaths: Record<string, string> = {}
@@ -345,7 +345,7 @@ export async function install(spec: EmbeddingModelSpec, artifactDir: string, dep
       writeFileSync(staged, readFileSync(join(outDir, name)))
       renameSync(staged, join(artifactDir, name))
     }
-    console.log(`adl-embedding: installed and verified at ${artifactDir} (${spec.source}@${revision})`)
+    console.log(`enact-embedding: installed and verified at ${artifactDir} (${spec.source}@${revision})`)
   } finally {
     rmSync(work, { recursive: true, force: true })
   }
@@ -353,18 +353,18 @@ export async function install(spec: EmbeddingModelSpec, artifactDir: string, dep
 
 export function uninstall(artifactDir: string): void {
   if (!existsSync(artifactDir)) {
-    console.log(`adl-embedding: nothing to remove at ${artifactDir}`)
+    console.log(`enact-embedding: nothing to remove at ${artifactDir}`)
     return
   }
   rmSync(artifactDir, { recursive: true, force: true })
-  console.log(`adl-embedding: removed ${artifactDir}`)
+  console.log(`enact-embedding: removed ${artifactDir}`)
 }
 
 function usage(): never {
   throw new Error('usage: install-embedding-model <install|check|uninstall> --spec JSON [--home ABSOLUTE_PATH]')
 }
 
-export async function main(argv: readonly string[]): Promise<void> {
+async function main(argv: readonly string[]): Promise<void> {
   const mode = argv[0]
   if (mode !== 'install' && mode !== 'check' && mode !== 'uninstall') usage()
 
@@ -394,8 +394,8 @@ export async function main(argv: readonly string[]): Promise<void> {
     const ok = isInstalledAtRevision(artifactDir, revision)
     console.log(
       ok
-        ? `adl-embedding: installed and verified at ${artifactDir} (${spec.source}@${revision})`
-        : `adl-embedding: NOT installed at latest revision ${revision} at ${artifactDir}`,
+        ? `enact-embedding: installed and verified at ${artifactDir} (${spec.source}@${revision})`
+        : `enact-embedding: NOT installed at latest revision ${revision} at ${artifactDir}`,
     )
     process.exitCode = ok ? 0 : 1
     return

package/packages/fleet/src/managed-settings.ts

@@ -1,6 +1,6 @@
 /**
- * Render and install the managed baseline hook artifacts (adl items 10/17,
- * `docs/architecture/cli-design.md` §2/§3) from the committed templates in
+ * Render and install the managed baseline hook artifacts
+ * (`docs/architecture/cli-design.md` §2/§3) from the committed templates in
  * `packages/agent-settings/managed/` onto the real, per-platform system
  * paths -- the "fleet installation" that directory's own README used to say
  * was a separate, later item. It is this reconcile pass.
@@ -70,7 +70,7 @@
  *          best-effort, never depended on) -- the actual, CONFIRMED
  *          enforcement is `allow_managed_hooks_only` above plus the
  *          fail-closed managed baseline hook
- *          (`adl.session-required-for-writes`): a missing or overridden
+ *          (`adl.run-required-for-writes`): a missing or overridden
  *          `ADL_AGENT_ID_AGENT` denies Azure DevOps writes for that session,
  *          exactly like a plain `codex` with no `adl run` today -- it never
  *          grants anything by being absent. Installed at
@@ -92,8 +92,8 @@ import { DEFAULT_AGENT_PATTERN } from './default-agent-file.ts'
 export type FleetPlatform = 'mac' | 'linux'
 
 const MANAGED_DIR = fileURLToPath(new URL('../../agent-settings/managed', import.meta.url))
-export const CLAUDE_TEMPLATE_PATH = join(MANAGED_DIR, 'claude-managed-settings.json')
-export const CODEX_REQUIREMENTS_TEMPLATE_PATH = join(MANAGED_DIR, 'codex-requirements.toml')
+const CLAUDE_TEMPLATE_PATH = join(MANAGED_DIR, 'claude-managed-settings.json')
+const CODEX_REQUIREMENTS_TEMPLATE_PATH = join(MANAGED_DIR, 'codex-requirements.toml')
 
 export function claudeManagedSettingsPath(platform: FleetPlatform, root = ''): string {
   switch (platform) {
@@ -153,7 +153,7 @@ export function renderCodexManagedConfig(agent: string): string {
 # https://developers.openai.com/codex/config-reference. Deployed anyway
 # because it is harmless if ignored or overridden: unsetting
 # ADL_AGENT_ID_AGENT here grants nothing -- the managed baseline hook
-# (adl.session-required-for-writes, CONFIRMED enforced from
+# (adl.run-required-for-writes, CONFIRMED enforced from
 # allow_managed_hooks_only in requirements.toml in this same directory) then
 # denies Azure DevOps writes for that session, fail-closed, exactly like a
 # plain \`codex\` with no \`adl run\` today. That hook is the real backstop,
@@ -168,7 +168,7 @@ set = { ADL_AGENT_ID_AGENT = "${agent}" }
 `
 }
 
-export interface FileWriteResult {
+interface FileWriteResult {
   readonly path: string
   readonly changed: boolean
 }