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

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

@@ -0,0 +1,179 @@
+/**
+ * Single-flight, detached `code-review-graph update --skip-flows`.
+ *
+ * Why this exists: on a large repo `update` takes ~13 s, but the
+ * `PostToolUse` hook that triggers it is killed by the host at 5 s
+ * (`assets/hooks.json`, `"timeout": 5`), so a synchronous run never
+ * finishes and the graph goes stale on every edit. The hook therefore only
+ * DECIDES here and returns at once; the work runs in a detached process
+ * group that outlives the hook.
+ *
+ * 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).
+ *
+ * `requestUpdate` (the hook side):
+ *  1. Acquire the lock atomically (`wx`), holding the hook's own pid as a
+ *     placeholder so a concurrent hook sees a live owner, then spawn the
+ *     runner and overwrite the lock with the runner's pid.
+ *  2. Lock already held by a live process (and younger than
+ *     `MAX_LOCK_AGE_MS`, a guard against pid reuse after a crash/reboot):
+ *     touch the pending marker and spawn nothing. A dead pid, or an
+ *     over-age lock, is stale: it is removed and step 1 retried once.
+ *  3. After touching the marker, re-check the owner: if it exited in the
+ *     window between the first check and the marker write, acquire and
+ *     spawn instead, so the queued edit is never stranded.
+ *
+ * `RUNNER_SCRIPT` (the detached side) runs the update, and while the
+ * pending marker exists clears it and runs once more. On its way out it
+ * releases the lock, then re-checks the marker once and re-acquires the
+ * lock (noclobber) if a hook queued in the meantime, closing the last gap.
+ */
+
+import { closeSync, mkdirSync, openSync, readFileSync, rmSync, statSync, writeFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+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'
+
+/** A lock older than this is presumed left by a crash, whatever its pid says. */
+export const MAX_LOCK_AGE_MS = 30 * 60 * 1000
+
+export const RUNNER_SCRIPT = [
+  'lock="$1"; pending="$2"; shift 2',
+  'while :; do',
+  '  rm -f "$pending"',
+  '  "$@"',
+  '  if [ -e "$pending" ]; then continue; fi',
+  '  rm -f "$lock"',
+  '  if [ -e "$pending" ] && (set -C; echo $$ > "$lock") 2>/dev/null; then continue; fi',
+  '  break',
+  'done',
+].join('\n')
+
+export interface SpawnSpec {
+  readonly cmd: string
+  readonly args: readonly string[]
+  readonly cwd: string
+  readonly env: Readonly<Record<string, string | undefined>>
+  /** Absolute path the child's stdout+stderr are appended to. */
+  readonly logFile: string
+}
+
+export interface BackgroundDeps {
+  /** Start a detached, unref'd child; return its pid. Must not wait for it. */
+  readonly spawn: (spec: SpawnSpec) => number
+  readonly isAlive: (pid: number) => boolean
+  readonly now: () => number
+  readonly selfPid: () => number
+  /** Resolve `bin` against `path` (the hook's own PATH); `null` when it is not there. */
+  readonly resolve: (bin: string, path: string | undefined) => string | null
+}
+
+export type UpdateRequest = 'spawned' | 'queued'
+
+const UPDATE_ARGS = ['update', '--skip-flows'] as const
+
+function isPidAlive(pid: number): boolean {
+  try {
+    process.kill(pid, 0)
+    return true
+  } catch (error) {
+    // EPERM: the process exists but belongs to someone else.
+    return (error as NodeJS.ErrnoException).code === 'EPERM'
+  }
+}
+
+function spawnDetached(spec: SpawnSpec): number {
+  const fd = openSync(spec.logFile, 'a', 0o600)
+  try {
+    const proc = Bun.spawn([spec.cmd, ...spec.args], {
+      cwd: spec.cwd,
+      env: spec.env as Record<string, string>,
+      stdin: 'ignore',
+      stdout: fd,
+      stderr: fd,
+      // Own session/process group: survives the hook, unreachable by the host's timeout kill.
+      detached: true,
+    })
+    proc.unref()
+    return proc.pid
+  } finally {
+    closeSync(fd)
+  }
+}
+
+export const defaultBackgroundDeps: BackgroundDeps = {
+  spawn: spawnDetached,
+  isAlive: isPidAlive,
+  now: () => Date.now(),
+  selfPid: () => process.pid,
+  resolve: (bin, path) => Bun.which(bin, { PATH: path ?? '' }),
+}
+
+function ownerIsLive(deps: BackgroundDeps, lockPath: string): boolean {
+  try {
+    const pid = Number.parseInt(readFileSync(lockPath, 'utf8').trim(), 10)
+    const ageMs = deps.now() - statSync(lockPath).mtimeMs
+    return Number.isInteger(pid) && pid > 0 && ageMs < MAX_LOCK_AGE_MS && deps.isAlive(pid)
+  } catch {
+    // Vanished between the caller's check and this read: nobody owns it.
+    return false
+  }
+}
+
+/** `wx` create: true if this call created the lock, false if it already exists. */
+function tryAcquire(lockPath: string, pid: number): boolean {
+  try {
+    writeFileSync(lockPath, `${pid}\n`, { flag: 'wx', mode: 0o600 })
+    return true
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === 'EEXIST') return false
+    throw error
+  }
+}
+
+function startRunner(deps: BackgroundDeps, root: string, env: SpawnSpec['env'], lockPath: string, pendingPath: string): void {
+  const pid = deps.spawn({
+    cmd: 'sh',
+    args: ['-c', RUNNER_SCRIPT, 'sh', lockPath, pendingPath, 'code-review-graph', ...UPDATE_ARGS],
+    cwd: root,
+    env,
+    logFile: join(root, UPDATE_LOG_REL),
+  })
+  writeFileSync(lockPath, `${pid}\n`, { mode: 0o600 })
+}
+
+/** Acquire + spawn. On a spawn failure the placeholder lock is released so the next edit can retry. */
+function acquireAndStart(deps: BackgroundDeps, root: string, env: SpawnSpec['env'], lockPath: string, pendingPath: string): boolean {
+  if (!tryAcquire(lockPath, deps.selfPid())) return false
+  try {
+    startRunner(deps, root, env, lockPath, pendingPath)
+  } catch (error) {
+    rmSync(lockPath, { force: true })
+    throw error
+  }
+  return true
+}
+
+export function requestUpdate(deps: BackgroundDeps, root: string, env: SpawnSpec['env']): UpdateRequest {
+  mkdirSync(join(root, '.adl', 'logs'), { recursive: true, mode: 0o700 })
+  const lockPath = join(root, LOCK_REL)
+  const pendingPath = join(root, PENDING_REL)
+
+  if (acquireAndStart(deps, root, env, lockPath, pendingPath)) return 'spawned'
+  if (!ownerIsLive(deps, lockPath)) {
+    rmSync(lockPath, { force: true })
+    if (acquireAndStart(deps, root, env, lockPath, pendingPath)) return 'spawned'
+  }
+  writeFileSync(pendingPath, '', { mode: 0o600 })
+  // The owner may have exited between the check and the marker write.
+  if (!ownerIsLive(deps, lockPath)) {
+    rmSync(lockPath, { force: true })
+    // The new runner clears the marker as its first step, so the queued edit is covered.
+    if (acquireAndStart(deps, root, env, lockPath, pendingPath)) return 'spawned'
+  }
+  return 'queued'
+}

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

