@lef237/hagumi 0.0.0-stage → 0.1.0

package/src/shell.ts

@@ -0,0 +1,215 @@
+// Reads a command line as the shell would, to find every program it would run.
+// This is for judging commands against the user's rules; the sandbox is what actually contains them.
+import { basename } from "node:path"
+
+type Token = { kind: "word" | "op"; text: string }
+
+// The simple commands a line would run, as argument lists, including those nested in substitutions,
+// `bash -c`, `eval`, `find -exec` and wrappers such as `env` or `xargs`. `opaque` is set when the line holds
+// anything whose effect cannot be read from its words: substitutions, loops, writes to files, scripts.
+export type Analysis = { commands: string[][]; opaque: boolean }
+
+const operators = ["&&", "||", "|&", ";;", ">>", "&>", "<<<", "<<", ">&", "<&", "|", "&", ";", "(", ")", "<", ">"]
+const separators = new Set(["&&", "||", "|&", ";;", "|", "&", ";", "(", ")"])
+const fileWrites = new Set([">", ">>", "&>"])
+const keywords = new Set(["!", "{", "}", "then", "else", "elif", "fi", "do", "done", "esac", "time"])
+const controls = new Set(["if", "for", "while", "until", "case", "select", "function"])
+const shells = new Set(["bash", "sh", "zsh", "dash", "ksh"])
+// Programs that run another program, with their options that take a value.
+const wrappers: Record<string, string[]> = {
+  env: ["-u", "-C", "-S"],
+  command: [],
+  builtin: [],
+  exec: ["-a"],
+  nohup: [],
+  stdbuf: [],
+  nice: ["-n"],
+  timeout: ["-s", "-k"],
+  sudo: ["-u", "-g", "-C", "-D", "-h", "-p", "-U", "-r", "-t"],
+  doas: ["-u", "-C"],
+  xargs: ["-I", "-n", "-P", "-L", "-s", "-E", "-d", "-a", "-J", "-R", "-S"],
+}
+
+export function analyze(line: string, depth = 0): Analysis {
+  if (depth > 3) return { commands: [], opaque: true }
+  const { tokens, nested, opaque: unreadable } = scan(line)
+  let opaque = unreadable || nested.length > 0
+  const commands: string[][] = []
+  let words: string[] = []
+  const endCommand = () => {
+    const found = commandsOf(words, depth)
+    commands.push(...found.commands)
+    opaque ||= found.opaque
+    words = []
+  }
+
+  for (let i = 0; i < tokens.length; i++) {
+    const token = tokens[i]!
+    if (token.kind === "word") words.push(token.text)
+    else if (separators.has(token.text)) endCommand()
+    else {
+      // A redirection: the next word is where it points, not an argument.
+      const target = tokens[i + 1]?.kind === "word" ? tokens[++i]!.text : ""
+      if (token.text === "<<") opaque = true
+      if (fileWrites.has(token.text) && target !== "/dev/null") opaque = true
+      if (token.text === ">&" && !/^\d+$/.test(target)) opaque = true
+    }
+  }
+  endCommand()
+  for (const script of nested) commands.push(...analyze(script, depth + 1).commands)
+  return { commands, opaque }
+}
+
+function commandsOf(words: string[], depth: number): Analysis {
+  let opaque = false
+  const commands: string[][] = []
+  let rest = words
+  const skip = (count: number) => {
+    rest = rest.slice(count)
+  }
+
+  // Keywords and variable assignments come before the program, not in its place.
+  while (rest[0] !== undefined && (keywords.has(rest[0]) || controls.has(rest[0]) || /^\w+=/.test(rest[0]))) {
+    if (controls.has(rest[0]) || /^\w+=/.test(rest[0])) opaque = true
+    skip(1)
+  }
+  while (rest[0] !== undefined && wrappers[basename(rest[0])]) {
+    const wrapper = basename(rest[0])
+    const takesValue = wrappers[wrapper]!
+    commands.push(rest)
+    if (wrapper === "env") opaque = true
+    skip(1)
+    while (rest[0] !== undefined && (rest[0].startsWith("-") || /^\w+=/.test(rest[0]))) {
+      skip(takesValue.includes(rest[0]) ? 2 : 1)
+    }
+    if (wrapper === "timeout") skip(1)
+  }
+  if (rest[0] === undefined) return { commands, opaque }
+
+  const program = basename(rest[0])
+  const argv = [program, ...rest.slice(1)]
+  commands.push(rest)
+  if (program.startsWith("$") || program === "source" || program === ".") opaque = true
+  if (shells.has(program) && argv.length > 1) {
+    opaque = true
+    const script = argv[argv.indexOf("-c") + 1]
+    if (argv.includes("-c") && script) commands.push(...analyze(script, depth + 1).commands)
+  }
+  if (program === "eval") {
+    opaque = true
+    commands.push(...analyze(argv.slice(1).join(" "), depth + 1).commands)
+  }
+  if (program === "find") {
+    argv.forEach((word, index) => {
+      if (!["-exec", "-execdir", "-ok", "-okdir"].includes(word)) return
+      const after = argv.slice(index + 1)
+      const end = after.findIndex((part) => part === ";" || part === "+")
+      commands.push(...commandsOf(end < 0 ? after : after.slice(0, end), depth).commands)
+    })
+  }
+  return { commands, opaque }
+}
+
+// Splits a line into words and operators as the shell does, and collects the scripts nested in
+// $(...), `...`, <(...) and >(...).
+function scan(line: string): { tokens: Token[]; nested: string[]; opaque: boolean } {
+  const tokens: Token[] = []
+  const nested: string[] = []
+  let opaque = false
+  let word: string | undefined
+  const add = (text: string) => {
+    word = (word ?? "") + text
+  }
+  const flush = () => {
+    if (word !== undefined) tokens.push({ kind: "word", text: word })
+    word = undefined
+  }
+  // Records a nested script starting at `start`, and returns the index of its closing character.
+  const substitution = (start: number, close: ")" | "`"): number => {
+    const end = closing(line, start, close)
+    nested.push(line.slice(start, end))
+    if (end >= line.length) opaque = true
+    return end
+  }
+
+  let i = 0
+  while (i < line.length) {
+    const c = line[i]!
+    if (c === "\\") {
+      if (line[i + 1] !== "\n") add(line[i + 1] ?? "")
+      i += 2
+    } else if (c === "'") {
+      const end = line.indexOf("'", i + 1)
+      if (end < 0) opaque = true
+      add(line.slice(i + 1, end < 0 ? undefined : end))
+      i = end < 0 ? line.length : end + 1
+    } else if (c === '"') {
+      add("")
+      i++
+      while (i < line.length && line[i] !== '"') {
+        if (line[i] === "\\" && '"\\$`'.includes(line[i + 1] ?? "")) {
+          add(line[i + 1]!)
+          i += 2
+        } else if (line.startsWith("$(", i) || line[i] === "`") {
+          const start = line[i] === "`" ? i + 1 : i + 2
+          const end = substitution(start, line[i] === "`" ? "`" : ")")
+          add(line.slice(i, end + 1))
+          i = end + 1
+        } else {
+          add(line[i]!)
+          i++
+        }
+      }
+      if (i >= line.length) opaque = true
+      i++
+    } else if (line.startsWith("$(", i) || line.startsWith("<(", i) || line.startsWith(">(", i) || c === "`") {
+      const start = c === "`" ? i + 1 : i + 2
+      const end = substitution(start, c === "`" ? "`" : ")")
+      add(line.slice(i, end + 1))
+      i = end + 1
+    } else if (c === "\n") {
+      flush()
+      tokens.push({ kind: "op", text: ";" })
+      i++
+    } else if (c === " " || c === "\t") {
+      flush()
+      i++
+    } else if (c === "#" && word === undefined) {
+      const end = line.indexOf("\n", i)
+      i = end < 0 ? line.length : end
+    } else {
+      const op = operators.find((candidate) => line.startsWith(candidate, i))
+      if (!op) {
+        add(c)
+        i++
+        continue
+      }
+      // A file descriptor written right before a redirection belongs to it, as in 2>&1.
+      if (word !== undefined && /^\d+$/.test(word) && /[<>]/.test(op)) word = undefined
+      flush()
+      tokens.push({ kind: "op", text: op })
+      i += op.length
+    }
+  }
+  flush()
+  return { tokens, nested, opaque }
+}
+
+function closing(line: string, start: number, close: ")" | "`"): number {
+  if (close === "`") {
+    const end = line.indexOf("`", start)
+    return end < 0 ? line.length : end
+  }
+  let depth = 1
+  for (let i = start; i < line.length; i++) {
+    const c = line[i]
+    if (c === "\\") i++
+    else if (c === "'") {
+      const end = line.indexOf("'", i + 1)
+      if (end < 0) return line.length
+      i = end
+    } else if (c === "(") depth++
+    else if (c === ")" && --depth === 0) return i
+  }
+  return line.length
+}

