@amsterdamdatalabs/adl-agent-control-linux-x64 0.1.29 → 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

@@ -72,7 +72,8 @@ import type { HookHandler, HookInvocation, HookResult } from './hooks/contract.t
 import { payloadCwd } from './hooks/contract.ts'
 import { resolveHost, readHostFlag, type HostId } from './hosts/spec.ts'
 import { resolveManagedRepo, realRootIO } from './gating/root.ts'
-import { decodeConfig, type AdlRepoConfig } from './gating/config.ts'
+import { setRunningAdlVersion } from './gating/running-adl.ts'
+import { decodeConfig, describeConfigIssue, type AdlRepoConfig } from './gating/config.ts'
 import { FAIL_CLOSED_EXIT_CODE } from './rules/engine.ts'
 import { handlePreToolUse } from './pre-tool-use/handler.ts'
 import { handleUserPromptSubmit } from './hooks/user-prompt-submit/handler.ts'
@@ -123,7 +124,13 @@ function writeResult(result: HookResult): number {
   return result.exitCode
 }
 
-export async function run(argv: readonly string[]): Promise<number> {
+/**
+ * `adlVersion` is the embedding CLI's version (`adl hook` passes
+ * `apps/cli/package.json`'s); the standalone entry passes none, and config
+ * errors then say `version unknown` rather than guess.
+ */
+export async function run(argv: readonly string[], adlVersion?: string): Promise<number> {
+  setRunningAdlVersion(adlVersion)
   if (argv.includes('--version')) {
     process.stdout.write(`${readPackageVersion()}\n`)
     return 0
@@ -185,7 +192,7 @@ export async function run(argv: readonly string[]): Promise<number> {
   // `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)
@@ -199,7 +206,7 @@ export async function run(argv: readonly string[]): Promise<number> {
     const decoded = decodeConfig(text)
     if (!decoded.ok) {
       process.stderr.write(
-        `adl hook: invalid ${managed.configPath} at ${decoded.issue.pointer}: ${decoded.issue.message}\n`,
+        `adl hook: ${describeConfigIssue(managed.configPath, decoded.issue)}\n`,
       )
       return 1
     }

package/packages/agent-hooks/src/pre-tool-use/handler.ts

@@ -19,7 +19,8 @@
 import { readFileSync } from 'node:fs'
 import { join } from 'node:path'
 import type { ActivityNote, HookInvocation, HookResult } from '../hooks/contract.ts'
-import { decodeConfig } from '../gating/config.ts'
+import { decodeConfig, describeConfigIssue } from '../gating/config.ts'
+import { runningAdl } from '../gating/running-adl.ts'
 import { MARKER } from '../gating/root.ts'
 import {
   buildEngineContext,
@@ -221,7 +222,7 @@ export async function handlePreToolUse(inv: HookInvocation): Promise<HookResult>
   const text = readFileSync(configPath, 'utf8')
   const decoded = decodeConfig(text)
   if (!decoded.ok) {
-    throw new Error(`adl hook: invalid ${configPath} at ${decoded.issue.pointer}: ${decoded.issue.message}`)
+    throw new Error(`adl hook: ${describeConfigIssue(configPath, decoded.issue)}`)
   }
   const config = decoded.value
 
@@ -243,10 +244,10 @@ export async function handlePreToolUse(inv: HookInvocation): Promise<HookResult>
   inv.root,
 )
   if (!ctx.ok) {
-    inv.record?.({ reason: 'ERROR rules config', message: `adl hook: ${configPath} ${ctx.issue.pointer}: ${ctx.issue.message}` })
+    inv.record?.({ reason: 'ERROR rules config', message: `adl hook: ${configPath} ${ctx.issue.pointer}: ${ctx.issue.message}${runningAdl()}` })
     return {
       stdout: '',
-      stderr: `adl hook: ${configPath} ${ctx.issue.pointer}: ${ctx.issue.message}\n`,
+      stderr: `adl hook: ${configPath} ${ctx.issue.pointer}: ${ctx.issue.message}${runningAdl()}\n`,
       exitCode: FAIL_CLOSED_EXIT_CODE,
     }
   }

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/azdo/src/azdo-wit.ts

@@ -42,7 +42,12 @@ const isAllowedType = (type: string | undefined): type is AllowedType => (ALLOWE
 function assertAllowedType(type: string | undefined): asserts type is AllowedType {
   if (!isAllowedType(type)) throw new Error(`type must be one of ${ALLOWED_TYPES.join(', ')}; got ${type ?? 'undefined'}`);
 }
-function formatItem(wi: any, raw: boolean): Record<string, unknown> {
+interface WorkItemView {
+  id: number; title: string; type: string; state: string; assignedTo: string | undefined; description: string | undefined; url: string | undefined;
+  links: { parent: number | null; children: number[]; predecessors: number[]; successors: number[]; related: number[] };
+  effort: number | null; failureReason: string | null; fields?: Record<string, unknown>; relations?: unknown[];
+}
+function formatItem(wi: any, raw: boolean): WorkItemView {
   const fields = wi.fields ?? {};
   const relationId = (url: string) => Number(/(\d+)\/?$/.exec(url)?.[1]);
   const links = { parent: null as number | null, children: [] as number[], predecessors: [] as number[], successors: [] as number[], related: [] as number[] };
@@ -53,7 +58,8 @@ function formatItem(wi: any, raw: boolean): Record<string, unknown> {
     if (relation.rel === 'System.LinkTypes.Dependency-Forward') links.successors.push(relationId(relation.url));
     if (relation.rel === 'System.LinkTypes.Related') links.related.push(relationId(relation.url));
   }
-  const out: Record<string, unknown> = { id: wi.id, title: fields['System.Title'], type: fields['System.WorkItemType'], state: fields['System.State'], assignedTo: fields['System.AssignedTo']?.displayName, description: fields['System.Description'], url: wi._links?.html?.href, links, customFields: Object.fromEntries(Object.entries(fields).filter(([name]) => name.startsWith('Custom.'))) };
+  const effort = fields['Microsoft.VSTS.Scheduling.Effort']; const failureReason = fields['Custom.FailureReason'];
+  const out: WorkItemView = { id: wi.id, title: fields['System.Title'], type: fields['System.WorkItemType'], state: fields['System.State'], assignedTo: fields['System.AssignedTo']?.displayName, description: fields['System.Description'], url: wi._links?.html?.href, links, effort: typeof effort === 'number' ? effort : null, failureReason: typeof failureReason === 'string' && failureReason ? failureReason : null };
   if (raw) { out.fields = fields; out.relations = wi.relations ?? []; }
   return out;
 }

package/packages/azdo/src/mcp-server.ts

@@ -124,7 +124,7 @@ export function createServer(): Server {
       },
       {
         name: 'workitem_list_or_get',
-        description: 'Get one or many tracked work items, or query the scoped backlog.',
+        description: 'Get one or many tracked work items, or query the scoped backlog. Each item carries effort and failureReason (both null when unset).',
         inputSchema: {
           type: 'object',
           properties: {

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()}`)
+      }
     }
   }