@amsterdamdatalabs/adl-agent-control-linux-x64 0.1.4

package/packages/agent-hooks/src/lean-ctx/env.ts

@@ -0,0 +1,106 @@
+/**
+ * Shared `LEAN_CTX_*` environment for every subprocess this package spawns
+ * into the global `lean-ctx` binary (installed fleet-wide on `PATH` by
+ * global-tools — see `../hooks/briefing/index.ts`'s header for why the
+ * binary itself is never repo-local here).
+ *
+ * `lean-ctx` reads four env vars to root its own config/data/state/cache
+ * per-invocation (confirmed directly against the real v3.9.20 binary via
+ * `strings` and `lean-ctx doctor --json`, this session, 2026-09-14 — they do
+ * not appear in `lean-ctx --help`'s documented list, which only advertises
+ * the unrelated `LEAN_CTX_DISABLED`/`LEAN_CTX_RAW`/... shell-hook toggles):
+ *
+ *   - `LEAN_CTX_CONFIG_DIR` — directly the app's own config dir (i.e. already
+ *     including the trailing `lean-ctx` segment, mirroring
+ *     `XDG_CONFIG_HOME/lean-ctx`'s resolved value, not `XDG_CONFIG_HOME`
+ *     itself) — `lean-ctx doctor --json` reports `config.toml exists` at
+ *     exactly `<this>/config.toml`.
+ *   - `LEAN_CTX_DATA_DIR`, `LEAN_CTX_STATE_DIR`, `LEAN_CTX_CACHE_DIR` — same
+ *     shape, for lean-ctx's data/state/cache.
+ *
+ * Verified end-to-end this session: pointing these four vars at
+ * `enact-m5`'s real `.agents/lean-ctx/{config/lean-ctx,data,state,cache}`
+ * (which carries a real `config.toml`) makes `lean-ctx doctor --json` report
+ * "Shell allowlist 249 command(s) enforced"; the same binary with these vars
+ * pointed at an empty scratch directory (no config.toml at all) reports 223 —
+ * proof the binary actually reads these vars to resolve its per-repo config,
+ * not just a coincidence of directory layout.
+ *
+ * HARDCUT (work item A.3): this replaces the plain `XDG_CONFIG_HOME`/
+ * `XDG_DATA_HOME`/`XDG_STATE_HOME`/`XDG_CACHE_HOME` vars `../hooks/briefing/index.ts`
+ * used to set for the same purpose — those are a generic Unix convention
+ * lean-ctx does not actually key its own dir resolution on (its shell-hook
+ * script derives ITS OWN unrelated `_LEAN_CTX_STATE_DIR` from
+ * `XDG_STATE_HOME`, but the compiled binary invoked here never consults it).
+ * Every call site that used to build its own `XDG_*` env now imports this
+ * one helper instead, so config/data/state/cache resolution for lean-ctx
+ * lives in exactly one place.
+ */
+
+import { existsSync, readFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+import { decodeConfig } from '../gating/config.ts'
+import { MARKER } from '../gating/root.ts'
+
+/**
+ * Repo-relative root every lean-ctx call's config/data/state/cache lives
+ * under, when `adl-config.toml`'s `[hooks] lean_ctx_dir` does not say
+ * otherwise.
+ */
+export const DEFAULT_LEAN_CTX_DIR = '.agents/lean-ctx'
+
+/**
+ * Resolve `[hooks] lean_ctx_dir` for `root`.
+ *
+ * Mirrors `../hooks/user-prompt-submit/handler.ts`'s `resolveSkillsDir`: an
+ * explicit key wins; a missing `adl-config.toml` falls back to the default
+ * (handlers are callable directly from tests, without the gating `main.ts`
+ * normally performs); a file that exists but fails to decode throws, so a
+ * typo'd key is a loud error rather than a silent revert to the default.
+ */
+export function resolveLeanCtxDir(root: string): string {
+  const configPath = join(root, MARKER)
+  if (!existsSync(configPath)) return DEFAULT_LEAN_CTX_DIR
+
+  const decoded = decodeConfig(readFileSync(configPath, 'utf8'))
+  if (!decoded.ok) {
+    throw new Error(`invalid ${configPath} at ${decoded.issue.pointer}: ${decoded.issue.message}`)
+  }
+
+  return decoded.value.hooks.leanCtxDir ?? DEFAULT_LEAN_CTX_DIR
+}
+
+/**
+ * Build the env for a `lean-ctx` subprocess rooted at repository `root`,
+ * merged over `base` (normally `inv.env`/`process.env`) so every other
+ * ambient var — `PATH` included — still reaches the child.
+ */
+export function leanCtxEnv(
+  root: string,
+  base: Readonly<Record<string, string | undefined>>,
+  leanCtxDir: string = DEFAULT_LEAN_CTX_DIR,
+): Record<string, string | undefined> {
+  return {
+    ...base,
+    LEAN_CTX_CONFIG_DIR: join(root, leanCtxDir, 'config/lean-ctx'),
+    LEAN_CTX_DATA_DIR: join(root, leanCtxDir, 'data'),
+    LEAN_CTX_STATE_DIR: join(root, leanCtxDir, 'state'),
+    LEAN_CTX_CACHE_DIR: join(root, leanCtxDir, 'cache'),
+  }
+}
+
+/**
+ * `leanCtxEnv` with the dir root read from `root`'s own `adl-config.toml`.
+ *
+ * Every production call site uses THIS rather than the pure form above, so
+ * the process that DECIDES and the process that ENFORCES derive their scope
+ * from one configured value — the single source of truth this module exists
+ * for, and the invariant G1 turned on.
+ */
+export function leanCtxEnvFor(
+  root: string,
+  base: Readonly<Record<string, string | undefined>>,
+): Record<string, string | undefined> {
+  return leanCtxEnv(root, base, resolveLeanCtxDir(root))
+}

package/packages/agent-hooks/src/lean-ctx/mcp.ts

@@ -0,0 +1,140 @@
+/**
+ * `adl hook lean-ctx mcp` (work item A.1): a true stdio-passthrough spawn
+ * of the global `lean-ctx mcp` server.
+ *
+ * This is fundamentally NOT a `HookHandler`: every other kind reads one JSON
+ * payload off stdin, decides something, and writes one JSON/text result —
+ * `main.ts`'s `run()` buffers stdin into a string and buffers a handler's
+ * whole stdout/stderr into a `HookResult` for exactly that shape. `lean-ctx
+ * mcp` is a long-running MCP server that speaks JSON-RPC continuously over
+ * stdin/stdout for the lifetime of the process; buffering either stream
+ * would break the protocol (and blocking on "read all of stdin first" would
+ * simply hang forever, since an MCP client never closes stdin). So `main.ts`
+ * dispatches `lean-ctx mcp` here directly, before it ever reads stdin as a
+ * JSON payload or checks `--host` — see `main.ts`'s own dispatch for exactly
+ * where this branches off.
+ *
+ * Two responsibilities:
+ *
+ *  1. `resolveLeanCtxMcpEnv` — walk from `cwd` to the git root and check for
+ *     `adl-config.toml` (`../gating/root.ts`'s `MARKER`), exactly
+ *     like every other kind's gating BUT with a different outcome on
+ *     failure: an unmanaged repo (no git root, or a git root with no
+ *     marker) still starts the MCP server — just with `lean-ctx`'s own
+ *     built-in defaults (no `LEAN_CTX_*` vars set at all) instead of this
+ *     repo's `.agents/lean-ctx/...` — plus a one-line stderr note. Every
+ *     other kind's gating treats "unmanaged" as "exit 0, do nothing"; that
+ *     is wrong here because an editor's MCP client expects the server it
+ *     just spawned to actually start, not silently exit.
+ *  2. `runLeanCtxMcp` — the real spawn: `stdin`/`stdout`/`stderr` all set to
+ *     `'inherit'` (Bun.spawn's true fd-passthrough, not a piped-and-copied
+ *     stream — no buffering, no JS-side copy loop that could stall or
+ *     reorder JSON-RPC frames), `SIGINT`/`SIGTERM` forwarded from this
+ *     process to the child so the MCP client's own shutdown signal reaches
+ *     `lean-ctx` instead of being swallowed by `adl hook`, and the child's
+ *     own exit code propagated back out as `main.ts`'s process exit code.
+ */
+
+import { join } from 'node:path'
+import { findGitRoot, MARKER, realRootIO, type RootIO } from '../gating/root.ts'
+import { leanCtxEnvFor } from './env.ts'
+
+export interface LeanCtxMcpEnvResult {
+  readonly env: Readonly<Record<string, string | undefined>>
+  /** Non-null only for an unmanaged repo — see this module's header. */
+  readonly note: string | null
+}
+
+/**
+ * Resolve the env `lean-ctx mcp` should run with, from `cwd` alone (there is
+ * no JSON payload for this subcommand — see this module's header). Injected
+ * `io` defaults to the real filesystem; tests supply a fake one, matching
+ * `../gating/root.ts`'s own `RootIO` pattern.
+ */
+export function resolveLeanCtxMcpEnv(
+  cwd: string,
+  baseEnv: Readonly<Record<string, string | undefined>>,
+  io: RootIO = realRootIO,
+): LeanCtxMcpEnvResult {
+  const { root } = findGitRoot(io, cwd)
+  const managed = root !== null && io.isFile(join(root, MARKER))
+
+  if (!managed || root === null) {
+    return {
+      env: { ...baseEnv },
+      note: `adl hook: lean-ctx mcp: no managed repo found from ${cwd} (missing ${MARKER}); starting lean-ctx with its own defaults\n`,
+    }
+  }
+
+  return { env: leanCtxEnvFor(root, baseEnv), note: null }
+}
+
+/** The minimal shape of `Bun.spawn`'s return value this module needs — narrowed so a test can inject a fake. */
+export interface SpawnedProcess {
+  readonly exited: Promise<number>
+  kill(signal?: number | NodeJS.Signals): void
+}
+
+export type SpawnMcp = (
+  cmd: readonly string[],
+  opts: { readonly cwd: string; readonly env: Record<string, string | undefined> },
+) => SpawnedProcess
+
+const defaultSpawn: SpawnMcp = (cmd, opts) =>
+  Bun.spawn(cmd as string[], {
+    cwd: opts.cwd,
+    env: opts.env as Record<string, string>,
+    stdin: 'inherit',
+    stdout: 'inherit',
+    stderr: 'inherit',
+  }) as unknown as SpawnedProcess
+
+/**
+ * Spawn `lean-ctx mcp` with fully inherited stdio, forward `SIGINT`/`SIGTERM`
+ * to it, and resolve with its exit code (never throws for a normal child
+ * exit — `main.ts` passes this straight to `process.exit`).
+ */
+export async function runLeanCtxMcp(
+  cwd: string,
+  baseEnv: Readonly<Record<string, string | undefined>>,
+  deps: {
+    readonly spawn?: SpawnMcp
+    readonly writeStderr?: (text: string) => void
+    readonly signalTarget?: NodeJS.Process
+    readonly io?: RootIO
+  } = {},
+): Promise<number> {
+  const spawn = deps.spawn ?? defaultSpawn
+  const writeStderr = deps.writeStderr ?? ((text: string) => process.stderr.write(text))
+  const signalTarget = deps.signalTarget ?? process
+
+  const { env, note } = resolveLeanCtxMcpEnv(cwd, baseEnv, deps.io ?? realRootIO)
+  if (note) writeStderr(note)
+
+  const child = spawn(['lean-ctx', 'mcp'], { cwd, env: env as Record<string, string | undefined> })
+
+  const onSigint = () => {
+    try {
+      child.kill('SIGINT')
+    } catch {
+      // already dead
+    }
+  }
+  const onSigterm = () => {
+    try {
+      child.kill('SIGTERM')
+    } catch {
+      // already dead
+    }
+  }
+  signalTarget.on('SIGINT', onSigint)
+  signalTarget.on('SIGTERM', onSigterm)
+
+  try {
+    const code = await child.exited
+    return code
+  } finally {
+    signalTarget.off('SIGINT', onSigint)
+    signalTarget.off('SIGTERM', onSigterm)
+  }
+}

package/packages/agent-hooks/src/lib/spawn-with-timeout.ts

@@ -0,0 +1,120 @@
+/**
+ * Timeout-enforcing subprocess spawn.
+ *
+ * `Bun.spawnSync` (what `enact-repo-controls`'s briefing/crg hooks used) has
+ * no timeout: a hung `lean-ctx`, `code-review-graph`, or embedding-model
+ * child blocks the calling hook — and therefore the host CLI's tool-use
+ * loop — forever. This wraps `Bun.spawn` (async) with a real wall-clock
+ * timeout: on expiry the child is killed and the call resolves rather than
+ * hangs, so a stuck child degrades the caller instead of freezing it.
+ *
+ * Not a generic process-pool abstraction — just the one shape every spawning
+ * hook here needs: run a command, capture stdout/stderr/exit code, and never
+ * wait longer than `timeoutMs`.
+ *
+ * Process-group kill (work item E): killing only the direct child is not
+ * enough — a child that forks a grandchild (e.g. a Python tool spawning a
+ * worker process) leaves that grandchild running after the direct child
+ * dies, still holding the inherited stdout/stderr pipes open, which hangs
+ * the `new Response(proc.stdout).text()` read below regardless of the kill
+ * (the read side only resolves once EVERY writer of the pipe has closed
+ * it). So the child is spawned `detached: true` (POSIX: `setsid()` — the
+ * child becomes its own process group leader, in its own session; Windows:
+ * `UV_PROCESS_DETACHED`), and on timeout the SIGNAL IS SENT TO THE WHOLE
+ * GROUP via `process.kill(-pid, signal)` (the POSIX convention: a negative
+ * pid targets that pid's process group) rather than to just the direct
+ * child — reaching any grandchild that stayed in the same group (the normal
+ * case for a forked child that never calls `setsid()`/`setpgid()` itself).
+ * `killProcessGroup` falls back to killing just the direct child when the
+ * group-kill call itself throws (e.g. on Windows, where POSIX process
+ * groups do not exist, or the pid is already gone) so the direct child is
+ * still always covered either way.
+ */
+
+export interface SpawnWithTimeoutResult {
+  readonly stdout: string
+  readonly stderr: string
+  readonly exitCode: number | null
+  readonly timedOut: boolean
+}
+
+export interface SpawnWithTimeoutOptions {
+  readonly cwd?: string
+  readonly env?: Readonly<Record<string, string | undefined>>
+  readonly timeoutMs: number
+  readonly stdin?: string
+}
+
+/** Grace period between SIGTERM and the follow-up SIGKILL, for a child that ignores SIGTERM. */
+const SIGKILL_GRACE_MS = 200
+
+/**
+ * Send `signal` to the whole process group `pid` leads (POSIX: negative pid
+ * addresses the group `setsid()` put the child in — see this file's header)
+ * so a forked grandchild dies too, not just the direct child. Falls back to
+ * signalling the direct pid alone when the group call itself throws (no
+ * POSIX process groups on this platform, or the process is already gone) —
+ * the direct child is covered either way.
+ */
+function killProcessGroup(pid: number, signal: 'SIGTERM' | 'SIGKILL'): void {
+  try {
+    process.kill(-pid, signal)
+  } catch {
+    try {
+      process.kill(pid, signal)
+    } catch {
+      // already dead
+    }
+  }
+}
+
+/**
+ * Run `cmd` with `args`, killing it if it has not exited within `timeoutMs`.
+ *
+ * On timeout, `exitCode` is `null` and `timedOut` is `true`; stdout/stderr
+ * carry whatever the child had already flushed. The child (and its whole
+ * process group — see this file's header) receives SIGTERM first and
+ * SIGKILL shortly after, so a process tree that ignores SIGTERM still
+ * cannot hang the caller.
+ */
+export async function spawnWithTimeout(
+  cmd: string,
+  args: readonly string[],
+  options: SpawnWithTimeoutOptions,
+): Promise<SpawnWithTimeoutResult> {
+  const proc = Bun.spawn([cmd, ...args], {
+    ...(options.cwd !== undefined ? { cwd: options.cwd } : {}),
+    ...(options.env !== undefined ? { env: options.env as Record<string, string> } : {}),
+    stdin: options.stdin !== undefined ? new TextEncoder().encode(options.stdin) : 'ignore',
+    stdout: 'pipe',
+    stderr: 'pipe',
+    // Own process group (see this file's header): lets a timeout kill reach
+    // a grandchild the direct child forked, not just the direct child.
+    detached: true,
+  })
+
+  let timedOut = false
+  const timer = setTimeout(() => {
+    timedOut = true
+    killProcessGroup(proc.pid, 'SIGTERM')
+    setTimeout(() => {
+      killProcessGroup(proc.pid, 'SIGKILL')
+    }, SIGKILL_GRACE_MS)
+  }, options.timeoutMs)
+
+  try {
+    const [stdout, stderr] = await Promise.all([
+      new Response(proc.stdout).text(),
+      new Response(proc.stderr).text(),
+      proc.exited,
+    ])
+    return {
+      stdout,
+      stderr,
+      exitCode: timedOut ? null : proc.exitCode,
+      timedOut,
+    }
+  } finally {
+    clearTimeout(timer)
+  }
+}

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

@@ -0,0 +1,230 @@
+/**
+ * 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 `tool-calls.log` writer keeps working. The module
+ * is generic across all five documented files so a caller never has to
+ * reinvent the format.
+ *
+ * - JSON Lines, one object per line. Fields are written in a fixed order;
+ *   an absent field is OMITTED, never null-filled.
+ * - Files live under `<repo>/.adl/logs/` (directory 0700, files 0600),
+ *   resolved from the git root of the caller's cwd. Outside a git repo,
+ *   logging falls back to `~/.local/state/adl/logs/` — logging location
+ *   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.
+ */
+import { spawnSync } from "node:child_process";
+import {
+  appendFileSync,
+  chmodSync,
+  existsSync,
+  mkdirSync,
+  renameSync,
+  statSync,
+  unlinkSync,
+  writeFileSync,
+} from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+
+export type LogFileName = "hooks" | "hooks-deny" | "tool-rewrites" | "tool-calls" | "repo-controls";
+
+export interface LogEntryInput {
+  /** Second column of every row: the host alone (`claude`, `codex`, `cursor`, `kimi`, `opencode`; `git` for git-hook rows). */
+  host?: string;
+  /** Third column: the hook kind (`pre-tool-use`, `lean-ctx:pre-tool-use`, `crg:session-stop`, `briefing`, …; the hook name for git rows; `adl-run` for `adl run` rows written by apps/cli). */
+  tool_call?: string;
+  session_id?: string;
+  /** The `adl run` dispatch (`ADL_RUN_ID`) when the row was produced inside one — one run_id per adl run dispatch, linking a host session back to it. `session_id` keeps the host's own id. */
+  run_id?: string;
+  agent?: string;
+  /** Where `agent` (or the effective identity a rewrite/deny decided on) came from — `inline` | `env` | `default-file` | `none`. Set only when an identity decision was actually made (`../hooks/contract.ts`'s `ActivityNote.identitySource`); absent for a row with no identity decision at all. Added 2026-09-28 (W2 build item 5) — never reuse the slot for another field. */
+  identity_source?: string;
+  human?: string;
+  event: string;
+  tool?: string;
+  decision?: string;
+  rule?: string;
+  /** The Azure DevOps target of a write (set by the tool-calls audit rows); hook rows leave it absent. */
+  target?: string;
+  command?: string;
+  result?: string | number;
+  duration_ms?: number;
+  /** Owning process pid; written by `adl run` session rows (apps/cli). */
+  pid?: number;
+  /** Parent pid of the owning process; written by `adl run` session rows (apps/cli). */
+  parent_pid?: number;
+  /**
+   * Path to the per-run transcript written by `adl run` when the run is
+   * non-interactive (`adl run -- <cmd>` or `adl run <surface> --headless
+   * "<prompt>"`). Absent for interactive surface runs (TUI) and for any
+   * line that does not begin a session. Added 2026-09-28 — never reuse
+   * the slot for another field.
+   */
+  transcript?: string;
+}
+
+export interface ResolvedLogDir {
+  dir: string;
+  fallback: boolean;
+}
+
+export interface WriteLogOptions {
+  /** Explicit logs directory; bypasses git-root resolution. Tests pass this. */
+  dir?: string;
+  /** cwd used to resolve the git root when `dir` is not given. */
+  cwd?: string;
+  /** Rotation threshold in bytes; defaults to 10 MiB. Tests inject a small value. */
+  maxBytes?: number;
+  /** Clock override for deterministic `ts` values in tests. */
+  now?: () => Date;
+}
+
+const DEFAULT_MAX_BYTES = 10 * 1024 * 1024;
+const MAX_BACKUPS = 5;
+const FIELD_ORDER: readonly (keyof LogEntryInput | "ts")[] = [
+  "ts",
+  "host",
+  "tool_call",
+  "session_id",
+  "run_id",
+  "agent",
+  "identity_source",
+  "human",
+  "event",
+  "tool",
+  "decision",
+  "rule",
+  "target",
+  "command",
+  "result",
+  "duration_ms",
+  "pid",
+  "parent_pid",
+  "transcript",
+];
+
+/** Repo root's `.adl/logs`, or the never-fails fallback under `~/.local/state/adl/logs`. */
+export function resolveLogDir(cwd: string = process.cwd()): ResolvedLogDir {
+  const result = spawnSync("git", ["rev-parse", "--show-toplevel"], { cwd, encoding: "utf8" });
+  if (result.status === 0 && result.stdout.trim().length > 0) {
+    return { dir: join(result.stdout.trim(), ".adl", "logs"), fallback: false };
+  }
+  return { dir: join(homedir(), ".local", "state", "adl", "logs"), fallback: true };
+}
+
+function tightenMode(path: string, target: number): void {
+  const current = statSync(path).mode & 0o777;
+  // Only ever tighten (remove bits outside `target`); never loosen a
+  // directory or file that is already stricter than the target.
+  if ((current & ~target) !== 0) {
+    chmodSync(path, target);
+  }
+}
+
+function ensureDirSecure(dir: string): void {
+  const parent = dirname(dir);
+  mkdirSync(parent, { recursive: true });
+  tightenMode(parent, 0o700);
+  mkdirSync(dir, { recursive: true });
+  tightenMode(dir, 0o700);
+}
+
+function ensureFileSecure(filePath: string): void {
+  if (!existsSync(filePath)) {
+    writeFileSync(filePath, "", { mode: 0o600 });
+  }
+  tightenMode(filePath, 0o600);
+}
+
+function rotate(filePath: string): void {
+  const dropped = `${filePath}.${MAX_BACKUPS}`;
+  if (existsSync(dropped)) unlinkSync(dropped);
+  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 (existsSync(filePath)) renameSync(filePath, `${filePath}.1`);
+}
+
+const USERINFO_RE = /(https?:\/\/)[^/\s:@]+:[^/\s@]+@/gi;
+// `[^\s'"]+` (not `\S+`) so a quoted value ("Bearer xyz") never eats the
+// closing quote (round 2 NIT 7 — the previous `\S+` did exactly that).
+const BEARER_RE = /\bBearer\s+[^\s'"]+/gi;
+const AUTH_HEADER_RE = /\bAuthorization:\s*[^\s'"]+(?:\s+[^\s'"]+)?/gi;
+const JWT_RE = /\b[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\b/g;
+
+/**
+ * Substrings that mark a `name=value` parameter or `--flag value` as
+ * secret-shaped. Substring, not exact-name, matching is deliberate (round 2
+ * BLOCKER 1: "prefer over-redaction to leaks") — an allowlist of exact names
+ * will always miss the next `*_key`/`*_auth`-style variant nobody
+ * anticipated. The tradeoff is documented over-redaction: `keyboard=1` and
+ * `author=Jane` are redacted too, because their names contain `key`/`auth`.
+ * A name with none of these substrings (`color=`, `size=`, `id=`, `query=`)
+ * is never touched.
+ */
+const SECRET_NAME_RE = /(?:token|secret|password|passwd|pwd|key|sig|credential|auth)/i;
+// One name=value shape covers BOTH a bare shell assignment (`API_TOKEN=…`)
+// and a URL query parameter (`?token=…`, `&access_token=…`): `?`/`&` are not
+// word characters, so `\b` still anchors correctly at the start of the name,
+// and excluding `&` from the value class stops at the next query parameter.
+const NAME_VALUE_RE = /\b([A-Za-z][A-Za-z0-9_-]*)=([^\s&'"]+)/g;
+// Long flags only (`--password xyz`) — never a short flag (`-p xyz`): round
+// 2 SHOULD-FIX 3 is explicit that `-p` must not be redacted just because it
+// might stand for "password".
+const SECRET_FLAG_RE = /(--[A-Za-z][A-Za-z0-9-]*)(\s+)([^\s'"]+)/g;
+
+/**
+ * Redacts, in order: URL userinfo, bearer tokens, `Authorization:` header
+ * values, JWT-shaped strings, secret-shaped `name=value` pairs (bare or in a
+ * URL query string), and secret-shaped `--flag value` pairs. Order matters
+ * only for overlapping matches (e.g. an `Authorization: Bearer …` header is
+ * fully covered either way).
+ */
+export function redact(input: string): string {
+  return input
+    .replace(USERINFO_RE, "$1[REDACTED]@")
+    .replace(BEARER_RE, "Bearer [REDACTED]")
+    .replace(AUTH_HEADER_RE, "Authorization: [REDACTED]")
+    .replace(JWT_RE, "[REDACTED]")
+    .replace(NAME_VALUE_RE, (match, name: string) => (SECRET_NAME_RE.test(name) ? `${name}=[REDACTED]` : match))
+    .replace(SECRET_FLAG_RE, (match, flag: string, space: string) =>
+      SECRET_NAME_RE.test(flag.slice(2)) ? `${flag}${space}[REDACTED]` : match,
+    );
+}
+
+function serialize(entry: LogEntryInput, ts: string): string {
+  const record: Record<string, string | number> = { ts };
+  for (const key of FIELD_ORDER) {
+    if (key === "ts") continue;
+    const value = entry[key as keyof LogEntryInput];
+    if (value === undefined) continue;
+    record[key] = key === "command" && typeof value === "string" ? redact(value) : value;
+  }
+  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`. */
+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`);
+  ensureFileSecure(filePath);
+
+  const currentSize = statSync(filePath).size;
+  if (currentSize + Buffer.byteLength(line, "utf8") > maxBytes) {
+    rotate(filePath);
+    ensureFileSecure(filePath);
+  }
+
+  appendFileSync(filePath, line, { mode: 0o600 });
+}