package/src/store.ts

@@ -0,0 +1,46 @@
+import { constants } from "node:fs"
+import { lstat, mkdir, open, rename, unlink, writeFile } from "node:fs/promises"
+import { basename, dirname, join } from "node:path"
+
+export async function readJson<T>(path: string): Promise<T | undefined> {
+  const file = Bun.file(path)
+  return (await file.exists()) ? ((await file.json()) as T) : undefined
+}
+
+export async function writeJson(path: string, value: unknown): Promise<void> {
+  await mkdir(dirname(path), { recursive: true })
+  await writeFile(path, `${JSON.stringify(value, null, 2)}\n`)
+}
+
+// Finish and sync a private file before atomically replacing the old credentials.
+export async function writeSecret(path: string, value: unknown): Promise<void> {
+  const text = JSON.stringify(value, null, 2)
+  if (text === undefined) throw new Error("Credentials must be JSON data")
+  const dir = dirname(path)
+  await mkdir(dir, { recursive: true, mode: 0o700 })
+  const directory = await open(dir, constants.O_RDONLY | constants.O_DIRECTORY | constants.O_NOFOLLOW)
+  try {
+    await directory.chmod(0o700)
+  } finally {
+    await directory.close()
+  }
+  const existing = await lstat(path).catch((error) => {
+    if (error.code === "ENOENT") return undefined
+    throw error
+  })
+  if (existing && (!existing.isFile() || existing.nlink !== 1)) throw new Error("Credentials must be a regular file with one link")
+  const temporary = join(dir, `.${basename(path)}.${crypto.randomUUID()}.tmp`)
+  const file = await open(temporary, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, 0o600)
+  try {
+    try {
+      await file.chmod(0o600)
+      await file.writeFile(`${text}\n`)
+      await file.sync()
+    } finally {
+      await file.close()
+    }
+    await rename(temporary, path)
+  } finally {
+    await unlink(temporary).catch((error) => { if (error.code !== "ENOENT") throw error })
+  }
+}