@@ -13,9 +13,10 @@
  */
 
 import type { HookInvocation, HookResult } from '../contract.ts'
+import { defaultBackgroundDeps } from './background.ts'
 import { bunRunner, createCrgHandler } from './index.ts'
 
-const crgHandler = createCrgHandler({ run: bunRunner })
+const crgHandler = createCrgHandler({ run: bunRunner, background: defaultBackgroundDeps })
 
 export async function handleCrg(inv: HookInvocation): Promise<HookResult> {
   return crgHandler(inv)

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

@@ -47,6 +47,7 @@
 
 import type { HookHandler, HookInvocation, HookResult } from '../contract.ts'
 import { spawnWithTimeout } from '../../lib/spawn-with-timeout.ts'
+import { defaultBackgroundDeps, requestUpdate, type BackgroundDeps } from './background.ts'
 import { toDecideInput } from '../../pre-tool-use/handler.ts'
 import { invocations } from '../../rules/shell/invocation.ts'
 
@@ -99,8 +100,38 @@ function missingBinaryNote(subcommand: string, result: RunResult): string {
   return `crg ${subcommand}: ${BIN} ${reason}\n`
 }
 
-/** `after-file-edit.sh`: silent `update --skip-flows`, stdout `{}`, always exit 0. */
-async function afterFileEdit(run: Runner, inv: HookInvocation): Promise<HookResult> {
+const UPDATE_LABEL = 'code-review-graph update --skip-flows'
+
+/**
+ * `after-file-edit.sh`: `update --skip-flows`, stdout `{}`, always exit 0.
+ *
+ * With `background` (production wiring) the update is spawned DETACHED and
+ * single-flight (see `./background.ts`) and the hook returns at once: the
+ * update takes longer than the host's 5 s hook timeout on a large repo, so a
+ * synchronous run was killed every time and the graph never refreshed.
+ * Without it (unit tests of the plain runner path) the update runs inline.
+ */
+async function afterFileEdit(run: Runner, inv: HookInvocation, background: BackgroundDeps | undefined): Promise<HookResult> {
+  if (background !== undefined) {
+    // Fail loud up front: the detached runner's own "command not found" would land only in crg-update.log.
+    if (background.resolve(BIN, inv.env.PATH) === null) {
+      const note = missingBinaryNote('after-file-edit', { status: null, stdout: '', stderr: '' })
+      inv.record?.({ reason: `ERROR ${BIN} not on PATH`, message: note.trim() })
+      return { stdout: '{}\n', stderr: note, exitCode: 0 }
+    }
+    try {
+      const outcome = requestUpdate(background, inv.root, inv.env)
+      inv.record?.({
+        reason: 'PASS',
+        downstream: outcome === 'spawned' ? `spawned ${UPDATE_LABEL} (background)` : 'update already running; queued',
+      })
+      return { stdout: '{}\n', stderr: '', exitCode: 0 }
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error)
+      inv.record?.({ reason: `ERROR background ${UPDATE_LABEL}`, message })
+      return { stdout: '{}\n', stderr: `crg after-file-edit: could not start background update: ${message}\n`, exitCode: 0 }
+    }
+  }
   const result = await runCrg(run, inv, ['update', '--skip-flows'])
   return { stdout: '{}\n', stderr: missingBinaryNote('after-file-edit', result), exitCode: 0 }
 }
@@ -156,11 +187,11 @@ async function sessionStop(run: Runner, inv: HookInvocation): Promise<HookResult
   return { stdout: `${JSON.stringify({ message, passed: true })}\n`, stderr: note, exitCode: 0 }
 }
 
