@amsterdamdatalabs/adl-agent-control-linux-x64 0.1.29 → 0.1.32

package/bin/adl

@@ -1,4 +1,4 @@
 [diffend] Oversized file quarantined before diffing.
 name: package/bin/adl
-size: 82912736 bytes
-sha256: 2b01ff7bfab3461ee9bc678cd6c7660691505b0bebd617f922de743b0187e197
+size: 82920928 bytes
+sha256: f63a82963b12de92399625846d611dc9a469ceec692522e95fbae7ff3f702acb

package/bin/health-check

@@ -17,8 +17,8 @@ fi
 
 case "$device" in
   m5)
-    launchctl print system/vsts.agent.amsterdamdatalabs.Default.mac-m5-ci 2>/dev/null |
-      grep -q 'state = running'
+    runner_state="$(launchctl print system/vsts.agent.amsterdamdatalabs.Default.mac-m5-ci 2>/dev/null)"
+    [[ "$runner_state" == *'state = running'* ]]
     ;;
   hostinger-vps-1)
     # One unit per call: `systemctl is-active` given several units exits 0 when at

package/bin/reconcile

@@ -368,7 +368,26 @@ SURFACE_UPDATE_TIMEOUT_SECONDS="${RECONCILE_SURFACE_UPDATE_TIMEOUT_SECONDS:-300}
 # brew's output for a cask whose upgrade needed sudo but was not allowed to ask: Homebrew refusing
 # ("sudo is disabled by HOMEBREW_NO_SUDO."), or sudo -n failing fast. It never blocks.
 brew_output_needs_password() {
-  grep -Eiq 'sudo is disabled by HOMEBREW_NO_SUDO|sudo: .*(password|terminal|tty|askpass)|^Password:' <<<"$1"
+  local lowered="${1,,}" nl=$'\n'
+  local sudo_re="sudo: [^${nl}]*(password|terminal|tty|askpass)"
+  [[ "$lowered" == *'sudo is disabled by homebrew_no_sudo'* ]] && return 0
+  [[ "$lowered" =~ $sudo_re ]] && return 0
+  [[ "$lowered" == 'password:'* || "$lowered" == *"${nl}password:"* ]]
+}
+
+# Whole-line membership of $1 in newline list $2, pure bash (runs before ripgrep exists).
+list_has_line() {
+  local nl=$'\n'
+  [[ "${nl}${2}${nl}" == *"${nl}${1}${nl}"* ]]
+}
+
+# True when file $2 has a line exactly equal to $1. Pure bash, same reason.
+file_has_line() {
+  local line
+  while IFS= read -r line || [[ -n "$line" ]]; do
+    [[ "$line" == "$1" ]] && return 0
+  done <"$2"
+  return 1
 }
 
 # Upgrades the outdated Homebrew formulae and casks, from ONE `brew outdated --json=v2` (the