package/src/terminal.ts

@@ -0,0 +1,254 @@
+// Everything that talks to the terminal: reading lines and secrets, and showing turns and changes.
+import { homedir } from "node:os"
+import { basename } from "node:path"
+import { createInterface, type Interface } from "node:readline"
+import { type Board, boardFrom } from "./board"
+import type { TurnEvent } from "./conversation"
+import { type DiffLine, hunk } from "./diff"
+import { type FaceSet, withFace } from "./faces"
+import { Problem, t } from "./i18n"
+import type { Verdict } from "./policy"
+import type { ApprovalRequest, Change, ToolContext } from "./tools"
+
+const shownDiffLines = 40
+const tty = process.stdout.isTTY
+
+// Shows a turn as it happens. The face follows along: thinking while the model works on a reply,
+// working on a tool, troubled by a failure; a reply after good work comes with a happy face.
+export async function show(events: AsyncIterable<TurnEvent>, faces: FaceSet): Promise<void> {
+  let midLine = false
+  let thinking = false
+  let replying = false
+  let worked = false
+  let stumbled = false
+  // Text and tool work are set apart by a blank line, and so is the turn from the line the user typed;
+  // tool calls in a row stay together.
+  let part: "text" | "tools" | undefined
+  // The thinking face is a placeholder on the current line, wiped once something real arrives.
+  const settle = () => {
+    if (thinking) process.stdout.write("\r\x1b[2K")
+    thinking = false
+  }
+  const line = (content: string) => {
+    settle()
+    if (midLine) process.stdout.write("\n")
+    console.log(content)
+    midLine = false
+    replying = false
+  }
+  const enter = (next: "text" | "tools") => {
+    if (part === next) return
+    settle()
+    process.stdout.write(midLine ? "\n\n" : "\n")
+    midLine = false
+    replying = false
+    part = next
+  }
+
+  for await (const event of events) {
+    if (event.kind === "thinking") {
+      replying = false
+      if (tty && !midLine && !thinking) {
+        process.stdout.write(faces.thinking)
+        thinking = true
+      }
+    } else if (event.kind === "text") {
+      enter("text")
+      settle()
+      if (!replying) process.stdout.write(withFace(stumbled ? faces.troubled : worked ? faces.happy : faces.replying, ""))
+      replying = true
+      process.stdout.write(event.delta)
+      midLine = !event.delta.endsWith("\n")
+    } else if (event.kind === "compacted") {
+      enter("tools")
+      line(dim(t.compacted(event.outputs)))
+    } else if (event.kind === "tool_call") {
+      enter("tools")
+      const board = event.call.name === "board" ? boardIn(event.call.arguments) : undefined
+      line(withFace(faces.working, board ? `→ board\n${boardChange(board)}` : `→ ${event.call.name} ${clip(event.call.arguments, 80)}`))
+    } else if (event.ok) {
+      worked = true
+    } else {
+      stumbled = true
+      line(withFace(faces.troubled, `✗ ${event.call.name}`))
+    }
+  }
+  settle()
+}
+
+// A board in the user's language, each column with its items.
+export function boardView(board: Board): string {
+  return (["doing", "todo", "done"] as const)
+    .filter((column) => board[column].length > 0)
+    .map((column) => [`${t.boardColumns[column]}:`, ...board[column].map((item) => `  - ${item}`)].join("\n"))
+    .join("\n")
+}
+
+// One project in the list: its name, what it is doing, and what comes next.
+export function projectLine(workspace: string, board: Board): string {
+  return [
+    basename(workspace),
+    ...(board.doing[0] ? [t.boardNow(clip(board.doing[0], 24))] : []),
+    ...(board.todo[0] ? [t.boardNext(clip(board.todo[0], 24))] : []),
+  ].join("  ")
+}
+
+// What the board says now, in a few lines: what is being done, what comes next, and the newest work done.
+function boardChange(board: Board): string {
+  return [
+    ...(["doing", "todo"] as const)
+      .filter((column) => board[column].length > 0)
+      .map((column) => `  ${t.boardColumns[column]}: ${board[column].join(" / ")}`),
+    ...(board.done[0] ? [`  ${t.boardColumns.done}: ${board.done[0]}`] : []),
+  ].join("\n")
+}
+
+// The board the model wrote, when its arguments read as one.
+function boardIn(args: string): Board | undefined {
+  try {
+    return boardFrom(JSON.parse(args))
+  } catch {
+    return undefined
+  }
+}
+
+// A path as people write it, with the home directory as ~.
+export function tilde(path: string): string {
+  const home = homedir()
+  return path === home || path.startsWith(`${home}/`) ? `~${path.slice(home.length)}` : path
+}
+
+export function dim(text: string): string {
+  return tty ? `\x1b[2m${text}\x1b[0m` : text
+}
+
+// The chat's one reader of the terminal. A pending question takes the next line; other lines queue up
+// as messages, and Ctrl+D ends the chat once the current message is done.
+export function chatInput(input: Interface) {
+  const prompt = input.getPrompt()
+  let answer: ((line: string) => void) | undefined
+  return {
+    question(asked: string): Promise<string> {
+      return new Promise((resolve) => {
+        answer = resolve
+        input.setPrompt(asked)
+        input.prompt()
+      })
+    },
+    async each(handle: (line: string) => Promise<void>): Promise<void> {
+      let queue = Promise.resolve()
+      let closed = false
+      input.on("line", (line) => {
+        if (answer) {
+          const resolve = answer
+          answer = undefined
+          input.setPrompt(prompt)
+          resolve(line)
+          return
+        }
+        queue = queue.then(async () => {
+          await handle(line)
+          if (!closed) input.prompt()
+        })
+      })
+      input.prompt()
+      await new Promise((resolve) => input.once("close", resolve))
+      closed = true
+      // A question left open by Ctrl+D is answered with nothing, which declines.
+      answer?.("")
+      await queue
+    },
+  }
+}
+
+// One question outside a chat. Without a terminal there is no one to answer, so the answer is empty.
+export async function askOnce(prompt: string): Promise<string> {
+  if (!process.stdin.isTTY) {
+    console.log(t.noTerminal)
+    return ""
+  }
+  const input = createInterface({ input: process.stdin, output: process.stdout })
+  const answer = await new Promise<string>((resolve) => input.question(prompt, resolve))
+  input.close()
+  return answer
+}
+
+// Shows each action and asks for approval. "a" approves the same tool for the rest of the session;
+// what it does is still shown.
+export function approver(question: (prompt: string) => Promise<string>, faces: FaceSet): ToolContext["approve"] {
+  const always = new Set<string>()
+  return async (request) => {
+    showRequest(request)
+    if (always.has(request.tool)) {
+      console.log(t.approvedForSession)
+      return true
+    }
+    const answer = (await question(withFace(faces.waiting, t.approve))).trim().toLowerCase()
+    if (answer === "a") always.add(request.tool)
+    return answer === "y" || answer === "a"
+  }
+}
+
+// What the user's rules decided without asking.
+export function notice(request: ApprovalRequest, verdict: Verdict): void {
+  showRequest(request)
+  if (verdict.kind === "allow") console.log(t.allowedByRule(verdict.rules.join(", ")))
+  if (verdict.kind === "deny") console.log(t.deniedByRule(verdict.rule))
+}
+
+function showRequest(request: ApprovalRequest): void {
+  if ("change" in request) return showChange(request.tool, request.change)
+  console.log(t.commandHeader(request.command))
+}
+
+function showChange(tool: string, change: Change): void {
+  console.log(t.changeHeader(tool, change.path, change.before === undefined))
+  const lines = hunk(change.before, change.after)
+  for (const line of lines.slice(0, shownDiffLines)) console.log(colored(line))
+  if (lines.length > shownDiffLines) console.log(t.moreLines(lines.length - shownDiffLines))
+}
+
+function colored({ mark, text }: DiffLine): string {
+  const content = `    ${mark} ${text}`
+  if (!process.stdout.isTTY) return content
+  const color = { "-": 31, "+": 32, " ": 2 }[mark]
+  return `\x1b[${color}m${content}\x1b[0m`
+}
+
+// Reads one line without echoing it, so that keys do not stay on the screen.
+export async function readSecret(question: string): Promise<string> {
+  process.stdout.write(question)
+  if (!process.stdin.isTTY) {
+    const value = (await Bun.stdin.text()).trim()
+    process.stdout.write("\n")
+    return value
+  }
+  process.stdin.setRawMode(true)
+  let value = ""
+  try {
+    for await (const chunk of process.stdin) {
+      for (const char of String(chunk)) {
+        if (char === "\u0003") throw new Problem("cancelled")
+        if (char === "\r" || char === "\n") return value.trim()
+        value = char === "\u007f" ? value.slice(0, -1) : value + char
+      }
+    }
+    return value.trim()
+  } finally {
+    process.stdin.setRawMode(false)
+    process.stdout.write("\n")
+  }
+}
+
+export function report(error: unknown): void {
+  console.error(error instanceof Problem ? t.problem[error.key](error.detail) : error)
+}
+
+export function openBrowser(url: string): void {
+  const opener = process.platform === "darwin" ? "open" : Bun.which("xdg-open")
+  if (opener) Bun.spawn([opener, url], { stdout: "ignore", stderr: "ignore" })
+}
+
+function clip(text: string, length: number): string {
+  return text.length > length ? `${text.slice(0, length - 1)}…` : text
+}