-export function createCrgHandler(deps: { run: Runner }): HookHandler {
+export function createCrgHandler(deps: { run: Runner; background?: BackgroundDeps }): HookHandler {
   return async (inv: HookInvocation): Promise<HookResult> => {
     switch (inv.subcommand) {
       case 'after-file-edit':
-        return afterFileEdit(deps.run, inv)
+        return afterFileEdit(deps.run, inv, deps.background)
       case 'pre-commit':
         return preCommit(deps.run, inv)
       case 'session-stop':
@@ -205,5 +236,5 @@ export const bunRunner: Runner = async (cmd, args, opts) => {
   }
 }
 
-export const handleCrg: HookHandler = createCrgHandler({ run: bunRunner })
+export const handleCrg: HookHandler = createCrgHandler({ run: bunRunner, background: defaultBackgroundDeps })
 export default handleCrg

package/packages/agent-hooks/src/rules/impl/fs-trash.ts

@@ -7,8 +7,8 @@
  *
  * The original's eighth predicate -- any path with an `.agents` segment --
  * was dropped by owner decision on 2026-09-15. `.agents/` is reconciled
- * centrally every six hours (global-tools `git-maintain` refreshes repo-local
- * surfaces in every managed repo), so a trashed copy is restored rather than
+ * centrally every 12 hours (`adl reconcile`'s repository step runs `adl install --repo`,
+ * which refreshes repo-local surfaces in every managed repo), so a trashed copy is restored rather than
  * lost, and `trash(1)` is itself recoverable from ~/.Trash. Protecting it here
  * blocked routine work to guard against something the fleet already repairs.
  *

package/packages/agent-hooks/src/rules/impl/git-paths.ts

@@ -31,15 +31,14 @@ export const gitRm: RuleSpec = {
   },
   message(_finding: Finding, ctx: MessageContext) {
     return {
-      user: 'Blocked git rm. It deletes tracked content and stages the deletion in one step; agents leave the file in place and hand the removal to you.',
+      user: 'Blocked git rm. It deletes tracked content and stages the deletion in one step; agents remove a tracked file with trash instead.',
       agent:
         'DENIED git rm. Every form is refused - with flags or without, --cached included. `git rm` deletes ' +
         'tracked content AND stages the deletion in one step, so it is both the delete and the commit-prep ' +
-        'for it, and it was the last deletion verb this hook left open after rm and trash were closed. ' +
-        'There is no flag that makes it acceptable and no `git rm` that this hook allows. ' +
-        'If a tracked file genuinely has to go: leave it exactly where it is, finish the rest of the change, ' +
-        'and tell the user which paths should be removed and why - removal is theirs to run, the same rule ' +
-        `that already applies to committing a protected tree. ${gitAgentTail(ctx.snippet)}`,
+        'for it. There is no flag that makes it acceptable and no `git rm` that this hook allows. ' +
+        'If a tracked file genuinely has to go, run `trash <path>` (recoverable from ~/.Trash; fs.trash only ' +
+        'refuses the working directory, a system root, $HOME and .git), then `git add <path>` to stage the ' +
+        `deletion with the rest of the change. ${gitAgentTail(ctx.snippet)}`,
     }
   },
   corpus: {

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

@@ -37,7 +37,7 @@ export const toolGrep: RuleSpec = {
   category: 'tool',
   severity: 'deny',
   enabledByDefault: true,
-  summary: 'Deny the grep family; steer at rg / ast-grep / search / ctx_search.',
+  summary: 'Deny the grep family; steer at ast-grep / search / crg / rg / ctx_search.',
   params: noParams,
   match(inv: Invocation): Finding | null {
     if (inv.kind !== 'grep') return null
@@ -45,15 +45,15 @@ export const toolGrep: RuleSpec = {
   },
   message(_finding: Finding, ctx: MessageContext) {
     return {
-      user: 'Blocked grep. Use `rg` (same job, faster, repo-aware), `ast-grep` for structural search, or `ctx_search` for the indexed search.',
+      user: 'Blocked grep. Pick the tool for the question: `ast-grep` for code shapes, `search` for docs by meaning, `crg` for callers and impact, `rg` for literal text, `ctx_search` for the indexed code search.',
       agent:
-        'DENIED grep. Use one of these instead - all are on PATH and already allowed:\n' +
-        '  rg          drop-in for grep, including stdin: `npm test 2>&1 | rg "pass|fail"`\n' +
-        '  ast-grep    structural/syntax search, for shapes rather than strings\n' +
-        '  search      hybrid semantic + keyword over indexed docs (`search query "<text>"`)\n' +
+        'DENIED grep. Match the tool to the question - in this order, all on PATH and already allowed:\n' +
+        '  ast-grep  code STRUCTURE: shapes rather than strings (`ast-grep -p "foo($A)" -l ts`)\n' +
+        '  search    docs and plans by MEANING: hybrid semantic + keyword (`search query "<text>"`)\n' +
+        '  crg       the code GRAPH: callers, callees, impact (`crg query callers_of <fn>`, `crg impact`)\n' +
+        '  rg        LITERAL text or regex, including stdin: `npm test 2>&1 | rg "pass|fail"`\n' +
         '  ctx_search  the indexed code search (action=symbol for an exact symbol)\n' +
-        'This applies to a pure output filter too: `rg` reads stdin exactly as grep does, ' +
-        'so there is no capability being removed here, only a slower tool. ' +
+        'A pure output filter is no exception: `rg` reads stdin exactly as grep does. ' +
         `Blocked command: ${ctx.snippet}`,
     }
   },

package/packages/agent-settings/assets/GLOBAL-AGENTS.md

@@ -9,7 +9,7 @@ repo's own `AGENTS.md`.
 - If a task is ambiguous, ask exactly one clarifying question.
 
 ## Truthfulness (non-negotiable)
-- **No fake-green tests** — never edit an assertion to force a pass. Red is honest.
+- **No fake-green tests.** A test changes only when the intended behaviour changes, never to make unintended behaviour pass. Red is honest.
 - **No silent fallback or degrade** — if the real path fails, fail loud and stop.
 - **No silent drops** — no `|| true`, no swallowed errors, no skipped gates.
 - **No fakes** — no stubs, placeholders or TODOs passed off as done.
@@ -69,7 +69,9 @@ repo's own `AGENTS.md`.
 
 ## Tests
 - For features, bugfixes and non-trivial refactors: **tests first**, confirmed failing for the right reason; then minimal code to pass; then a separate review pass.
-- Every change ships a **new** test. Never edit an existing test to make work pass.
+- Every change ships a **new** test.
+- When a change deliberately alters behaviour, rework the existing tests that assert the old behaviour, in the same change. Name each reworked test and the decision that changed it.
+- **Never fake green.** Don't loosen, skip or delete an assertion, or set an expectation to whatever the code returns, to hide a failure you didn't intend.
 - Skip for pure config, docs and trivial one-liners.
 
 ## Delegation & parallelism

package/packages/agent-settings/src/global-surface-sweep.ts

@@ -29,7 +29,6 @@ import {
 import { dirname, isAbsolute, join, relative, resolve, sep } from 'node:path'
 import { fileURLToPath } from 'node:url'
 import { BEGIN as KIMI_BEGIN, END as KIMI_END } from './kimi-hooks.ts'
-import { declaredLaunchAgentPlists } from '../../../packages/fleet/src/launch-agents.ts'
 
 const LAUNCH_AGENTS_DIR = 'Library/LaunchAgents'
 
@@ -40,8 +39,6 @@ const LAUNCH_AGENTS_DIR = 'Library/LaunchAgents'
  * these strings verbatim) contain, case-insensitively, one of these agent
  * tool tokens. Everything else (GoogleUpdater, Keystone, other application
  * updaters) is not an agent surface and is neither a candidate nor reported.
- * LaunchAgents enact-vps declares in fleet/manifest.json are always in
- * scope and protected by identity (see loadProtectionList).
  */
 export const AGENT_TOOL_TOKENS = [
   'lean-ctx',
@@ -295,7 +292,6 @@ export const EMPTY_PROTECTION: ProtectionList = {
 }
 
 export const DEFAULT_PROTECTION_PATH = fileURLToPath(new URL('../protected.json', import.meta.url))
-export const DEFAULT_MANIFEST_PATH = fileURLToPath(new URL('../../fleet/manifest.json', import.meta.url))
 
 export interface SweepNote {
   readonly level: 'warn' | 'ok'
@@ -605,18 +601,12 @@ export function decodeProtectionList(value: unknown): ProtectionList {
 }
 
 /**
- * The checked-in protection list plus every LaunchAgent plist enact-vps
- * itself ships (declared under `launch_agents` in fleet/manifest.json).
- * Shipped-job protection is derived from the manifest, never hand-listed.
+ * The checked-in protection list. (It used to add every LaunchAgent the fleet
+ * manifest declared; the manifest declares none since git-maintain was retired
+ * on 2026-09-30, so nothing is derived from it any more.)
  */
-export function loadProtectionList(path = DEFAULT_PROTECTION_PATH, manifestPath = DEFAULT_MANIFEST_PATH): ProtectionList {
-  const list = decodeProtectionList(JSON.parse(readFileSync(path, 'utf8')))
-  const declared = declaredLaunchAgentPlists(JSON.parse(readFileSync(manifestPath, 'utf8')))
-  const listed = new Set(list.paths.map((entry) => entry.path))
-  const derived = declared
-    .filter((entry) => !listed.has(entry.path))
-    .map((entry) => ({ path: entry.path, reason: `LaunchAgent shipped by enact-vps (fleet/manifest.json ${entry.declaredAt})` }))
-  return { ...list, paths: [...list.paths, ...derived] }
+export function loadProtectionList(path = DEFAULT_PROTECTION_PATH): ProtectionList {
+  return decodeProtectionList(JSON.parse(readFileSync(path, 'utf8')))
 }
 
 function tomlHeaderName(header: string): string {

package/packages/agent-skills/package.json

@@ -15,7 +15,7 @@
   "scripts": {
     "build": "rm -rf dist && tsc -p tsconfig.build.json",
     "typecheck": "tsc -p tsconfig.json --noEmit",
-    "test": "bun run typecheck && bun test"
+    "test": "bun run typecheck && bun test --coverage"
   },
   "dependencies": {
     "@iarna/toml": "^2.2.5",

package/packages/azdo/package.json

@@ -5,8 +5,7 @@
   "type": "module",
   "scripts": {
     "start": "bun src/mcp-server.ts",
-    "test": "bun test",
-    "test:coverage": "bun test --coverage",
+    "test": "bun test --coverage",
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {