@amsterdamdatalabs/adl-agent-control-linux-x64 0.1.10 → 0.1.26

package/packages/agent-hooks/src/deploy/json-merge.ts

@@ -44,14 +44,13 @@
  * position; adl's slot is restored separately, right there — never
  * deleted, never duplicated.
  *
- * A lock recording no hashes at all (`ownedEntries` absent — every repo
- * enrolled before this fix; closes (a)) falls back, for exactly this one
- * transitional deploy, to command-anywhere matching against the lock's OLD
- * `ownedCommands` — the only signal that data has — via the SAME
- * `legacyOwnedCommands` channel the pre-agent-hooks engine's own takeover
- * already used (both are "we have no better proof than an exact command
- * string" signals). This run then persists real content hashes
- * (`ownedEntries`), so every later deploy uses the full contract.
+ * The `legacyOwnedCommands` channel ("command text is the only proof we
+ * have") is fed ONLY by the pre-agent-hooks engine's own hash-verified
+ * takeover (legacy-lock.ts). It used to ALSO carry a one-deploy transitional
+ * fallback for a lock with no hashes at all (`ownedEntries` absent — every
+ * repo enrolled before this fix; closed (a)); that transition is over
+ * (Tarun, 2026-10-01): lock.ts's `readLock` now refuses such an entry
+ * outright, so every deploy here uses the full content-addressed contract.
  *
  * THIRD independent review (2026-09-30) found the fallback ITSELF still
  * leaked through raw array position, in two ways:

package/packages/agent-hooks/src/deploy/legacy-lock.ts

@@ -61,13 +61,13 @@ export function stableStringify(value: unknown): string {
 /** Content hash of a JSON value, exactly as the legacy engine recorded it. */
 export const legacyValueHash = (value: unknown): string => sha256Hex(stableStringify(value))
 
-export interface LegacyJsonMergeEntry {
+interface LegacyJsonMergeEntry {
   readonly type: string
   readonly path: readonly (string | number)[]
   readonly sha256: string
 }
 
-export interface LegacyMergedRecord {
+interface LegacyMergedRecord {
   readonly entries?: readonly LegacyJsonMergeEntry[]
 }
 

package/packages/agent-hooks/src/deploy/list.ts

@@ -10,7 +10,7 @@ import { type HookLockEntry, readLock } from './lock.ts'
 import { type HookDeployProfile, type HookSurface, loadProfile } from './profile.ts'
 import { flattenSourceHooks, hookLabel, loadHooksSource, type CanonicalHooksDoc } from './source.ts'
 
-export type HookOwner = 'adl' | 'user' | 'conflict' | '-'
+type HookOwner = 'adl' | 'user' | 'conflict' | '-'
 
 export interface HookListingEntry {
   readonly name: string

package/packages/agent-hooks/src/deploy/lock.ts

@@ -7,8 +7,12 @@
  * read it to report ownership.
  *
  * For a json-hooks surface (claude-settings / codex-hooks / cursor-hooks-v1),
- * "owned" is recorded per surface event name as the exact rendered command
- * strings (already carrying --host=<surface>) this deploy wrote there. For
+ * "owned" is recorded per surface event name as content-addressed hook
+ * entries (`ownedEntries`: hash + command + matcher), alongside the exact
+ * rendered command strings (`ownedCommands`, already carrying
+ * --host=<surface>; informational, read by list.ts). `readLock` refuses an
+ * entry without `ownedEntries` (the older `ownedCommands`-only shape is no
+ * longer migrated — Tarun, 2026-10-01). For
  * the opencode-plugin surface, the whole file is wholly adl-owned (H3) —
  * `owned: true` records that fact rather than a per-command breakdown.
  */
@@ -29,7 +33,7 @@ export const LOCK_RELATIVE_PATH = '.agents/agent-hooks.lock.json'
  * never by array position/index, which the second independent review
  * already ruled unreliable.
  */
-export interface OwnedHookEntry {
+interface OwnedHookEntry {
   readonly hash: string
   readonly command: string
   readonly matcher?: string
@@ -37,7 +41,7 @@ export interface OwnedHookEntry {
 
 export interface JsonHooksLockEntry {
   readonly format: 'claude-settings' | 'codex-hooks' | 'cursor-hooks-v1'
-  /** Surface event name -> the exact command strings (with --host) this deploy wrote into that event's array — informational only (list.ts); ownership itself is `ownedEntries`, below. */
+  /** Surface event name -> the exact command strings (with --host) this deploy wrote into that event's array — informational only (list.ts reads it to label what is adl's); ownership itself is `ownedEntries`, below. */
   readonly ownedCommands: Readonly<Record<string, readonly string[]>>
   /**
    * Surface event name -> this deploy's own written hooks, content-
@@ -45,16 +49,14 @@ export interface JsonHooksLockEntry {
    * pure array-index tracking, broke the moment a user inserted or
    * removed an entry before adl's own block, and could not express
    * "split a group" when a user hook was appended inside one — see
-   * json-merge.ts's header for the corrected rule). Absent on a lock
-   * written before EITHER ownership fix existed (every repo enrolled
-   * before this one) — every reader treats that as "derive ownership
-   * once from `ownedCommands` by exact command match, then persist real
-   * entries here," never as malformed.
+   * json-merge.ts's header for the corrected rule). Required: `readLock`
+   * refuses an entry without it (Tarun, 2026-10-01: the transitional
+   * rewrite of the older `ownedCommands`-only shape is gone).
    */
-  readonly ownedEntries?: Readonly<Record<string, readonly OwnedHookEntry[]>>
+  readonly ownedEntries: Readonly<Record<string, readonly OwnedHookEntry[]>>
 }
 
-export interface OpencodePluginLockEntry {
+interface OpencodePluginLockEntry {
   readonly format: 'opencode-plugin'
   readonly owned: true
 }
@@ -86,7 +88,24 @@ export function readLock(targetRepo: string): HookLock {
   if (typeof record !== 'object' || record === null || record.version !== 1 || typeof record.entries !== 'object' || record.entries === null) {
     throw new Error(`agent-hooks lock has an unrecognized shape: ${path}`)
   }
-  return { version: 1, entries: record.entries as Record<string, HookLockEntry> }
+  const entries = record.entries as Record<string, HookLockEntry>
+  // Tarun, 2026-10-01: the legacy (`ownedCommands` without `ownedEntries`) ->
+  // content-addressed migration is over. Reading such an entry as "owns
+  // nothing" would duplicate every adl hook already in the file, and
+  // guessing ownership from command text is the very thing content-
+  // addressing replaced — so refuse, loudly, and say how to recover.
+  for (const [file, entry] of Object.entries(entries)) {
+    if (typeof entry !== 'object' || entry === null || entry.format === 'opencode-plugin') continue
+    const ownedEntries: unknown = (entry as { ownedEntries?: unknown }).ownedEntries
+    if (typeof ownedEntries !== 'object' || ownedEntries === null || Array.isArray(ownedEntries)) {
+      throw new Error(
+        `agent-hooks lock entry for ${file} has no usable \`ownedEntries\` (the older \`ownedCommands\`-only shape is no longer migrated): ${path}. ` +
+          `Recover by removing the adl-written hook commands listed under that entry's \`ownedCommands\` from ${file}, deleting that entry from the lock (or deleting the lock file), ` +
+          `then running \`adl hooks deploy --repo ${targetRepo}\` to re-enrol.`,
+      )
+    }
+  }
+  return { version: 1, entries }
 }
 
 /** Skips the write entirely when the serialized content is already byte-identical (independent review, 2026-09-29, finding 8: a genuine no-op run must not touch the lock file's mtime either). */

package/packages/agent-hooks/src/deploy/profile.ts

@@ -16,11 +16,10 @@ import Ajv, { type ErrorObject, type ValidateFunction } from 'ajv'
 import { readFileSync } from 'node:fs'
 import { fileURLToPath } from 'node:url'
 
-export type HookWireFormat = 'claude-settings' | 'codex-hooks' | 'cursor-hooks-v1' | 'opencode-plugin'
-export const HOOK_WIRE_FORMATS: readonly HookWireFormat[] = ['claude-settings', 'codex-hooks', 'cursor-hooks-v1', 'opencode-plugin']
+type HookWireFormat = 'claude-settings' | 'codex-hooks' | 'cursor-hooks-v1' | 'opencode-plugin'
 
-export type UnmappedMatcherPolicy = 'keep' | 'drop'
-export type TimeoutUnit = 's' | 'ms'
+type UnmappedMatcherPolicy = 'keep' | 'drop'
+type TimeoutUnit = 's' | 'ms'
 
 export interface HookSurface {
   readonly name: string

package/packages/agent-hooks/src/deploy/source.ts

@@ -23,7 +23,7 @@ export interface CanonicalHookGroup {
 
 export type CanonicalHooksDoc = ReadonlyMap<string, readonly CanonicalHookGroup[]>
 
-export const DEFAULT_HOOKS_SOURCE_PATH = fileURLToPath(new URL('../../assets/hooks.json', import.meta.url))
+const DEFAULT_HOOKS_SOURCE_PATH = fileURLToPath(new URL('../../assets/hooks.json', import.meta.url))
 
 function isHookCommand(value: unknown): value is CanonicalHookCommand {
   if (typeof value !== 'object' || value === null) return false

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

@@ -10,8 +10,9 @@
  * `adl-config.toml` is shared with other tools at the same root: adl hook
  * owns `[hooks]`, `[rules]`, and `[repo]`; `adl-repo-controls` owns
  * `[controls]`; `adl-extensions` owns `[extensions]` (and, before its
- * HARDCUT, `[skills]`). `[controls]` and `[skills]` are recognized root tables
- * this module accepts and never reads into.
+ * HARDCUT, `[skills]`). `[azdo]` is reserved for shared Azure DevOps
+ * configuration. `[controls]`, `[skills]`, and `[azdo]` are recognized root
+ * tables this module accepts and never reads into.
  *
  * `[extensions]` is the one exception, and a deliberate one: its sub-table
  * KEYS are decoded into `AdlRepoConfig.extensions`. Since adl-extensions
@@ -27,13 +28,6 @@
  *                              # (pre-tool-use, user-prompt-submit, briefing,
  *                              # crg) for this repo: exit 0, empty stdout/stderr.
  *   skills_dir = ".agents/skills"  # optional; see src/hooks/user-prompt-submit
- *   lean_ctx_dir = ".agents/lean-ctx"  # optional; repo-relative root for
- *                              # lean-ctx's own config/data/state/cache dirs
- *                              # (see src/lean-ctx/env.ts). A throwaway repo
- *                              # — a binary test fixture, say — sets this so
- *                              # lean-ctx's state, and any daemon it starts
- *                              # off that state, lands somewhere disposable
- *                              # instead of the default.
  *
  *   [rules]
  *   default = "on"             # "on" | "off"; baseline for rules with no
@@ -69,7 +63,7 @@
 
 import { MARKER } from './root.ts'
 
-export interface RuleSection {
+interface RuleSection {
   readonly enabled: boolean
 }
 
@@ -79,11 +73,9 @@ export interface RulesConfig {
   readonly byId: Readonly<Record<string, RuleSection>>
 }
 
-export interface HooksConfig {
+interface HooksConfig {
   readonly enabled: boolean
   readonly skillsDir: string | undefined
-  /** Repo-relative root for lean-ctx's config/data/state/cache; see `../lean-ctx/env.ts`. */
-  readonly leanCtxDir: string | undefined
 }
 
 /**
@@ -185,7 +177,7 @@ const DEFAULT_AGENT: AgentSection = {
 }
 
 const DEFAULT_CONFIG: AdlRepoConfig = {
-  hooks: { enabled: true, skillsDir: undefined, leanCtxDir: undefined },
+  hooks: { enabled: true, skillsDir: undefined },
   rules: { default: 'on', unsafeAllowUncertain: false, byId: {} },
   repo: DEFAULT_REPO,
   agent: DEFAULT_AGENT,
@@ -222,13 +214,13 @@ function rejectUnknownKeys(
  * Top-level keys `decodeConfig` recognizes. `version` is accepted (and
  * ignored) only so the marker file's own minimal `version = 1\n` convention
  * stays valid — this package has no schema migrations to gate on it.
- * controls/skills: see module header for ownership.
+ * controls/skills/azdo: see module header for ownership.
  */
 /**
  * Root tables this module accepts. It owns `version`/`hooks`/`rules`/`repo`
  * and never reads the rest — they belong to the other tools sharing this file:
- * `controls` to adl-repo-controls, and `extensions` (formerly `skills`) to
- * adl-extensions.
+ * `controls` to adl-repo-controls, `extensions` (formerly `skills`) to
+ * adl-extensions, and `azdo` to shared Azure DevOps configuration.
  *
  * `skills` is retained alongside `extensions` on purpose. adl-extensions
  * HARDCUT to `[extensions]` because an extension owns its skills rather than
@@ -237,7 +229,7 @@ function rejectUnknownKeys(
  * here would fail exactly those repos, the ones nobody has touched yet.
  */
 const KNOWN_ROOT_KEYS: ReadonlySet<string> = new Set([
-  'version', 'hooks', 'rules', 'repo', 'agent', 'controls', 'skills', 'extensions',
+  'version', 'hooks', 'rules', 'repo', 'agent', 'controls', 'skills', 'extensions', 'azdo',
 ])
 
 /**
@@ -314,17 +306,11 @@ function decodeHooks(value: unknown): { ok: true; value: HooksConfig } | { ok: f
     return { ok: false, issue: { pointer: '/hooks/skills_dir', message: 'expected a string' } }
   }
 
-  const leanCtxDirRaw = value.lean_ctx_dir
-  if (leanCtxDirRaw !== undefined && typeof leanCtxDirRaw !== 'string') {
-    return { ok: false, issue: { pointer: '/hooks/lean_ctx_dir', message: 'expected a string' } }
-  }
-
   return {
     ok: true,
     value: {
       enabled: enabledRaw ?? true,
       skillsDir: skillsDirRaw,
-      leanCtxDir: leanCtxDirRaw,
     },
   }
 }

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

@@ -28,7 +28,7 @@ import { dirname, join } from 'node:path'
 import { statSync } from 'node:fs'
 
 /** Guard against a symlink loop or a pathological mount turning the walk into a hang. */
-export const MAX_WALK_DEPTH = 128
+const MAX_WALK_DEPTH = 128
 
 /** The repo marker + settings file (docs/architecture/adl-config.md). Hard cut (Tarun, 2026-09-27): no fallback read of the old `adl-config.toml` name. */
 export const MARKER = 'adl-config.toml'
@@ -40,7 +40,7 @@ export interface RootIO {
   readonly cwd: () => string
 }
 
-export interface GitRootResult {
+interface GitRootResult {
   readonly root: string | null
   readonly searched: readonly string[]
 }
@@ -50,7 +50,7 @@ export interface GitRootResult {
  * Stops at the first one found, at the filesystem root, or after
  * `MAX_WALK_DEPTH` levels — whichever comes first.
  */
-export function findGitRoot(io: RootIO, startDir: string): GitRootResult {
+function findGitRoot(io: RootIO, startDir: string): GitRootResult {
   const searched: string[] = []
   let current = startDir
 

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

@@ -13,9 +13,9 @@
  */
 
 import type { HookInvocation, HookResult } from '../contract.ts'
-import { bunRunner, createBriefingHandler } from './index.ts'
+import { createBriefingHandler } from './index.ts'
 
-const briefingHandler = createBriefingHandler({ run: bunRunner })
+const briefingHandler = createBriefingHandler()
 
 export async function handleBriefing(inv: HookInvocation): Promise<HookResult> {
   return briefingHandler(inv)

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

@@ -1,320 +1,60 @@
-/**
- * The `briefing` hook kind.
- *
- * Ports `enact-m5/.agents/hooks/session-briefing/`
- * (`session-briefing.mjs` + `src/render.mjs` + `src/warmup.mjs`) onto the
- * `HookHandler` contract in `../contract.ts`.
- *
- * Two subprocess calls into `lean-ctx`, both behind the injected `Runner` so
- * tests never touch a real binary:
- *
- *  1. `hook codex-session-start` — the base lean-ctx session briefing text,
- *     read out of its `hookSpecificOutput.additionalContext` JSON.
- *  2. `overview [task]` and `knowledge status` — the PROJECT WARMUP appendix,
- *     always emitted (even with no lean-ctx at all) because its static
- *     workflow block does not depend on either call succeeding.
- *
- * `lean-ctx` is a GLOBAL binary installed fleet-wide on `PATH` by
- * global-tools (see its `manifest.json`'s `"lean-ctx"` entry) — unlike the
- * reference tree, there is no repo-local `.agents/bin/lean-ctx-local`
- * wrapper here, so every call below resolves `lean-ctx` off the ambient
- * `PATH` directly. What stays repo-local is lean-ctx's own state: every call
- * still sets `LEAN_CTX_CONFIG_DIR`/`LEAN_CTX_DATA_DIR`/`LEAN_CTX_STATE_DIR`/
- * `LEAN_CTX_CACHE_DIR` rooted at `<root>/.agents/lean-ctx/<config/lean-ctx|data|state|cache>`
- * (`../../lean-ctx/env.ts`'s `leanCtxEnv` — shared with the `lean-ctx`
- * pre/post-tool-use hook kind, `../lean-ctx/index.ts`), so lean-ctx's
- * config/data/state/cache stay per-repository even though the binary itself
- * is now shared.
- *
- * HARDCUT (work item A.3): this used to set the plain `XDG_CONFIG_HOME`/
- * `XDG_DATA_HOME`/`XDG_STATE_HOME`/`XDG_CACHE_HOME` vars, mirroring what the
- * reference's wrapper script exported before exec'ing its own repo-local
- * binary. `../../lean-ctx/env.ts`'s header records the live verification
- * (this session, 2026-09-14) that the real v3.9.20 binary does not actually
- * key its config/data/state/cache resolution on those XDG vars at all — only
- * on the four `LEAN_CTX_*` ones now used here.
- *
- * lean-ctx missing or failing is advisory, never fatal: the warmup section
- * still goes out and the failure is named on stderr, but this never returns
- * exitCode 2 — a briefing hook has no host-visible "block" channel, and the
- * reference script's own header says the same ("Advises only — never block
- * the session or prompt"). A spawn that never exits (gap #1) degrades the
- * same way: the injected `Runner` is timeout-enforcing (see
- * `../../lib/spawn-with-timeout.ts`), so a hung `lean-ctx` child is killed
- * and reported exactly like a failed/ENOENT spawn — `status: null` — rather
- * than hanging the calling agent host.
- *
- * `deploy.mjs`-level concerns from the reference tree — wiring the hook into
- * each host's config, `--self-test`/`--host=`/`--event=` argv parsing, the
- * five-surface deploy fixture in `tests/test-wiring.mjs` — are out of scope
- * here: `src/hosts/*` and `src/main.ts`'s dispatch own that, per this task's
- * boundary.
- */
-
+/** Static session-orientation briefing for supported agent hosts. */
 import { existsSync, mkdirSync, writeFileSync } from 'node:fs'
 import { join } from 'node:path'
-
 import type { HookHandler, HookInvocation, HookResult, HostId } from '../contract.ts'
 import { spawnWithTimeout } from '../../lib/spawn-with-timeout.ts'
-import { leanCtxEnvFor } from '../../lean-ctx/env.ts'
-
-/** The marker lean-ctx's own `hook codex-session-start` output carries, when present. */
-export const MARKER = 'lean-ctx SESSION BRIEFING'
-export const WARMUP_MARKER = 'PROJECT WARMUP'
-
-const LEAN_CTX_BIN = 'lean-ctx'
 
-const OVERVIEW_MAX_LINES = 28
-const OVERVIEW_TIMEOUT_MS = 12_000
-const DEFAULT_TIMEOUT_MS = 8_000
-
-export interface RunResult {
-  readonly status: number | null
-  readonly stdout: string
-  readonly stderr: string
-  /** `true` only when the spawn was killed for exceeding `timeoutMs` — see gap #1. */
-  readonly timedOut?: boolean
-}
-
-export interface RunOptions {
-  readonly cwd: string
-  readonly env: Readonly<Record<string, string | undefined>>
-  readonly input?: string
-  /** Wall-clock spawn timeout in ms; overridable per call, defaults per call site below. */
-  readonly timeoutMs?: number
-}
-
-/** Process spawning, injected so tests never need a real `lean-ctx` binary. */
+interface RunResult { readonly status: number | null; readonly stdout: string; readonly stderr: string; readonly timedOut?: boolean }
+interface RunOptions { readonly cwd: string; readonly env: Readonly<Record<string, string | undefined>>; readonly input?: string; readonly timeoutMs?: number }
 export type Runner = (cmd: string, args: readonly string[], opts: RunOptions) => Promise<RunResult>
-
-function deliveredStateDir(root: string): string {
-  return join(root, '.agents/lean-ctx/state/session-briefing-delivered')
-}
-
-function sessionId(payload: Record<string, unknown>): string {
-  const raw = payload['session_id'] ?? payload['conversation_id']
-  return typeof raw === 'string' && raw.trim().length > 0 ? raw.trim() : 'unknown'
-}
-
-/** Cursor and Kimi have no host-native "fire once at SessionStart" channel; gate on a marker file instead. */
-function usesPromptGate(host: HostId): boolean {
-  return host === 'cursor' || host === 'kimi'
+/** Kept for the shared subprocess-runner contract used by focused tests. */
+export const bunRunner: Runner = async (cmd, args, opts) => {
+  try {
+    const result = await spawnWithTimeout(cmd, args, { cwd: opts.cwd, env: opts.env, timeoutMs: opts.timeoutMs ?? 8_000, ...(opts.input === undefined ? {} : { stdin: opts.input }) })
+    return result.timedOut ? { status: null, stdout: result.stdout, stderr: result.stderr.trim() || `${cmd} timed out after ${opts.timeoutMs ?? 8_000}ms`, timedOut: true } : { status: result.exitCode, stdout: result.stdout, stderr: result.stderr }
+  } catch (error) { return { status: null, stdout: '', stderr: error instanceof Error ? error.message : String(error) } }
 }
 
-function deliveredPath(root: string, host: HostId, session: string): string {
-  return join(deliveredStateDir(root), `${host}-${session}.done`)
-}
+const WARMUP_MARKER = 'PROJECT WARMUP'
 
-function alreadyDelivered(root: string, host: HostId, session: string): boolean {
-  if (!usesPromptGate(host)) return false
-  return existsSync(deliveredPath(root, host, session))
+function deliveredStateDir(root: string): string { return join(root, '.adl', 'state', 'session-briefing-delivered') }
+function sessionId(payload: Record<string, unknown>): string {
+  const raw = payload.session_id ?? payload.conversation_id
+  return typeof raw === 'string' && raw.trim() ? raw.trim() : 'unknown'
 }
-
+function usesPromptGate(host: HostId): boolean { return host === 'cursor' || host === 'kimi' }
+function deliveredPath(root: string, host: HostId, session: string): string { return join(deliveredStateDir(root), `${host}-${session}.done`) }
+function alreadyDelivered(root: string, host: HostId, session: string): boolean { return usesPromptGate(host) && existsSync(deliveredPath(root, host, session)) }
 function markDelivered(root: string, host: HostId, session: string): void {
   if (!usesPromptGate(host)) return
   mkdirSync(deliveredStateDir(root), { recursive: true })
   writeFileSync(deliveredPath(root, host, session), `${new Date().toISOString()}\n`)
 }
-
-function runLeanCtx(
-  run: Runner,
-  root: string,
-  env: Readonly<Record<string, string | undefined>>,
-  args: readonly string[],
-  timeoutMs = DEFAULT_TIMEOUT_MS,
-): Promise<RunResult> {
-  return run(LEAN_CTX_BIN, args, { cwd: root, env: leanCtxEnvFor(root, env), timeoutMs })
-}
-
-function truncateLines(text: string, maxLines: number): string {
-  const lines = text.split('\n')
-  if (lines.length <= maxLines) return text
-  return `${lines.slice(0, maxLines).join('\n')}\n… (${lines.length - maxLines} more lines; call ctx_overview for full map)`
-}
-
-function taskFromPayload(payload: Record<string, unknown>): string {
-  const prompt = payload['prompt']
-  const trimmed = typeof prompt === 'string' ? prompt.trim() : ''
-  if (trimmed.length < 8) return ''
-  return trimmed.length > 120 ? `${trimmed.slice(0, 117)}…` : trimmed
-}
-
-function workflowBlock(): string {
+function briefingText(): string {
   return [
-    WARMUP_MARKER,
-    '',
-    'Start every session (ctx_* or lean-ctx; use ctx_call when not advertised):',
-    '• ctx_overview / lean-ctx overview ["task"] — project map; FIRST on unfamiliar work',
+    WARMUP_MARKER, '',
+    'Start every session with ctx_overview when it is available; use ctx_call when it is not advertised.',
     '• ctx_knowledge(action="wakeup") — cross-session facts and decisions',
-    '• ctx_session(action="status") — last session findings in this repo',
-    '',
-    'Knowledge: ctx_knowledge or lean-ctx knowledge — status | recall | search | remember | consolidate',
-    'Checkpoints: ctx_session(action="task"|"decision", …) after significant progress',
-    '',
+    '• ctx_session(action="status") — last session findings in this repository', '',
     'After orientation: ctx_compose → ctx_read/ctx_search → ctx_shell (verify) → persist.',
   ].join('\n')
 }
-
-/**
- * The PROJECT WARMUP appendix. Always non-empty — its static workflow block
- * does not depend on `lean-ctx` at all — so a briefing is never fully silent
- * just because the binary is missing.
- */
-async function projectWarmupAppendix(
-  run: Runner,
-  root: string,
-  env: Readonly<Record<string, string | undefined>>,
-  payload: Record<string, unknown>,
-): Promise<string> {
-  const parts = [workflowBlock()]
-
-  const task = taskFromPayload(payload)
-  const overviewArgs = task ? ['overview', task] : ['overview']
-  const overview = await runLeanCtx(run, root, env, overviewArgs, OVERVIEW_TIMEOUT_MS)
-  if (overview.status === 0 && overview.stdout.trim()) {
-    parts.push('', '--- ctx_overview (cached snapshot) ---', truncateLines(overview.stdout.trim(), OVERVIEW_MAX_LINES))
-  }
-
-  const knowledge = await runLeanCtx(run, root, env, ['knowledge', 'status'])
-  if (knowledge.status === 0 && knowledge.stdout.trim()) {
-    parts.push('', '--- ctx_knowledge status ---', knowledge.stdout.trim())
-  }
-
-  return parts.join('\n')
-}
-
-function composeBriefing(base: string, warmup: string): string {
-  const b = base.trim()
-  const w = warmup.trim()
-  if (b && w) return `${b}\n\n${w}`
-  return b || w
-}
-
-interface BaseBriefing {
-  readonly text: string
-  readonly failureNote: string
-  readonly outcome: 'ok' | 'timeout' | 'error'
-}
-
-/** Runs `lean-ctx hook codex-session-start`; failure degrades to an empty base text plus a stderr note. */
-async function baseBriefing(
-  run: Runner,
-  root: string,
-  env: Readonly<Record<string, string | undefined>>,
-  payload: Record<string, unknown>,
-): Promise<BaseBriefing> {
-  const result = await run(LEAN_CTX_BIN, ['hook', 'codex-session-start'], {
-    cwd: root,
-    env: leanCtxEnvFor(root, env),
-    input: JSON.stringify(payload),
-    timeoutMs: DEFAULT_TIMEOUT_MS,
-  })
-
-  if (result.status !== 0 || !result.stdout.trim()) {
-    const reason = result.stderr.trim() || `lean-ctx exited with status ${String(result.status)}`
-    return {
-      text: '',
-      failureNote: `session-briefing: lean-ctx hook codex-session-start failed — ${reason}\n`,
-      outcome: result.timedOut ? 'timeout' : 'error',
-    }
-  }
-
-  try {
-    const parsed = JSON.parse(result.stdout) as { hookSpecificOutput?: { additionalContext?: unknown } }
-    const text = parsed.hookSpecificOutput?.additionalContext
-    return { text: typeof text === 'string' ? text : '', failureNote: '', outcome: 'ok' }
-  } catch (error) {
-    const message = error instanceof Error ? error.message : String(error)
-    return {
-      text: '',
-      failureNote: `session-briefing: lean-ctx hook codex-session-start returned invalid JSON — ${message}\n`,
-      outcome: 'error',
-    }
-  }
-}
-
-/**
- * Wrap briefing text in a host's native envelope.
- *
- * Per official docs where they differ from the reference tree:
- *  - Claude / Codex SessionStart (and any other event): `hookSpecificOutput.additionalContext`.
- *  - Cursor: flat `additional_context` — the reference's nested
- *    `hookSpecificOutput` shape for Cursor `UserPromptSubmit` is not part of
- *    Cursor's documented hook contract, so it is not ported here.
- *  - Kimi: bare stdout text (its `UserPromptSubmit` hook has no JSON envelope).
- *  - OpenCode: `{"advice": "..."}`, consumed by this repo's own OpenCode plugin.
- */
 function renderBriefing(host: HostId, event: string, text: string): string {
-  if (!text) return ''
   if (host === 'kimi') return `${text}\n`
   if (host === 'opencode') return JSON.stringify({ advice: text })
   if (host === 'cursor') return JSON.stringify({ additional_context: text })
   return JSON.stringify({ hookSpecificOutput: { hookEventName: event, additionalContext: text } })
 }
 
-export function createBriefingHandler(deps: { run: Runner }): HookHandler {
+export function createBriefingHandler(): HookHandler {
   return async (inv: HookInvocation): Promise<HookResult> => {
-    const { host, root, env } = inv
-    const payload = inv.payload
-    const event = inv.event ?? 'SessionStart'
-    const session = sessionId(payload)
-
-    if (alreadyDelivered(root, host, session)) {
+    const session = sessionId(inv.payload)
+    if (alreadyDelivered(inv.root, inv.host, session)) {
       inv.record?.({ reason: 'SKIP already delivered this session' })
       return { stdout: '', stderr: '', exitCode: 0 }
     }
-
-    const { text: base, failureNote, outcome } = await baseBriefing(deps.run, root, env, payload)
-    const warmup = await projectWarmupAppendix(deps.run, root, env, payload)
-    const text = composeBriefing(base, warmup)
-
-    markDelivered(root, host, session)
-    const reasons = { ok: 'PASS', timeout: 'TIMEOUT lean-ctx hook codex-session-start', error: 'ERROR lean-ctx hook codex-session-start' }
-    inv.record?.({
-      reason: reasons[outcome],
-      message: failureNote.trim(),
-      downstream: 'lean-ctx hook codex-session-start, lean-ctx overview, lean-ctx knowledge status',
-    })
-
-    return {
-      stdout: renderBriefing(host, event, text),
-      stderr: failureNote,
-      exitCode: 0,
-    }
+    markDelivered(inv.root, inv.host, session)
+    inv.record?.({ reason: 'PASS', downstream: 'static session briefing' })
+    return { stdout: renderBriefing(inv.host, inv.event ?? 'SessionStart', briefingText()), stderr: '', exitCode: 0 }
   }
 }
-
-/**
- * The production `Runner`: a real, timeout-enforcing subprocess via
- * `spawnWithTimeout` (see `../../lib/spawn-with-timeout.ts`) — replaces the
- * reference tree's `Bun.spawnSync`, which had no timeout and could hang the
- * calling agent host forever on a stuck `lean-ctx` child (gap #1). A timeout
- * degrades exactly like an ENOENT/failed spawn: `status: null` with the
- * reason on stderr, plus `timedOut: true` so callers can tell the two apart.
- */
-export const bunRunner: Runner = async (cmd, args, opts) => {
-  const timeoutMs = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS
-  try {
-    const result = await spawnWithTimeout(cmd, args, {
-      cwd: opts.cwd,
-      env: opts.env,
-      timeoutMs,
-      ...(opts.input !== undefined ? { stdin: opts.input } : {}),
-    })
-    if (result.timedOut) {
-      return {
-        status: null,
-        stdout: result.stdout,
-        stderr: result.stderr.trim() || `${cmd} timed out after ${timeoutMs}ms`,
-        timedOut: true,
-      }
-    }
-    return { status: result.exitCode, stdout: result.stdout, stderr: result.stderr }
-  } catch (error) {
-    const message = error instanceof Error ? error.message : String(error)
-    return { status: null, stdout: '', stderr: message }
-  }
-}
-
-export const handleBriefing: HookHandler = createBriefingHandler({ run: bunRunner })
-export default handleBriefing