package/src/tools/bash.ts

@@ -0,0 +1,46 @@
+import type { Tool } from "."
+import { judge } from "../policy"
+import { type CommandResult, runSandboxed } from "../sandbox"
+
+const defaultTimeout = 120
+const maxTimeout = 600
+
+export const bash: Tool = {
+  name: "bash",
+  kind: "act",
+  description:
+    "Run a shell command with bash in the working directory. It can read outside the working directory, " +
+    "except blocked credential locations such as ~/.ssh and hagumi's storage directory. Other sensitive files are not automatically hidden. " +
+    "Read an outside path only when the user explicitly requests it. It runs in a sandbox: it can write to " +
+    "the working directory and temporary directories and cannot use the network. " +
+    `Commands follow the user's allow/deny rules and approval. It stops after timeout_seconds (default ${defaultTimeout}).`,
+  parameters: {
+    type: "object",
+    properties: {
+      command: { type: "string", description: "The command line, run with bash -c." },
+      timeout_seconds: { type: "integer", minimum: 1, maximum: maxTimeout },
+    },
+    required: ["command"],
+    additionalProperties: false,
+  },
+  async plan(input, context) {
+    const command = String(input.command)
+    const timeoutSeconds = Math.min(Number(input.timeout_seconds ?? defaultTimeout), maxTimeout)
+    return {
+      request: { tool: "bash", command },
+      verdict: judge(command, context.rules),
+      perform: async () =>
+        describe(await runSandboxed({ command, workspace: context.workspace, timeoutSeconds }), timeoutSeconds),
+    }
+  },
+}
+
+function describe(result: CommandResult, timeoutSeconds: number): string {
+  return [
+    result.timedOut ? `Stopped after ${timeoutSeconds} seconds.` : `Exit code: ${result.exitCode}`,
+    result.stdout && `stdout:\n${result.stdout}`,
+    result.stderr && `stderr:\n${result.stderr}`,
+  ]
+    .filter(Boolean)
+    .join("\n")
+}

