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

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

@@ -1,10 +1,10 @@
 /**
  * The `.adl/logs/` logger (docs/architecture/cli-design.md §5a, item 9). `agent-hooks`
- * "holds logs" (§12): this module lives here and writes `hooks.log` /
- * `hooks-deny.log` (`../hooks/log.ts`); `apps/cli/src/log.ts` re-exports it
- * unchanged so `adl run`'s `agents/tool-calls.log` writer keeps working. The module
- * is generic across all five documented files so a caller never has to
- * reinvent the format.
+ * "holds logs" (§12): this module lives here and writes
+ * `agent-hooks/hooks.log` / `agent-hooks/deny.log` (`../hooks/log.ts`);
+ * `apps/cli/src/log.ts` re-exports it so `adl run`'s `agents/tool-calls.log`
+ * writer and repo-controls' `git-hooks/` writer share it. One folder per
+ * owner under `.adl/logs/` (Bug 600); every stream rotates through here.
  *
  * - JSON Lines, one object per line. Fields are written in a fixed order;
  *   an absent field is OMITTED, never null-filled.
@@ -14,24 +14,35 @@
  *   must never fail the caller.
  * - `command` is redacted with `redact()` before it is written.
  * - Rotation: a file that would exceed `maxBytes` (10 MiB by default) is
- *   rotated to `.1` … `.5`, dropping `.5`, before the new line is written.
+ *   rotated to `.1` … `.5`, dropping `.5`, before the new line is written,
+ *   under a per-file lock (README, "Hook logs").
  */
+import { randomBytes } from "node:crypto";
 import { spawnSync } from "node:child_process";
 import {
   appendFileSync,
   chmodSync,
   existsSync,
+  linkSync,
   mkdirSync,
+  readdirSync,
+  readFileSync,
   renameSync,
+  rmSync,
   statSync,
-  unlinkSync,
   writeFileSync,
 } from "node:fs";
 import { homedir } from "node:os";
 import { basename, dirname, join } from "node:path";
 import { ensureAdlGitignore } from "./adl-dir.ts";
 
-export type LogFileName = "hooks" | "hooks-deny" | "tool-rewrites" | "tool-calls" | "repo-controls";
+/** Every stream as `<owner folder>/<file>` under `.adl/logs/` (README, "Hook logs": one folder per owner, Bug 600). */
+export type LogFileName =
+  | "agent-hooks/hooks"
+  | "agent-hooks/deny"
+  | "git-hooks/activity"
+  | "git-hooks/deny"
+  | "agents/tool-calls";
 
 export interface LogEntryInput {
   /** Second column of every row: the host alone (`claude`, `codex`, `cursor`, `kimi`, `opencode`; `git` for git-hook rows). */
@@ -78,6 +89,8 @@ export interface WriteLogOptions {
   dir?: string;
   /** cwd used to resolve the git root when `dir` is not given. */
   cwd?: string;
+  /** How long to wait for the rotation lock before appending without rotating; defaults to 10 s. Tests inject a small value. */
+  lockTimeoutMs?: number;
   /** Rotation threshold in bytes; defaults to 10 MiB. Tests inject a small value. */
   maxBytes?: number;
   /** Clock override for deterministic `ts` values in tests. */
@@ -147,22 +160,154 @@ function ensureDirSecure(dir: string): void {
   ensureAdlGitignore(dir);
 }
 
+function isMissing(error: unknown): boolean {
+  return (error as NodeJS.ErrnoException).code === "ENOENT";
+}
+
 function ensureFileSecure(filePath: string): void {
-  if (!existsSync(filePath)) {
-    writeFileSync(filePath, "", { mode: 0o600 });
+  writeFileSync(filePath, "", { mode: 0o600, flag: "a" });
+  try {
+    tightenMode(filePath, 0o600);
+  } catch (error) {
+    if (!isMissing(error)) throw error;
   }
-  tightenMode(filePath, 0o600);
 }
 
-function rotate(filePath: string): void {
-  const dropped = `${filePath}.${MAX_BACKUPS}`;
-  if (existsSync(dropped)) unlinkSync(dropped);
+function renameIfPresent(src: string, dst: string): boolean {
+  try {
+    renameSync(src, dst);
+    return true;
+  } catch (error) {
+    if (isMissing(error)) return false;
+    throw error;
+  }
+}
+
+const INSERT_ATTEMPTS = 5;
+
+function linkIfFree(src: string, dst: string): boolean {
+  try {
+    linkSync(src, dst);
+    return true;
+  } catch (error) {
+    const code = (error as NodeJS.ErrnoException).code;
+    if (code === "EEXIST" || code === "ENOENT") return false;
+    throw error;
+  }
+}
+
+function shiftBackups(filePath: string): void {
+  rmSync(`${filePath}.${MAX_BACKUPS}`, { force: true });
   for (let n = MAX_BACKUPS - 1; n >= 1; n--) {
-    const src = `${filePath}.${n}`;
-    const dst = `${filePath}.${n + 1}`;
-    if (existsSync(src)) renameSync(src, dst);
+    if (linkIfFree(`${filePath}.${n}`, `${filePath}.${n + 1}`)) rmSync(`${filePath}.${n}`, { force: true });
+  }
+}
+
+/** Moves `src` into slot `.1` without ever overwriting a backup; exported for tests, `afterShift` is their race hook. */
+export function insertBackup(filePath: string, src: string, afterShift?: () => void): void {
+  for (let attempt = 0; attempt < INSERT_ATTEMPTS; attempt++) {
+    shiftBackups(filePath);
+    afterShift?.();
+    if (linkIfFree(src, `${filePath}.1`)) {
+      rmSync(src, { force: true });
+      return;
+    }
+    if (!existsSync(src)) return;
+  }
+  throw new Error(`log rotation could not find a free backup slot for ${src}; file kept`);
+}
+
+function ownerAlive(pid: number): boolean {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    return (error as NodeJS.ErrnoException).code === "EPERM";
+  }
+}
+
+function orphanedAsides(filePath: string): string[] {
+  const prefix = `${basename(filePath)}.rotating-`;
+  const dir = dirname(filePath);
+  return readdirSync(dir)
+    .filter((name) => name.startsWith(prefix))
+    .map((name) => ({ path: join(dir, name), pid: Number(/^(\d+)-/.exec(name.slice(prefix.length))?.[1]) }))
+    .map((entry) => ({ ...entry, mtime: statSync(entry.path, { throwIfNoEntry: false })?.mtimeMs }))
+    .filter(({ pid, mtime }) => mtime !== undefined && (!Number.isInteger(pid) || !ownerAlive(pid) || Date.now() - mtime > LOCK_STALE_MS))
+    .sort((a, b) => (a.mtime as number) - (b.mtime as number))
+    .map(({ path }) => path);
+}
+
+function rotate(filePath: string): void {
+  for (const orphan of orphanedAsides(filePath)) insertBackup(filePath, orphan);
+  const aside = `${filePath}.rotating-${process.pid}-${randomBytes(4).toString("hex")}`;
+  if (!renameIfPresent(filePath, aside)) return;
+  insertBackup(filePath, aside);
+}
+
+/** A lock older than this was left by a crashed writer and is broken. */
+const LOCK_STALE_MS = 5_000;
+const LOCK_TIMEOUT_MS = 10_000;
+
+function sleepSync(ms: number): void {
+  Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+
+function readLockToken(lockPath: string): string | undefined {
+  try {
+    return readFileSync(lockPath, "utf8");
+  } catch (error) {
+    if (isMissing(error)) return undefined;
+    throw error;
+  }
+}
+
+export function breakStaleLock(lockPath: string, observed: string): void {
+  if (readLockToken(lockPath) === observed) rmSync(lockPath, { force: true });
+}
+
+/** Runs `body` holding `<filePath>.lock` (O_EXCL create); size check and rotation are one critical section (README, "Hook logs"). Exported for tests. */
+export function withRotationLock(filePath: string, lockTimeoutMs: number, body: () => void): void {
+  const lockPath = `${filePath}.lock`;
+  const token = `${process.pid}-${randomBytes(8).toString("hex")}`;
+  const deadline = Date.now() + lockTimeoutMs;
+  for (;;) {
+    try {
+      writeFileSync(lockPath, token, { flag: "wx", mode: 0o600 });
+      break;
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== "EEXIST") throw error;
+    }
+    const held = statSync(lockPath, { throwIfNoEntry: false });
+    if (held !== undefined && Date.now() - held.mtimeMs > LOCK_STALE_MS) {
+      const observed = readLockToken(lockPath);
+      if (observed !== undefined) breakStaleLock(lockPath, observed);
+    }
+    if (Date.now() > deadline) throw new Error(`log rotation lock ${lockPath} is held; refusing to rotate without it`);
+    sleepSync(2);
+  }
+  try {
+    body();
+  } finally {
+    if (readLockToken(lockPath) === token) rmSync(lockPath, { force: true });
   }
-  if (existsSync(filePath)) renameSync(filePath, `${filePath}.1`);
+}
+
+/** Rotates `filePath` to `.1` … `.5` when `incomingBytes` more would pass `maxBytes`, size re-read inside the lock; exported for raw-text streams (README, "Hook logs"). */
+export function rotateIfNeeded(
+  filePath: string,
+  incomingBytes: number,
+  maxBytes: number = DEFAULT_MAX_BYTES,
+  lockTimeoutMs: number = LOCK_TIMEOUT_MS,
+): void {
+  const over = () => {
+    const size = statSync(filePath, { throwIfNoEntry: false })?.size ?? 0;
+    return size > 0 && size + incomingBytes > maxBytes;
+  };
+  if (!over()) return;
+  withRotationLock(filePath, lockTimeoutMs, () => {
+    if (over()) rotate(filePath);
+  });
 }
 
 const USERINFO_RE = /(https?:\/\/)[^/\s:@]+:[^/\s@]+@/gi;
@@ -223,22 +368,23 @@ function serialize(entry: LogEntryInput, ts: string): string {
   return `${JSON.stringify(record)}\n`;
 }
 
-/** Appends one JSON-Lines entry to `<dir>/<file>.log`, rotating first if needed. Never throws for a missing repo — callers resolve `dir` with `resolveLogDir`. */
+/** Appends one JSON-Lines entry to `<dir>/<file>.log` (`file` is `<owner>/<name>`), rotating first if needed. Never throws for a missing repo — callers resolve `dir` with `resolveLogDir`. */
 export function writeLogEntry(file: LogFileName, entry: LogEntryInput, options: WriteLogOptions = {}): void {
   const dir = options.dir ?? resolveLogDir(options.cwd).dir;
   const maxBytes = options.maxBytes ?? DEFAULT_MAX_BYTES;
   const ts = (options.now?.() ?? new Date()).toISOString();
   const line = serialize(entry, ts);
 
-  ensureDirSecure(dir);
   const filePath = join(dir, `${file}.log`);
+  ensureDirSecure(dirname(filePath));
   ensureFileSecure(filePath);
 
-  const currentSize = statSync(filePath).size;
-  if (currentSize + Buffer.byteLength(line, "utf8") > maxBytes) {
-    rotate(filePath);
-    ensureFileSecure(filePath);
+  try {
+    rotateIfNeeded(filePath, Buffer.byteLength(line, "utf8"), maxBytes, options.lockTimeoutMs);
+  } catch (error) {
+    process.stderr.write(`adl log: rotation deferred, row kept: ${error instanceof Error ? error.message : String(error)}\n`);
   }
+  ensureFileSecure(filePath);
 
   appendFileSync(filePath, line, { mode: 0o600 });
 }

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

@@ -192,7 +192,7 @@ export async function run(argv: readonly string[], adlVersion?: string): Promise
   // `adl-config.toml` where `adl hooks deploy` has run — nowhere else. No
   // git root, or no `adl-config.toml` above `cwd`: a strict no-op (this
   // file's own header) — no rule evaluation, no identity check, no
-  // `hooks.log` write. There is no global identity baseline: a repo where
+  // `agent-hooks/hooks.log` write. There is no global identity baseline: a repo where
   // `adl-config.toml` does not exist has no business running hooks at all.
   // The same no-op applies when `[hooks] enabled = false` (below).
   const managed = resolveManagedRepo(realRootIO, cwd)

package/packages/agent-hooks/src/rules/impl/mcp-tool.ts

@@ -55,7 +55,7 @@ export function toolNameEndingWithKnownSuffix(tool: string, knownSuffixes: Reado
  *
  * Prefix-less fallback (added 2026-09-28 with the one-agent-identity
  * standard): OpenCode's and Kimi's own MCP tool-call naming has never actually been
- * observed in production (`.adl/logs/hooks.log` shows only `mcp__`-prefixed
+ * observed in production (`.adl/logs/agent-hooks/hooks.log` shows only `mcp__`-prefixed
  * calls, from Claude/Codex/Cursor) — they MAY call an azdo tool with no
  * `mcp__` prefix at all, spelled `<server>_<tool>` / `<server>.<tool>` /
  * `<server>:<tool>`. When `tool` carries no `mcp__` prefix, this falls back

package/packages/agent-hooks/src/rules/shell/invocation.ts

@@ -501,7 +501,8 @@ function classifyGitArgv(argv: readonly Token[], binary: string): readonly Invoc
 
 function walkGit(tokens: readonly Token[], index: number, parser: Parser): readonly Invocation[] {
   const binary = tokenValue(tokens[index] as Token)
-  const argv = tokens.slice(index + 1)
+  // Redirections are the shell's, not git's: write targets are classified from the raw tokens elsewhere (Bug 626).
+  const argv = withoutRedirections(tokens.slice(index + 1))
   const scan = scanGitGlobals(argv, 0)
   if (scan.terminal) return [{ kind: 'read-only', name: 'git' }]
   if (scan.index >= argv.length) return uncertain('git command missing subcommand')

package/packages/agent-skills/assets/agent-search-tool-audit/SKILL.md

@@ -91,7 +91,7 @@ ready for the next research-page review.
 
 | Metric | Source | Use |
 | --- | --- | --- |
-| Total decisions per host | `hooks.log` / `hooks.log.1` / `hooks-deny.log`, deduped by `(ts, command, rule)` | Volume baseline |
+| Total decisions per host | `agent-hooks/hooks.log*` / `agent-hooks/deny.log*` (plus the pre-Bug-600 top-level `hooks.log` / `hooks.log.1` / `hooks-deny.log`), deduped by `(ts, command, rule)` | Volume baseline |
 | Denials per host, broken down by `rule` field | same | Where the hook fires |
 | Search-tool denials (`tool.grep` / `tool.native-search` / `tool.find`) | same | The hook category this skill cares about |
 | `ast-grep` invocations (Bash command starting with `ast-grep`) | same | Whether the recommended tool is being used |
@@ -117,4 +117,26 @@ classifying them by tool). For the retry analysis, follow the
   — the hand-curated analysis this script would generate for today
 - `packages/agent-hooks/src/rules/impl/tool-grep.ts`,
   `tool-find.ts`, `tool-native-search.ts` — the deny messages the
-  audit is measuring
+  audit is measuring
+
+## Script notes
+
+Rationale moved out of `scripts/audit.sh` (REP-007: no multi-line comments).
+
+- Usage: `scripts/audit.sh [--days N] [--out DIR]`; defaults `--days 7`, `--out docs/research`.
+- Output: `<out>/research-YYYY-MM-DD-search-tool-usage-across-surfaces.md`, plus one new row appended
+  to `<out>/index.md`. Per-host, per-day tally of agent-hooks decisions, grouped by surface
+  (claude / codex / kimi / opencode), so the next weekly page in the series can compare against the
+  previous one. Reads only; never modifies the repo beyond those two files.
+- Source data: `.adl/logs/agent-hooks/hooks.log[.1-.5]` and `deny.log[.1-.5]` (one folder per owner,
+  Bug 600, Tarun 2026-10-08); the pre-Bug-600 top-level `.adl/logs/hooks.log`, `hooks.log.1` and
+  `hooks-deny.log` (read-only history, never migrated, deduped against the new ones);
+  `.adl/logs/agents/tool-calls.log` (`adl run` lifecycle).
+- Path discovery: the script lives in the agent-skills asset tree (5 levels deep in dev, 4 once
+  deployed to `.agents/skills/`), so it uses `git rev-parse --show-toplevel` to work in both layouts
+  and falls back to the dev layout if git is missing.
+- Required tools: `jq`, `python3` and `rg`; each is checked up front and the script fails loud
+  (exit 1) naming the missing one. `rg` is a protected bootstrap tool on every managed machine.
+- Cost: under 30 s on a typical 2-3 MB log set; no network.
+- An existing page for today is left untouched (it may be hand-curated); `index.md` is still updated
+  so the catalog stays current. Existing index rows are never disturbed; one row is appended.

package/packages/agent-skills/assets/agent-search-tool-audit/scripts/audit.sh

@@ -1,35 +1,5 @@
 #!/usr/bin/env bash
-# scripts/audit.sh — part of the agent-search-tool-audit skill
-# (packages/agent-skills/assets/agent-search-tool-audit/).
-#
-# Per-host, per-day tally of agent-hooks decisions in `.adl/logs/`,
-# grouped by surface (claude / codex / kimi / opencode). Writes one
-# dated markdown under `docs/research/` so the next weekly research
-# page in the "agent search-tool behaviour" series can compare against
-# the previous one. Reads only — never modifies the repo.
-#
-# Usage:
-#   scripts/audit.sh [--days N] [--out DIR]
-#
-# Defaults: --days 7, --out docs/research
-#
-# Output:
-#   <out>/research-YYYY-MM-DD-search-tool-usage-across-surfaces.md
-#   <out>/index.md  (one new row appended for the new page)
-#
-# Source data:
-#   .adl/logs/hooks.log            (current decision log)
-#   .adl/logs/hooks.log.1          (rotated decision log)
-#   .adl/logs/hooks-deny.log       (dedicated deny stream)
-#   .adl/logs/agents/tool-calls.log (adl run lifecycle)
-#
-# Path discovery: this script lives in the agent-skills asset tree
-# (5 levels deep in dev, 4 levels deep once deployed to
-# `.agents/skills/`). Use `git rev-parse --show-toplevel` so it
-# works in both layouts.
-#
-# Cost: <30 s on a typical 2-3 MB log set; no network, no new tools
-# beyond jq + python3 + the shell.
+# Usage and rationale: SKILL.md, "Script notes", in this skill's folder.
 
 set -euo pipefail
 
@@ -40,7 +10,7 @@ while [[ $# -gt 0 ]]; do
     --days) DAYS="$2"; shift 2;;
     --out)  OUT="$2"; shift 2;;
     -h|--help)
-      sed -n '2,30p' "$0"
+      echo "usage: audit.sh [--days N] [--out DIR]  (defaults: --days 7, --out docs/research)"
       exit 0
       ;;
     *)
@@ -52,10 +22,6 @@ done
 
 cd "$(dirname "$0")/../.."
 
-# `git rev-parse --show-toplevel` works in both dev (5 levels deep
-# under packages/agent-skills/assets/agent-search-tool-audit/scripts)
-# and deployed (4 levels deep under .agents/skills/). Fall back to
-# the dev layout if git is missing.
 if command -v git >/dev/null 2>&1; then
   if toplevel=$(git rev-parse --show-toplevel 2>/dev/null) && [[ -n "$toplevel" ]]; then
     cd "$toplevel"
@@ -63,9 +29,22 @@ if command -v git >/dev/null 2>&1; then
 fi
 
 command -v jq >/dev/null 2>&1 || { echo "jq is required and is not on PATH" >&2; exit 1; }
+command -v rg >/dev/null 2>&1 || { echo "rg is required and is not on PATH" >&2; exit 1; }
 command -v python3 >/dev/null 2>&1 || { echo "python3 is required and is not on PATH" >&2; exit 1; }
 
 LOG_FILES=(
+  .adl/logs/agent-hooks/hooks.log
+  .adl/logs/agent-hooks/hooks.log.1
+  .adl/logs/agent-hooks/hooks.log.2
+  .adl/logs/agent-hooks/hooks.log.3
+  .adl/logs/agent-hooks/hooks.log.4
+  .adl/logs/agent-hooks/hooks.log.5
+  .adl/logs/agent-hooks/deny.log
+  .adl/logs/agent-hooks/deny.log.1
+  .adl/logs/agent-hooks/deny.log.2
+  .adl/logs/agent-hooks/deny.log.3
+  .adl/logs/agent-hooks/deny.log.4
+  .adl/logs/agent-hooks/deny.log.5
   .adl/logs/hooks.log
   .adl/logs/hooks.log.1
   .adl/logs/hooks-deny.log
@@ -80,15 +59,12 @@ TODAY="$(date -u +%Y-%m-%d)"
 RUN_TS="$(date -u +%Y-%m-%dT%H:%M:%SZ)"
 OUT_FILE="${OUT}/research-${TODAY}-search-tool-usage-across-surfaces.md"
 
-# If today's page already exists, leave it alone — it might be a hand-curated
-# analysis from earlier in the day. Append / update `index.md` either way so
-# the catalog stays current.
 if [[ -f "$OUT_FILE" ]]; then
   echo "${OUT_FILE} already exists; leaving it untouched. Re-run after deleting it (or pass --out to a different dir)."
   # Still touch index.md so the catalog row stays current (idempotent).
   INDEX="${OUT}/index.md"
   ROW="| [Search-tool usage across surfaces — ${TODAY}](research-${TODAY}-search-tool-usage-across-surfaces.md) | Auto-generated weekly audit of per-host search-tool denials and recommended-tool invocations |"
-  if [[ -f "$INDEX" ]] && ! grep -q "research-${TODAY}-search-tool-usage-across-surfaces.md" "$INDEX"; then
+  if [[ -f "$INDEX" ]] && ! rg -q "research-${TODAY}-search-tool-usage-across-surfaces.md" "$INDEX"; then
     python3 - "$INDEX" "$ROW" <<'PYEOF' >/dev/null
 import sys
 path, row = sys.argv[1], sys.argv[2]
@@ -177,13 +153,13 @@ lines.append("type: Research")
 lines.append("created: {0}".format(today))
 lines.append("status: stable")
 lines.append("last_update: {0}".format(run_ts))
-lines.append("sources: .adl/logs/hooks.log, .adl/logs/hooks.log.1, .adl/logs/hooks-deny.log")
+lines.append("sources: .adl/logs/agent-hooks/hooks.log*, .adl/logs/agent-hooks/deny.log*, .adl/logs/hooks.log, .adl/logs/hooks.log.1, .adl/logs/hooks-deny.log")
 lines.append("related: ./index.md, ./research-2026-10-02-search-tool-usage-across-surfaces.md")
 lines.append("---")
 lines.append("")
 lines.append("# Agent interface search-tool usage across surfaces ({0})".format(today))
 lines.append("")
-lines.append("Auto-generated weekly audit. Window: trailing {0} UTC days ending {1}. Source: `.adl/logs/hooks*.log` and `.adl/logs/hooks-deny.log`. Re-run with `just research/weekly-search-audit`.".format(days, today))
+lines.append("Auto-generated weekly audit. Window: trailing {0} UTC days ending {1}. Source: `.adl/logs/agent-hooks/` (plus the pre-Bug-600 top-level `hooks.log*` and `hooks-deny.log`). Re-run with `just research/weekly-search-audit`.".format(days, today))
 lines.append("")
 lines.append("## Headline per host")
 lines.append("")
@@ -238,8 +214,6 @@ lines.append("")
 sys.stdout.write("\n".join(lines))
 PYEOF
 
-# Append / update index.md with the new page row. We don't disturb
-# other rows; we add one to the end of the table.
 INDEX="${OUT}/index.md"
 ROW="| [Search-tool usage across surfaces — ${TODAY}](research-${TODAY}-search-tool-usage-across-surfaces.md) | Auto-generated weekly audit of per-host search-tool denials and recommended-tool invocations |"
 
@@ -247,7 +221,7 @@ if [[ ! -f "$INDEX" ]]; then
   echo "index.md not present at ${INDEX}; not updating" >&2
   exit 0
 fi
-if grep -q "research-${TODAY}-search-tool-usage-across-surfaces.md" "$INDEX"; then
+if rg -q "research-${TODAY}-search-tool-usage-across-surfaces.md" "$INDEX"; then
   echo "index.md already has today's page; not appending"
 else
   # Insert before the closing fence (if any) or just append before EOF.

package/packages/agent-skills/assets/diagnosing-bugs/SKILL.md

@@ -98,3 +98,12 @@ Required before declaring done:
 - [ ] The hypothesis that turned out correct is stated in the commit / PR message — so the next debugger learns
 
 **Then ask: what would have prevented this bug?** If the answer involves architectural change (no good test seam, tangled callers, hidden coupling) hand off to the `/improve-codebase-architecture` skill with the specifics. Make the recommendation **after** the fix is in, not before — you have more information now than when you started.
+
+## HITL loop script
+
+`scripts/hitl-loop.template.sh` is the human-in-the-loop reproduction loop (usage notes moved out of the script so the deployed copy has no multi-line comment run).
+
+- Copy the file, edit the steps in it, and run it. The agent runs the script; the user follows prompts in their terminal.
+- Usage: `bash hitl-loop.template.sh`
+- Two helpers: `step "<instruction>"` shows the instruction and waits for Enter; `capture VAR "<question>"` shows the question and reads the response into `VAR`.
+- At the end, captured values are printed as `KEY=VALUE` for the agent to parse.

package/packages/agent-skills/assets/diagnosing-bugs/scripts/hitl-loop.template.sh

@@ -1,16 +1,5 @@
 #!/usr/bin/env bash
-# Human-in-the-loop reproduction loop.
-# Copy this file, edit the steps below, and run it.
-# The agent runs the script; the user follows prompts in their terminal.
-#
-# Usage:
-#   bash hitl-loop.template.sh
-#
-# Two helpers:
-#   step "<instruction>"          → show instruction, wait for Enter
-#   capture VAR "<question>"      → show question, read response into VAR
-#
-# At the end, captured values are printed as KEY=VALUE for the agent to parse.
+# Human-in-the-loop reproduction loop; usage in SKILL.md "HITL loop script".
 
 set -euo pipefail
 

package/packages/fleet/manifest.json

@@ -33,7 +33,7 @@
       "remove_worktrees": true
     },
     "brew_upgrade_exclude": [],
-    "protected_tools": ["git", "jq"],
+    "protected_tools": ["git", "jq", "ripgrep"],
     "git_global_config": {
       "credential.helper": ["", "{git-credential-manager}"],
       "credential.https://dev.azure.com.useHttpPath": "true",
@@ -159,6 +159,7 @@
         "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"},
+        "shfmt": {"manager": "brew", "package": "shfmt", "executable": "shfmt"},
         "tailscale": {"manager": "apt", "package": "tailscale", "executable": "/usr/bin/tailscale"},
         "uv": {"manager": "brew", "package": "uv", "executable": "uv"},
         "yq": {"manager": "brew", "package": "yq", "executable": "yq"}

package/packages/fleet/src/repo-maintain.ts

@@ -328,8 +328,8 @@ export function maintainRepositories(options: MaintainOptions): MaintainResult {
     if (maxAgeDays !== undefined) pruneStale(repo, name, current, maxAgeDays)
 
     // 5. the per-repo enrolment.
-    const argv = [...options.install.leadingArgs, 'install', '--repo', repo]
-    const shown = `adl install --repo ${repo}`
+    const argv = [...options.install.leadingArgs, 'install', '--repo', repo, '--rewire']
+    const shown = `adl install --repo ${repo} --rewire`
     if (dry) {
       info(`${name}: [dry] would run ${shown}`)
       return
@@ -341,6 +341,9 @@ export function maintainRepositories(options: MaintainOptions): MaintainResult {
       fail(`${name}: ${shown} exited ${result.status}: ${(result.stderr ?? '').trim()}`, repo)
     } else {
       info(`${name}: ${shown}: ok`)
+      for (const line of `${result.stdout}${result.stderr}`.split('\n')) {
+        if (/WARNING|FAIL|COULD-NOT-RUN/.test(line)) warn(`${name}: ${line.trim()}`)
+      }
     }
   }
 

package/packages/repo-controls/AGENTS.md

@@ -44,8 +44,8 @@ connection to `enact-vps`.
 **This repo's own layout versus what it writes.** Package-owned hook sources
 live under `scripts/hooks/`; commit `20ec790` removed the former
 `scripts/verbatim/` mirror and its manifest when mechanism moved into the
-package. The `.workflows/hooks/` stubs, the `.adl/logs/{repo-controls,
-hooks-deny}.log` JSON-Lines streams (written via `adl-repo-controls log`,
+package. The `.workflows/hooks/` stubs, the `.adl/logs/git-hooks/{activity,
+deny}.log` JSON-Lines streams (written via `adl-repo-controls log`,
 `src/hook-log.ts` — `.enact/logs/` is a 2026-09-27 hard cut, no longer
 written) and the `core.hooksPath` setting are what `install --repo` wires in
 **target** repos.
@@ -55,8 +55,11 @@ branch prefixes `feat|fix|docs|chore`, protected `main` and `integration`,
 lowercase kebab-case descriptions, lowercase commit subject with an 80-character
 limit and a fixed type list, plus the coverage ratchet and the behind-origin push
 check. Per-repo values are config-driven, in `adl-config.toml`'s `[controls]`
-table. Installing seeds `branches` and `pre_push.remote` only and arms no gate;
-every other control is absent and therefore off until someone adds it.
+table. Installing seeds `branches` and `pre_push.remote` for `[controls]` and arms no
+push or commit gate there; every other `[controls]` key is absent and therefore off
+until someone adds it. `[controls.compliance]` is the opposite: install seeds the standard
+trees and arms the strict gate set (see
+`docs/architecture/compliance-controls.md#strict-activation-and-switching-a-gate-off`).
 
 **`doctor --repo` must detect a dangling `core.hooksPath`.** If the directory it
 points at is missing, git silently runs no hooks and does not error. That is the