@@ -430,7 +449,7 @@ run_brew_upgrade_all_body() {
   excluded_names="$(jq -r '(.config.brew_upgrade_exclude // [])[]' "$manifest")"
   while IFS=$'\t' read -r kind name installed available; do
     [[ -n "$name" ]] || continue
-    if [[ -n "$excluded_names" ]] && grep -Fxq -- "$name" <<<"$excluded_names"; then
+    if [[ -n "$excluded_names" ]] && list_has_line "$name" "$excluded_names"; then
       echo "global-tools: brew upgrade skips excluded: $name ($installed → $available)"
       skipped=$((skipped + 1))
       continue
@@ -878,12 +897,12 @@ install_surface_policy_file() {
 # "v" belongs to "dev"/"rev", not a version prefix -- silently matched and
 # would have skipped a real upgrade). The RIGHT boundary is a space or a
 # string end and never accepts "v", or "0.39.3" would incorrectly match
-# inside "0.39.30". Dots in the version are escaped so they match literally,
-# not "any character," in the regex below.
+# inside "0.39.30". The match is a literal, space-bounded glob (no regex), so
+# dots in the version are never "any character."
 release_archive_version_matches() {
-  local version_line="$1" version="$2" escaped
-  escaped="$(printf '%s' "$version" | sed 's/[.[\*^$()+?{}|]/\\&/g')"
-  grep -Eq "(^| )v?${escaped}( |\$)" <<<"$version_line"
+  local version_line="$1" version="$2" padded
+  padded=" ${version_line//$'\n'/ } "
+  [[ "$padded" == *" $version "* || "$padded" == *" v$version "* ]]
 }
 
 # Resolves the release tag GitHub's own "latest" redirect currently points
@@ -1040,7 +1059,7 @@ install_one_tool() {
         }
       fi
       if [[ "$rc" -eq 0 && -n "$tap" && "$mode" == apply ]]; then
-        brew_query tap | grep -Fqx "$tap" || run_brew tap "$tap" || {
+        list_has_line "$tap" "$(brew_query tap)" || run_brew tap "$tap" || {
           echo "ERROR $tool_id: brew tap $tap failed" >&2
           rc=1
         }
@@ -1070,7 +1089,7 @@ install_one_tool() {
         # whole-tap grant ("Trusted taps: owner/repo") can never satisfy the
         # item check.
         if [[ "$rc" -eq 0 ]]; then
-          brew_query trust | awk '{$1=$1};1' | grep -Fqx "$package" || run_brew trust "--$trust_kind" "$package" || {
+          list_has_line "$package" "$(brew_query trust | awk '{$1=$1};1')" || run_brew trust "--$trust_kind" "$package" || {
             echo "ERROR $tool_id: brew trust --$trust_kind $package failed" >&2
             rc=1
           }
@@ -1426,8 +1445,8 @@ managed_repo_script_legacy_marker='# Managed by Enact global-tools.'
 is_managed_repo_script() {
   local executable="$1"
   [[ -f "$executable" && ! -L "$executable" ]] || return 1
-  grep -Fqx "$managed_repo_script_marker" "$executable" ||
-    grep -Fqx "$managed_repo_script_legacy_marker" "$executable"
+  file_has_line "$managed_repo_script_marker" "$executable" ||
+    file_has_line "$managed_repo_script_legacy_marker" "$executable"
 }
 
 atomic_install_managed_repo_script() {
@@ -2094,20 +2113,21 @@ run_surface_update() {
 # update path, native/npm and Homebrew-cask alike, rather than one
 # per-surface parser.
 #
-# Never `cmd1 | cmd2` piped straight into the caller's assignment: see the
-# inner `if var=$(grep ...); then` below (not `grep | sed`) for why -- under
-# this file's `set -euo pipefail`, grep's ordinary "no match" exit would
-# otherwise abort the run on every surface that DIDN'T report an error. An
-# `if`-tested command is exempt from that abort by design; the function's
-# OWN exit status is therefore never meaningful (an `if` with no `else`
-# always returns 0), so callers check the printed string's emptiness, never
-# this function's exit status.
+# Pure bash (no ripgrep yet); callers check the printed string, never the exit status.
 surface_update_error_reason() {
   local output="$1" plain line
   # LC_ALL=C: the strip is bytewise. Under en_US.UTF-8 glibc resolves [@-~]
   # by collation, so the escape's final letter would never match.
   plain="$(LC_ALL=C sed -E $'s/\x1b\\[[0-9;]*[@-~]//g' <<<"$output")"
-  if line="$(grep -m1 -iE '^[[:space:]]*(✖[[:space:]]*)?error:' <<<"$plain")"; then
+  local error_re='^[[:space:]]*(✖[[:space:]]*)?[eE][rR][rR][oO][rR]:' candidate
+  line=""
+  while IFS= read -r candidate; do
+    if [[ "$candidate" =~ $error_re ]]; then
+      line="$candidate"
+      break
+    fi
+  done <<<"$plain"
+  if [[ -n "$line" ]]; then
     sed -E 's/^[[:space:]]*(✖[[:space:]]*)?[eE][rR][rR][oO][rR]:[[:space:]]*//' <<<"$line"
   fi
 }
@@ -2309,7 +2329,7 @@ reconcile_one_surface_cli() {
     # the per-tool brew path in install_one_tool; the kind is certain here).
     # Bare names are core casks, trusted by default -- no grant.
     if [[ "$name" == */* ]]; then
-      brew_query trust | awk '{$1=$1};1' | grep -Fqx "$name" || run_brew trust --cask "$name" || {
+      list_has_line "$name" "$(brew_query trust | awk '{$1=$1};1')" || run_brew trust --cask "$name" || {
         echo "ERROR surface $name: brew trust --cask $name failed" >&2
         return 1
       }

package/bin/setup

@@ -112,7 +112,8 @@ if [[ "$fleet_host_platform" == linux ]]; then
     "$brew_prefix/Homebrew" \
     "$brew_prefix/Homebrew/Library/Taps/adl-tan-theta/homebrew-tap"; do
     [[ -d "$brew_repo/.git" ]] || continue
-    if ! (cd /tmp && sudo -u "$brew_owner" -H git config --global --get-all safe.directory 2>/dev/null) | grep -Fxq "$brew_repo"; then
+    safe_dirs="$(cd /tmp && sudo -u "$brew_owner" -H git config --global --get-all safe.directory 2>/dev/null)" || safe_dirs=""
+    if [[ $'\n'"$safe_dirs"$'\n' != *$'\n'"$brew_repo"$'\n'* ]]; then
       (cd /tmp && sudo -u "$brew_owner" -H git config --global --add safe.directory "$brew_repo")
     fi
   done

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@amsterdamdatalabs/adl-agent-control-linux-x64",
-  "version": "0.1.29",
+  "version": "0.1.32",
   "description": "adl CLI binary for linux/x64 (agent identity + Azure DevOps front door — see docs/architecture/cli-design.md)",
   "license": "UNLICENSED",
   "os": [

package/packages/agent-hooks/README.md

@@ -78,14 +78,16 @@ adl hook doctor [--repo <path>]
 In a managed repo doctor also prints both hook-log paths with their row
 counts and echoes the last 5 deny-log rows.
 
-## Hook logs: `.adl/logs/hooks.log` and `.adl/logs/hooks-deny.log`
+## Hook logs: `.adl/logs/agent-hooks/`
 
 Written only for a managed repo with hooks enabled (same gate as every hook;
 unmanaged or `[hooks] enabled = false` writes nothing). Only agent hook
 invocations are logged. Logging is strictly best-effort: the directory is
 created lazily with the first row, one append per file per invocation, and a
-write failure (read-only dir, full disk) never changes a hook's stdout,
-stderr, or exit code. Environment variables are never logged.
+write failure (read-only dir, full disk) never changes a hook's stdout
+or exit code; it prints one `adl agent-hooks: could not write log row: ...`
+line to stderr, so a lost row is never silent (git hooks print the same with
+the prefix `adl repo controls:`). Environment variables are never logged.
 
 This is a hard cut: legacy `.agents/hooks/hooks.log` and
 `.agents/hooks/hooks-activity.log` files are neither read, copied, appended,
@@ -94,7 +96,7 @@ CSV files this format replaces (docs/architecture/cli-design.md §5a, Tarun 2026
 `.enact/logs/` is no longer written at all.
 
 Both files are **JSON Lines** — one JSON object per line, written by the one
-shared logger every `.adl/logs/*.log` file uses
+shared logger every `.adl/logs/<owner>/*.log` file uses
 (`src/log/writer.ts`'s `writeLogEntry`, moved here from `apps/cli` so
 agent-hooks "holds logs"; `apps/cli/src/log.ts` re-exports it unchanged).
 Fields are written in a fixed order and an absent field is OMITTED, never
@@ -104,10 +106,60 @@ characters (`...<truncated>`, unchanged from the CSV era) and then redacted
 (`redact()`: bearer tokens, `Authorization:` headers, JWTs, `*_TOKEN=`/
 `*_SECRET=`/… name=value pairs, `--password`-style flags, URL userinfo).
 Files live at `0600`, the directory at `0700`; a file that would exceed 10 MiB
-is rotated to `.1`…`.5`, dropping `.5`.
-
-**`hooks.log`** — one row per hook invocation of every kind (allow, deny,
-route). **`hooks-deny.log`** — the same row, additionally, only when the
+is rotated to `.1`…`.5`, dropping `.5`, under a per-file lock so concurrent
+hook processes normally rotate once (see "Rotation-race hardening" for the
+residual cases).
+
+Bug 600 (Tarun, 2026-10-08): `.adl/logs` has one folder per owner. This
+package owns `agent-hooks/` and writes nothing else; git hooks write
+`git-hooks/`, `adl run` writes `agents/`. The old top-level `hooks.log`,
+`hooks-deny.log` and `crg-update.log` are never migrated, moved or deleted —
+they are left where they are. `agent-hooks/crg-update.log` is the raw stdout+stderr
+of the detached `code-review-graph update` and rotates by the same rule before
+each spawn.
+
+Rotation race (Bug 600): on 2026-10-08 Enact's logs showed `hooks.log.1` = 580 B
+and `hooks.log.2` = 10 MB. Two hook processes both saw size > max; the first
+rotated the full file to `.1` and appended, the second (stale size check)
+rotated again, pushing the full file to `.2`. The per-file lock fixes this:
+the size is re-read inside the lock, so a writer that lost the race finds the
+file fresh and does not rotate again. Rotation is idempotent: the live file is
+renamed aside first (a missing file means someone else already rotated, so it
+stops), then the backups shift. An empty live file is never rotated, so one
+row larger than the maximum cannot push an empty file into `.1`.
+`crg-update.log` was observed unbounded (2.8 MB, no rotation) before it joined
+the same rule.
+
+Rotation-race hardening (Bug 600 verifiers, 2026-10-08): every pre-write stat
+and open tolerates the live log being renamed away by another writer's
+rotation (ENOENT means "fresh file": the append recreates it at 0600), so a
+writer that does not itself rotate never loses its row. The lock file carries
+a `pid-random` token. A stale lock (older than 5 s) is broken by unlinking it
+only if it still holds the token we observed; a holder removes the lock only
+if it still holds its own token. This is read-compare-unlink, so a narrow race
+remains where two writers can briefly both hold the lock. No step of rotation
+overwrites a backup: shifting and the final placement into `.1` are hard-link
+then unlink, a slot that is already taken is shifted again (at most 5 attempts,
+then rotation fails loudly and keeps the aside file), so a double lock holder
+can duplicate or shuffle backups but never lose a live file. The one deliberate
+loss is the oldest backup falling off `.5`. A crash between the aside rename and
+the final placement leaves `<log>.rotating-<pid>-<random>`; the next rotation
+(inside the lock) adopts every such file whose owner pid is dead, or whose mtime
+is over 5 s old, into the chain, oldest first. A crash between the link and the
+unlink can leave one duplicate of a backup.
+A row is never dropped because of the lock: on a lock timeout or any other
+lock error the writer appends the row WITHOUT rotating and prints one
+`adl log: rotation deferred, row kept: ...` line to stderr. `adl run` guards
+its own two rows the same way (`adl run: could not write log row: ...`, never
+aborting the run). `agent-hooks/crg-update` is not a JSON `LogFileName`: crg
+output is raw text written by `src/hooks/crg/background.ts`.
+
+The weekly search-tool audit (`agent-search-tool-audit`) reads the per-owner
+folders and still reads the legacy top-level `hooks.log` (never migrated)
+without writing to it.
+
+**`agent-hooks/hooks.log`** — one row per hook invocation of every kind (allow, deny,
+route). **`agent-hooks/deny.log`** — the same row, additionally, only when the
 invocation was a blocked pre-tool-use decision.
 
 `src/hooks/log.ts`'s field mapping (the shared schema has no dedicated
@@ -414,3 +466,20 @@ patterns, and `test/unit/coverage-policy.test.ts` asserts that policy (and
 that a below-threshold run really exits non-zero — Bun ignores the singular
 `line`/`function` keys). `bun test <file>` without `--coverage` stays usable
 for targeted runs.
+
+## Generated OpenCode plugin
+
+`adl install` deploys one OpenCode project plugin, `.opencode/plugins/adl-repo.ts`,
+rendered by `src/deploy/opencode-template.ts` from `assets/opencode-plugin.template.ts`,
+`assets/hooks.json` and the OpenCode surface in `deploy-profile.json`. Do not edit
+the deployed file by hand; re-run `adl install`.
+
+- The deployed file has no multi-line comments (Tarun 2026-10-08, Bug 602), so it
+  passes compliance control REP-007. Its header is a single line pointing here.
+- Fallback projection: an event with no documented OpenCode equivalent runs on a
+  substitute event, per the surface's `eventFallback` map in
+  `packages/agent-hooks/deploy-profile.json` (today `SessionEnd -> SessionIdle`).
+  The generated file lists the map as one line, `// Event fallbacks: A -> B, C -> D`,
+  and emits no line at all when the map is empty.
+- Source of truth for hook commands is `assets/hooks.json`; the generated arrays
+  carry `command`, `matcher`, `timeoutMs` and `fallbackFor` per entry.

package/packages/agent-hooks/assets/opencode-plugin.template.ts

@@ -1,9 +1,5 @@
-// AUTO-GENERATED by packages/agent-hooks (src/deploy/opencode-template.ts). Do not edit by hand.
-// Source: assets/hooks.json -> ONE OpenCode project plugin.
-//
-// Projected via fallback (owner rule: an event with no documented OpenCode
-// equivalent runs on a substitute event instead — see
-// this surface's `eventFallback` in packages/agent-hooks/deploy-profile.json):
+// AUTO-GENERATED by packages/agent-hooks from assets/hooks.json; do not edit. See packages/agent-hooks/README.md "Generated OpenCode plugin".
+
 __ADL_FALLBACK_ENTRIES__
 
 interface HookCommandSpec {

package/packages/agent-hooks/src/cli/args.ts

@@ -11,7 +11,7 @@
 
 import { readFileSync, statSync } from 'node:fs'
 import { resolve } from 'node:path'
-import { decodeConfig, type AdlRepoConfig } from '../gating/config.ts'
+import { decodeConfig, describeConfigIssue, type AdlRepoConfig } from '../gating/config.ts'
 import { MARKER, realRootIO, resolveManagedRepo } from '../gating/root.ts'
 import type { HookResult } from '../hooks/contract.ts'
 
@@ -88,7 +88,7 @@ export function loadRepo(cwd: string, repoArg: string | undefined): LoadedRepo |
   if (managed.configPath === null) return { ok: true, state, config: defaultConfig() }
   const decoded = decodeConfig(readFileSync(managed.configPath, 'utf8'))
   if (!decoded.ok) {
-    return { ok: false, state, error: `invalid ${managed.configPath} at ${decoded.issue.pointer}: ${decoded.issue.message}` }
+    return { ok: false, state, error: describeConfigIssue(managed.configPath, decoded.issue) }
   }
   return { ok: true, state, config: decoded.value }
 }

package/packages/agent-hooks/src/cli/doctor.ts

@@ -33,6 +33,7 @@ import { scanSkills } from '../hooks/user-prompt-submit/skills.ts'
 import { loadTokenizer } from '../hooks/user-prompt-submit/tokenizer.ts'
 import { loadVectorHalf, resolveGlobalArtifactDir } from '../hooks/user-prompt-submit/vector.ts'
 import { HOOKS_DENY_LOG_REL, HOOKS_LOG_REL } from '../hooks/log.ts'
+import { runningAdl } from '../gating/running-adl.ts'
 import { buildEngineContext } from '../rules/engine.ts'
 import { liveEnv, liveRepoIndex } from '../rules/ports.ts'
 import { BUILTIN_RULES, requireRegistered } from '../rules/registry.ts'
@@ -67,7 +68,7 @@ function repoChecks(loaded: LoadedRepo): { readonly checks: Check[]; readonly co
   if (!loaded.ok) return { checks: [repoLine, check('FAIL', 'config', loaded.error)], config: null }
   const root = state.root as string
   const ctx = buildEngineContext(loaded.config.rules, loaded.config.repo, requireRegistered(BUILTIN_RULES), liveRepoIndex(root), liveEnv, undefined, loaded.config.agent)
-  if (!ctx.ok) return { checks: [repoLine, check('FAIL', 'config', `${ctx.issue.pointer}: ${ctx.issue.message}`)], config: null }
+  if (!ctx.ok) return { checks: [repoLine, check('FAIL', 'config', `${ctx.issue.pointer}: ${ctx.issue.message}${runningAdl()}`)], config: null }
   return { checks: [repoLine, check('ok', 'config', 'valid')], config: loaded.config }
 }
 

package/packages/agent-hooks/src/cli/rules.ts

@@ -13,6 +13,7 @@
 
 import { buildEngineContext } from '../rules/engine.ts'
 import { liveEnv, liveRepoIndex } from '../rules/ports.ts'
+import { runningAdl } from '../gating/running-adl.ts'
 import { BUILTIN_RULES, requireRegistered } from '../rules/registry.ts'
 import type { AnyRuleSpec } from '../rules/spec.ts'
 import { type CliResult, type RepoState, cliError, loadRepo, parseArgs, unmanagedReason } from './args.ts'
@@ -42,7 +43,7 @@ function resolveRules(cwd: string, repoArg: string | undefined): Resolved | CliR
   const { state, config } = loaded
   const registered = requireRegistered(BUILTIN_RULES)
   const ctx = buildEngineContext(config.rules, config.repo, registered, liveRepoIndex(state.root ?? state.start), liveEnv, undefined, config.agent)
-  if (!ctx.ok) return cliError(`${state.configPath} ${ctx.issue.pointer}: ${ctx.issue.message}`)
+  if (!ctx.ok) return cliError(`${state.configPath} ${ctx.issue.pointer}: ${ctx.issue.message}${runningAdl()}`)
   const hooksEnabled = config.hooks.enabled
   const rules = [...registered.values()].map((spec) => ({
     spec,

package/packages/agent-hooks/src/deploy/opencode-template.ts

@@ -3,8 +3,9 @@
  * (render.ts's renderOpencodeSlots), the profile's pluginName, and the
  * identifier derived from it — reproducing this repo's own committed
  * `.opencode/plugins/adl-repo.ts` byte-for-byte for the current
- * deploy-profile.json + assets/hooks.json, except the header's first two
- * lines (see the template's own header comment for why).
+ * deploy-profile.json + assets/hooks.json, except the header (a one-line
+ * comment plus an optional one-line fallback comment; no multi-line comments in
+ * deployed code, Bug 602). See README "Generated OpenCode plugin".
  */
 import { readFileSync } from 'node:fs'
 import { join } from 'node:path'
@@ -54,7 +55,8 @@ export function renderOpencodePlugin(options: RenderOpencodePluginOptions): stri
 
   if (!template.includes('__ADL_FALLBACK_ENTRIES__')) throw new Error(`opencode plugin template is missing marker __ADL_FALLBACK_ENTRIES__: ${templatePath}`)
   const fallbackEntries = Object.entries(surface.eventFallback ?? {})
-  let out = template.replace('__ADL_FALLBACK_ENTRIES__', fallbackEntries.map(([from, to]) => `//   - ${from} -> ${to}`).join('\n'))
+  const fallbackComment = fallbackEntries.length === 0 ? '' : `// Event fallbacks: ${fallbackEntries.map(([from, to]) => `${from} -> ${to}`).join(', ')}`
+  let out = template.replace('__ADL_FALLBACK_ENTRIES__', fallbackComment)
 
   const slots = renderOpencodeSlots(hooksDoc, surface)
   for (const slot of OPENCODE_SLOTS) {

package/packages/agent-hooks/src/gating/config.ts

@@ -62,6 +62,7 @@
  */
 
 import { MARKER } from './root.ts'
+import { runningAdl } from './running-adl.ts'
 
 interface RuleSection {
   readonly enabled: boolean
@@ -146,6 +147,16 @@ export interface AdlRepoConfig {
 
 export type ConfigDecodeIssue = { readonly pointer: string; readonly message: string }
 
+/**
+ * The one place a config-decode failure is rendered for an operator:
+ * `invalid <config> at <pointer>: <message> (adl <version> at <exec path>)`
+ * (`./running-adl.ts`). Added at rendering only — `ConfigDecodeIssue` stays
+ * untouched for programmatic consumers.
+ */
+export function describeConfigIssue(configPath: string, issue: ConfigDecodeIssue): string {
+  return `invalid ${configPath} at ${issue.pointer}: ${issue.message}${runningAdl()}`
+}
+
 export type ConfigDecodeResult =
   | { readonly ok: true; readonly value: AdlRepoConfig }
   | { readonly ok: false; readonly issue: ConfigDecodeIssue }

package/packages/agent-hooks/src/gating/running-adl.ts

@@ -0,0 +1,24 @@
+/**
+ * Which adl is decoding the config. A stale binary rejecting a newer config's
+ * keys ("unknown key(s) 'fleet'") looks identical to a bad config, so every
+ * config rejection an operator sees carries `(adl <version> at <exec path>)`.
+ *
+ * The version belongs to the CLI (`apps/cli/package.json`, what `adl
+ * --version` prints). This package must not import upward into the app, so
+ * `adl hook` injects it through `run(argv, adlVersion)` in `../main.ts`. A
+ * caller that does not inject one (the standalone agent-hooks entry, in-process
+ * tests) renders `version unknown` — never a made-up number.
+ *
+ * The path is `process.execPath`: the compiled binary itself (there
+ * `process.argv[1]` is a virtual `/$bunfs` path); under `bun run` it is bun,
+ * which is what is actually running.
+ */
+let injectedVersion: string | undefined;
+
+export function setRunningAdlVersion(version: string | undefined): void {
+  injectedVersion = version;
+}
+
+export function runningAdl(): string {
+  return ` (adl ${injectedVersion ?? "version unknown"} at ${process.execPath})`;
+}

package/packages/agent-hooks/src/hooks/crg/background.ts

@@ -11,7 +11,8 @@
  * Protocol (all state under `<root>/.adl/`, already git-ignored):
  *  - `crg-update.lock`   holds the pid of the process running the update.
  *  - `crg-update.pending` marker: "an edit landed while an update ran".
- *  - `logs/crg-update.log` the update's own stdout+stderr (append).
+ *  - `logs/agent-hooks/crg-update.log` the update's own stdout+stderr (append;
+ *    rotated by the shared writer's rule before each spawn, Bug 600).
  *
  * `requestUpdate` (the hook side):
  *  1. Acquire the lock atomically (`wx`), holding the hook's own pid as a
@@ -33,7 +34,7 @@
  * Self-heal: if `code-review-graph update --skip-flows` exits non-zero,
  * the runner runs `code-review-graph build --skip-flows` once and logs a
  * `SELF-HEAL:` marker to stderr (captured by the spawn into
- * `crg-update.log`). The original error is already in the log because
+ * `agent-hooks/crg-update.log`). The original error is already in the log because
  * the spawn captures the update's own stderr; the marker is appended
  * after, so the failure is never silently swallowed. The build runs at
  * most once per runner invocation (a per-runner shell variable), so a
@@ -47,10 +48,11 @@ import { closeSync, mkdirSync, openSync, readFileSync, rmSync, statSync, writeFi
 import { join } from 'node:path'
 
 import { ensureAdlGitignore } from '../../log/adl-dir.ts'
+import { rotateIfNeeded } from '../../log/writer.ts'
 
 export const LOCK_REL = '.adl/crg-update.lock'
 export const PENDING_REL = '.adl/crg-update.pending'
-export const UPDATE_LOG_REL = '.adl/logs/crg-update.log'
+export const UPDATE_LOG_REL = '.adl/logs/agent-hooks/crg-update.log'
 
 /** A lock older than this is presumed left by a crash, whatever its pid says. */
 export const MAX_LOCK_AGE_MS = 30 * 60 * 1000
@@ -113,6 +115,7 @@ function isPidAlive(pid: number): boolean {
 }
 
 function spawnDetached(spec: SpawnSpec): number {
+  rotateIfNeeded(spec.logFile, 0)
   const fd = openSync(spec.logFile, 'a', 0o600)
   try {
     const proc = Bun.spawn([spec.cmd, ...spec.args], {
@@ -185,7 +188,7 @@ function acquireAndStart(deps: BackgroundDeps, root: string, env: SpawnSpec['env
 }
 
 export function requestUpdate(deps: BackgroundDeps, root: string, env: SpawnSpec['env']): UpdateRequest {
-  mkdirSync(join(root, '.adl', 'logs'), { recursive: true, mode: 0o700 })
+  mkdirSync(join(root, '.adl', 'logs', 'agent-hooks'), { recursive: true, mode: 0o700 })
   ensureAdlGitignore(join(root, '.adl'))
   const lockPath = join(root, LOCK_REL)
   const pendingPath = join(root, PENDING_REL)

package/packages/agent-hooks/src/hooks/log.ts

@@ -1,15 +1,15 @@
 /**
- * The agent-hook decision logs: `.adl/logs/hooks.log` (every decision —
- * allow, deny, route) and `.adl/logs/hooks-deny.log` (every deny, with the
- * rule and the `adl` hint shown to the agent) — docs/architecture/cli-design.md §5a.
+ * The agent-hook decision logs: `.adl/logs/agent-hooks/hooks.log` (every
+ * decision — allow, deny, route) and `.adl/logs/agent-hooks/deny.log` (every
+ * deny, with the rule and the `adl` hint shown to the agent) — docs/architecture/cli-design.md §5a; one folder per owner (README, "Hook logs").
  *
  * BEHAVIOUR CHANGE (Tarun, 2026-09-27, §5a): this used to write two CSV
  * files under `.enact/logs/` (`adl-hook-deny.log` / `adl-hook-activity.log`,
  * ported from enact-m5's `.agents/hooks/pre-tool-use/src/deny.mjs`
  * `logDenial`). §5a's later decision replaces that with ONE JSON-Lines
- * format shared by all five `.adl/logs/*.log` files
- * (`../log/writer.ts`'s `writeLogEntry`), written to `.adl/logs/hooks.log`
- * and `.adl/logs/hooks-deny.log`. `.enact/logs/` is a **hard cut**: it is no
+ * format shared by every `.adl/logs/<owner>/*.log` file
+ * (`../log/writer.ts`'s `writeLogEntry`), written to `.adl/logs/agent-hooks/hooks.log`
+ * and `.adl/logs/agent-hooks/deny.log`. `.enact/logs/` is a **hard cut**: it is no
  * longer written (the old files, if present, are left in place — see
  * `../log/writer.ts`'s header and `writeLogEntry`'s rotation/redaction/0700
  * '0600 behaviour, which this file now delegates to instead of owning its
@@ -76,8 +76,8 @@ import type { LogEntryInput } from '../log/writer.ts'
 import { writeLogEntry } from '../log/writer.ts'
 import type { ActivityNote, HookHandler, HookInvocation, HookResult } from './contract.ts'
 
-export const HOOKS_LOG_REL = '.adl/logs/hooks.log'
-export const HOOKS_DENY_LOG_REL = '.adl/logs/hooks-deny.log'
+export const HOOKS_LOG_REL = '.adl/logs/agent-hooks/hooks.log'
+export const HOOKS_DENY_LOG_REL = '.adl/logs/agent-hooks/deny.log'
 const MAX_LOGGED_COMMAND_LENGTH = 2000
 
 function truncateCommand(value: string): string {
@@ -212,10 +212,10 @@ export async function runLogged(inv: HookInvocation, handler: HookHandler, now:
     const stamped = now()
     const sameNow = () => stamped
     try {
-      writeLogEntry('hooks', entry, { dir, now: sameNow })
-      if (outcome.denyRuleId !== undefined) writeLogEntry('hooks-deny', entry, { dir, now: sameNow })
-    } catch {
-      // Best-effort: a log write must never change a hook's stdout/stderr/exit code.
+      writeLogEntry('agent-hooks/hooks', entry, { dir, now: sameNow })
+      if (outcome.denyRuleId !== undefined) writeLogEntry('agent-hooks/deny', entry, { dir, now: sameNow })
+    } catch (error) {
+      process.stderr.write(`adl agent-hooks: could not write log row: ${error instanceof Error ? error.message : String(error)}\n`)
     }
   }
   let result: HookResult

package/packages/agent-hooks/src/hooks/user-prompt-submit/handler.ts

@@ -15,7 +15,7 @@
 import { existsSync, readFileSync } from 'node:fs'
 import { join } from 'node:path'
 import type { HookHandler, HookInvocation } from '../contract.ts'
-import { decodeConfig } from '../../gating/config.ts'
+import { decodeConfig, describeConfigIssue } from '../../gating/config.ts'
 import { MARKER } from '../../gating/root.ts'
 import { DEFAULT_SKILLS_DIR } from './constants.ts'
 import { skillRootsFor } from './skill-roots.ts'
@@ -52,7 +52,7 @@ function resolveSkillRoots(inv: HookInvocation): readonly string[] {
   const text = readFileSync(configPath, 'utf8')
   const decoded = decodeConfig(text)
   if (!decoded.ok) {
-    throw new Error(`invalid ${configPath} at ${decoded.issue.pointer}: ${decoded.issue.message}`)
+    throw new Error(describeConfigIssue(configPath, decoded.issue))
   }
 
   const explicit = decoded.value.hooks.skillsDir