package/src/tools/board.ts

@@ -0,0 +1,34 @@
+import type { Tool } from "."
+import { boardFrom, writeBoard } from "../board"
+import { boardRule } from "../prompt"
+
+const column = (description: string) => ({ type: "array", items: { type: "string" }, description })
+
+// Keeps the board of this project as the work moves, without asking: it is hagumi's own note of the work,
+// shown on the screen at every change (docs/concept.md §6.1).
+export const board: Tool = {
+  name: "board",
+  kind: "look",
+  description: [
+    "Keep the board of this project: what you are doing now, what to do next with the most important first, and what is done.",
+    boardRule,
+    "Write the whole board each time, as it stands now, so that the work can be picked up in a later session.",
+    "Skip it for a quick question with no steps. Write each item as one short line, in the language you are speaking.",
+  ].join(" "),
+  parameters: {
+    type: "object",
+    properties: {
+      doing: column("What you are doing now."),
+      todo: column("What to do next, most important first."),
+      done: column("What is done, newest first."),
+    },
+    required: ["doing", "todo", "done"],
+    additionalProperties: false,
+  },
+  async run(input, context) {
+    const board = boardFrom(input)
+    if (!board) throw new Error("Write doing, todo and done as lists of short lines.")
+    await writeBoard(context.workspace, board, context.boards)
+    return "The board is kept."
+  },
+}

package/src/tools/change.ts

@@ -0,0 +1,79 @@
+// Changes to files: planned by a tool, approved by the user, then written here.
+import { type BigIntStats, constants, fstatSync, ftruncateSync, readFileSync, statSync, writeSync } from "node:fs"
+import { type FileHandle, mkdir, open, realpath } from "node:fs/promises"
+import { dirname, relative, sep } from "node:path"
+import type { ToolContext } from "."
+import { fingerprint, resolveInWorkspace } from "./workspace"
+
+// `before` is undefined for a new file.
+export type Change = { path: string; target: string; before: string | undefined; version?: string; after: string }
+
+// A file's identity and revision, without losing precision for inode numbers or timestamps.
+function version(state: BigIntStats): string {
+  if (!state.isFile() || state.nlink !== 1n) throw new Error("Changes require a regular file with only one hard link")
+  return `${state.dev}:${state.ino}:${state.size}:${state.mtimeNs}:${state.ctimeNs}`
+}
+
+// Resolves where a change would land, and what is there now.
+export async function current(path: string, context: ToolContext): Promise<Omit<Change, "after">> {
+  const target = await resolveInWorkspace(path, context.workspace)
+  // Git runs hooks from here; nothing the model writes should land in it.
+  const fromRoot = relative(await realpath(context.workspace), target)
+  if (fromRoot.split(sep).includes(".git")) throw new Error(`${path} is inside .git`)
+  const file = await open(target, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK).catch((error) => {
+    if (error.code === "ENOENT") return undefined
+    throw error
+  })
+  if (!file) return { path, target, before: undefined }
+
+  // A file is changed only as the model last read it, so that no one's edits are lost.
+  try {
+    const stamp = version(await file.stat({ bigint: true }))
+    const before = await file.readFile("utf8")
+    if (target !== await resolveInWorkspace(path, context.workspace) || version(statSync(target, { bigint: true })) !== stamp ||
+        version(await file.stat({ bigint: true })) !== stamp || context.seen.get(target) !== fingerprint(before)) {
+      throw new Error(`Read ${path} first: it has not been read in this session, or it changed since`)
+    }
+    return { path, target, before, version: stamp }
+  } finally {
+    await file.close()
+  }
+}
+
+export async function apply(change: Change, context: ToolContext): Promise<string> {
+  const changed = () => new Error(`Read ${change.path} again: it changed while awaiting approval`)
+  let file: FileHandle | undefined
+  try {
+    const latest = await current(change.path, context)
+    if (latest.target !== change.target || latest.before !== change.before || latest.version !== change.version) throw changed()
+    await mkdir(dirname(change.target), { recursive: true })
+    if (await resolveInWorkspace(change.path, context.workspace) !== change.target) throw changed()
+
+    // Never truncate on open. A new file must not exist; an existing file must still be the approved inode.
+    const flags = constants.O_RDWR | constants.O_NOFOLLOW | constants.O_NONBLOCK |
+      (change.before === undefined ? constants.O_CREAT | constants.O_EXCL : 0)
+    file = await open(change.target, flags)
+    if (await resolveInWorkspace(change.path, context.workspace) !== change.target) throw changed()
+    const state = fstatSync(file.fd, { bigint: true })
+    const stamp = version(state)
+    if (change.before === undefined ? state.size !== 0n : stamp !== change.version || readFileSync(file.fd, "utf8") !== change.before) throw changed()
+    if (version(fstatSync(file.fd, { bigint: true })) !== stamp || version(statSync(change.target, { bigint: true })) !== stamp) throw changed()
+
+    // Write to the checked descriptor at explicit offsets, with no async gap after the final checks.
+    const content = Buffer.from(change.after)
+    for (let offset = 0; offset < content.length;) {
+      const written = writeSync(file.fd, content, offset, content.length - offset, offset)
+      if (written === 0) throw new Error(`Could not finish writing ${change.path}`)
+      offset += written
+    }
+    ftruncateSync(file.fd, content.length)
+  } catch (error) {
+    context.seen.delete(change.target)
+    throw error
+  } finally {
+    await file?.close()
+  }
+  context.seen.set(change.target, fingerprint(change.after))
+  const lines = change.after.split("\n").length
+  return `${change.before === undefined ? "Created" : "Updated"} ${change.path} (${lines} lines)`
+}