@raidiant/notifai 0.3.0 → 0.5.0

package/src/file-lock.test.ts

@@ -0,0 +1,279 @@
+import { spawn, type ChildProcess } from 'node:child_process'
+import {
+  existsSync,
+  mkdirSync,
+  mkdtempSync,
+  readFileSync,
+  readdirSync,
+  rmSync,
+  statSync,
+  symlinkSync,
+  writeFileSync,
+} from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+import { describe, expect, it } from 'vitest'
+import { withFileLock, withTargetFileLock } from './file-lock.js'
+
+interface LockWorker {
+  child: ChildProcess
+  done: Promise<void>
+  pausedPath: string
+  continuePath: string
+  enteredPath: string
+  releasePath: string
+  waitsPath: string
+}
+
+interface LockWorkerOptions {
+  pauseAt?: string
+  action?: 'hold' | 'crash'
+}
+
+function waitCount(file: string): number {
+  try {
+    return Number(readFileSync(file, 'utf8'))
+  } catch {
+    return 0
+  }
+}
+
+async function waitUntil(predicate: () => boolean, timeoutMs = 10_000): Promise<void> {
+  const deadline = Date.now() + timeoutMs
+  while (!predicate()) {
+    if (Date.now() >= deadline) throw new Error('timed out waiting for file-lock worker')
+    await new Promise((resolve) => setTimeout(resolve, 5))
+  }
+}
+
+function lockWorker(
+  root: string,
+  lockPath: string,
+  id: string,
+  options: LockWorkerOptions = {},
+): LockWorker {
+  const marker = (name: string): string => path.join(root, `${id}-${name}`)
+  const pausedPath = marker('paused')
+  const continuePath = marker('continue')
+  const enteredPath = marker('entered')
+  const releasePath = marker('release')
+  const waitsPath = marker('waits')
+  const vitest = path.join(process.cwd(), 'node_modules', 'vitest', 'vitest.mjs')
+  const child = spawn(
+    process.execPath,
+    [vitest, 'run', 'src/file-lock-process-worker.test.ts', '--reporter=dot', '--maxWorkers=1'],
+    {
+      cwd: process.cwd(),
+      env: {
+        ...process.env,
+        NOTIFAI_FILE_LOCK_WORKER: id,
+        NOTIFAI_FILE_LOCK_PATH: lockPath,
+        NOTIFAI_FILE_LOCK_PAUSED: pausedPath,
+        NOTIFAI_FILE_LOCK_CONTINUE: continuePath,
+        NOTIFAI_FILE_LOCK_ENTERED: enteredPath,
+        NOTIFAI_FILE_LOCK_RELEASE: releasePath,
+        NOTIFAI_FILE_LOCK_WAITS: waitsPath,
+        NOTIFAI_FILE_LOCK_ACTION: options.action ?? 'hold',
+        ...(options.pauseAt === undefined
+          ? {}
+          : { NOTIFAI_FILE_LOCK_PAUSE_AT: options.pauseAt }),
+      },
+      stdio: ['ignore', 'pipe', 'pipe'],
+    },
+  )
+  const stdout: Buffer[] = []
+  const stderr: Buffer[] = []
+  child.stdout!.on('data', (chunk: Buffer) => stdout.push(chunk))
+  child.stderr!.on('data', (chunk: Buffer) => stderr.push(chunk))
+  const done = new Promise<void>((resolve, reject) => {
+    child.once('error', reject)
+    child.once('exit', (code, signal) => {
+      const expectedExit =
+        options.action === 'crash' ? code !== 0 || signal !== null : code === 0
+      if (expectedExit) resolve()
+      else {
+        reject(
+          new Error(
+            `file-lock worker ${id} exited ${String(code)}\n${Buffer.concat(stdout).toString()}\n${Buffer.concat(stderr).toString()}`,
+          ),
+        )
+      }
+    })
+  })
+  void done.catch(() => undefined)
+  return { child, done, pausedPath, continuePath, enteredPath, releasePath, waitsPath }
+}
+
+function stop(workers: LockWorker[]): void {
+  for (const worker of workers) {
+    if (worker.child.exitCode === null && worker.child.signalCode === null) worker.child.kill('SIGKILL')
+  }
+}
+
+describe('cross-process file lock', () => {
+  it('does not expose an ownerless publication window before acquisition is complete', async () => {
+    const root = mkdtempSync(path.join(os.tmpdir(), 'notifai-file-lock-'))
+    const lockPath = path.join(root, 'shared.lock')
+    const workers: LockWorker[] = []
+    try {
+      const first = lockWorker(root, lockPath, 'first', { pauseAt: 'choosing-published' })
+      workers.push(first)
+      await waitUntil(() => existsSync(first.pausedPath))
+
+      const published = readdirSync(lockPath)
+      expect(published).toHaveLength(1)
+      expect(published[0]).toMatch(/^choosing-\d+-[0-9a-f]+$/)
+      expect(statSync(path.join(lockPath, published[0]!)).size).toBe(0)
+
+      const second = lockWorker(root, lockPath, 'second')
+      workers.push(second)
+      await waitUntil(() => existsSync(second.pausedPath) && waitCount(second.waitsPath) > 0)
+      expect(existsSync(first.enteredPath)).toBe(false)
+      expect(existsSync(second.enteredPath)).toBe(false)
+
+      writeFileSync(first.continuePath, 'continue')
+      await waitUntil(() => existsSync(first.enteredPath) !== existsSync(second.enteredPath))
+
+      const winner = existsSync(first.enteredPath) ? first : second
+      const loser = winner === first ? second : first
+      const waitsBefore = waitCount(loser.waitsPath)
+      await waitUntil(() => {
+        if (existsSync(loser.enteredPath)) throw new Error('both lock actions overlapped')
+        return waitCount(loser.waitsPath) > waitsBefore
+      })
+
+      writeFileSync(winner.releasePath, 'release')
+      await waitUntil(() => existsSync(loser.enteredPath))
+      writeFileSync(loser.releasePath, 'release')
+      await Promise.all(workers.map(({ done }) => done))
+      expect(existsSync(lockPath)).toBe(false)
+    } finally {
+      stop(workers)
+      await Promise.allSettled(workers.map(({ done }) => done))
+      rmSync(root, { recursive: true, force: true })
+    }
+  }, 30_000)
+
+  it('cannot reap a successor after observing a dead owner', async () => {
+    const root = mkdtempSync(path.join(os.tmpdir(), 'notifai-file-lock-'))
+    const lockPath = path.join(root, 'shared.lock')
+    const workers: LockWorker[] = []
+    try {
+      const crashed = lockWorker(root, lockPath, 'crashed', { action: 'crash' })
+      workers.push(crashed)
+      await waitUntil(() => existsSync(crashed.enteredPath))
+      await crashed.done
+
+      const staleEntries = readdirSync(lockPath)
+      expect(staleEntries).toHaveLength(1)
+      expect(staleEntries[0]).toMatch(/^ticket-\d+-\d+-[0-9a-f]+$/)
+      const staleEntry = staleEntries[0]!
+
+      const delayedReaper = lockWorker(root, lockPath, 'delayed-reaper', {
+        pauseAt: 'stale-entry',
+      })
+      workers.push(delayedReaper)
+      await waitUntil(
+        () =>
+          existsSync(delayedReaper.pausedPath) &&
+          readFileSync(delayedReaper.pausedPath, 'utf8') === staleEntry,
+      )
+
+      const successor = lockWorker(root, lockPath, 'successor')
+      workers.push(successor)
+      await waitUntil(() => existsSync(successor.enteredPath))
+      const successorEntry = readdirSync(lockPath).find((entry) => entry.startsWith('ticket-'))
+      expect(successorEntry).toBeDefined()
+      expect(successorEntry).not.toBe(staleEntry)
+
+      writeFileSync(delayedReaper.continuePath, 'continue')
+      await waitUntil(() => {
+        if (existsSync(delayedReaper.enteredPath)) {
+          throw new Error('the delayed stale cleanup displaced the successor')
+        }
+        return waitCount(delayedReaper.waitsPath) > 0
+      })
+
+      writeFileSync(successor.releasePath, 'release')
+      await waitUntil(() => existsSync(delayedReaper.enteredPath))
+      writeFileSync(delayedReaper.releasePath, 'release')
+      await Promise.all([successor.done, delayedReaper.done])
+    } finally {
+      stop(workers)
+      await Promise.allSettled(workers.map(({ done }) => done))
+      rmSync(root, { recursive: true, force: true })
+    }
+  }, 30_000)
+})
+
+describe('target file transaction lock', () => {
+  it('refuses a symlinked target parent before publishing a contender', () => {
+    const root = mkdtempSync(path.join(os.tmpdir(), 'notifai-target-lock-'))
+    const foreign = path.join(root, 'foreign')
+    const linked = path.join(root, 'linked')
+    mkdirSync(foreign)
+    symlinkSync(foreign, linked)
+
+    expect(() => withTargetFileLock(path.join(linked, 'settings.json'), () => {})).toThrow(
+      /not a regular directory/,
+    )
+    expect(existsSync(path.join(foreign, '.settings.json.notifai.lock'))).toBe(false)
+  })
+
+  it('refuses a symlink posing as the lock rendezvous', () => {
+    const root = mkdtempSync(path.join(os.tmpdir(), 'notifai-target-lock-'))
+    const foreign = path.join(root, 'foreign')
+    const lock = path.join(root, '.settings.json.notifai.lock')
+    mkdirSync(foreign)
+    symlinkSync(foreign, lock)
+
+    expect(() => withTargetFileLock(path.join(root, 'settings.json'), () => {})).toThrow(
+      /not a regular directory/,
+    )
+  })
+
+  it('does not remove a replacement at its unique owned entry', () => {
+    const root = mkdtempSync(path.join(os.tmpdir(), 'notifai-target-lock-'))
+    const target = path.join(root, 'settings.json')
+    const lock = path.join(root, '.settings.json.notifai.lock')
+    let replacement = ''
+
+    expect(() =>
+      withTargetFileLock(target, () => {
+        const entry = readdirSync(lock)[0]!
+        replacement = path.join(lock, entry)
+        rmSync(replacement)
+        writeFileSync(replacement, 'replacement')
+      }),
+    ).toThrow(/changed while held/)
+    expect(readFileSync(replacement, 'utf8')).toBe('replacement')
+  })
+
+  it('preserves the action error when release also finds a replacement', () => {
+    const root = mkdtempSync(path.join(os.tmpdir(), 'notifai-target-lock-'))
+    const target = path.join(root, 'settings.json')
+    const lock = path.join(root, '.settings.json.notifai.lock')
+    const actionError = new Error('merge failed')
+
+    expect(() =>
+      withTargetFileLock(target, () => {
+        const entry = path.join(lock, readdirSync(lock)[0]!)
+        rmSync(entry)
+        writeFileSync(entry, 'replacement')
+        throw actionError
+      }),
+    ).toThrow(actionError)
+  })
+
+  it('refuses a symlink masquerading as a protocol entry', () => {
+    const root = mkdtempSync(path.join(os.tmpdir(), 'notifai-target-lock-'))
+    const lock = path.join(root, 'shared.lock')
+    const foreign = path.join(root, 'foreign')
+    mkdirSync(lock)
+    writeFileSync(foreign, 'leave me')
+    symlinkSync(foreign, path.join(lock, 'ticket-1-999999-deadbeef'))
+
+    expect(() => withFileLock(lock, () => {})).toThrow(/regular file-lock entry/)
+    expect(readFileSync(foreign, 'utf8')).toBe('leave me')
+  })
+})

package/src/file-lock.ts

@@ -0,0 +1,318 @@
+import { randomBytes } from 'node:crypto'
+import {
+  chmodSync,
+  closeSync,
+  fstatSync,
+  lstatSync,
+  mkdirSync,
+  openSync,
+  readdirSync,
+  renameSync,
+  rmdirSync,
+  unlinkSync,
+} from 'node:fs'
+import path from 'node:path'
+
+/**
+ * Serialize a short cross-process filesystem transaction.
+ *
+ * Each contender publishes all of its ownership in one unique filename. A
+ * two-phase bakery lock then orders live contenders by ticket and process
+ * identity. Because paths are never reused, recovering an entry left by a dead
+ * process cannot remove a later owner's entry; because process liveness, rather
+ * than age, decides recovery, a delayed holder is never mistaken for a dead one.
+ *
+ * Acquisition is deliberately bounded because both harness hooks and logging
+ * must fail open rather than hold an agent turn indefinitely.
+ */
+const FILE_LOCK_WAIT_MS = 1_000
+const FILE_LOCK_POLL_MS = 5
+const FILE_LOCK_TOKEN_BYTES = 12
+const ENTRY_PATTERN = /^(choosing|ticket-(\d+))-(\d+)-([0-9a-f]+)$/
+const lockSleep = new Int32Array(new SharedArrayBuffer(4))
+
+export type FileLockObservation =
+  | { phase: 'choosing-published'; entry: string }
+  | { phase: 'stale-entry'; entry: string }
+  | { phase: 'waiting'; blockers: string[] }
+
+interface FileLockOptions {
+  waitMs?: number
+  observe?: (observation: FileLockObservation) => void
+  /** Installer transactions report lock replacement after a successful action. */
+  strictRelease?: boolean
+}
+
+interface FileIdentity {
+  dev: number
+  ino: number
+}
+
+interface ChoosingEntry {
+  kind: 'choosing'
+  name: string
+  pid: number
+  token: string
+}
+
+interface TicketEntry {
+  kind: 'ticket'
+  name: string
+  pid: number
+  token: string
+  ticket: bigint
+}
+
+type LockEntry = ChoosingEntry | TicketEntry
+
+function parseEntry(name: string): LockEntry | null {
+  const match = ENTRY_PATTERN.exec(name)
+  if (match === null) return null
+  const pid = Number(match[3])
+  if (!Number.isSafeInteger(pid) || pid <= 0) return null
+  const token = match[4]!
+  if (match[1] === 'choosing') return { kind: 'choosing', name, pid, token }
+  try {
+    const ticket = BigInt(match[2]!)
+    if (ticket <= 0n) return null
+    return { kind: 'ticket', name, pid, token, ticket }
+  } catch {
+    return null
+  }
+}
+
+function processIsAlive(pid: number): boolean {
+  if (pid === process.pid) return true
+  try {
+    process.kill(pid, 0)
+    return true
+  } catch (err) {
+    const code = (err as NodeJS.ErrnoException).code
+    if (code === 'ESRCH') return false
+    // EPERM means the process exists but is owned by somebody else. Unknown
+    // failures are also treated as live: losing recovery is safer than allowing
+    // two holders into the transaction.
+    return true
+  }
+}
+
+function currentUid(): number | undefined {
+  return typeof process.getuid === 'function' ? process.getuid() : undefined
+}
+
+function assertOwnedDirectory(directory: string): FileIdentity {
+  const stat = lstatSync(directory)
+  if (stat.isSymbolicLink() || !stat.isDirectory()) {
+    throw new Error(`${directory} is not a regular directory; refusing to use it as a file lock.`)
+  }
+  const uid = currentUid()
+  if (uid !== undefined && stat.uid !== uid) {
+    throw new Error(`${directory} is owned by uid ${stat.uid}, not the current user.`)
+  }
+  return { dev: stat.dev, ino: stat.ino }
+}
+
+function assertSameDirectory(directory: string, expected: FileIdentity): void {
+  const current = lstatSync(directory)
+  if (
+    current.isSymbolicLink() ||
+    !current.isDirectory() ||
+    current.dev !== expected.dev ||
+    current.ino !== expected.ino
+  ) {
+    throw new Error(`${directory} changed while the file lock was active.`)
+  }
+}
+
+function sameIdentity(file: string, expected: FileIdentity): boolean {
+  try {
+    const current = lstatSync(file)
+    return current.dev === expected.dev && current.ino === expected.ino
+  } catch {
+    return false
+  }
+}
+
+/** Live protocol entries, pruning only unique paths whose process is gone. */
+function liveEntries(
+  directory: string,
+  directoryIdentity: FileIdentity,
+  observe: FileLockOptions['observe'],
+): LockEntry[] {
+  assertSameDirectory(directory, directoryIdentity)
+  const live: LockEntry[] = []
+  for (const name of readdirSync(directory)) {
+    const entry = parseEntry(name)
+    if (entry === null) continue
+    const entryPath = path.join(directory, name)
+    let stat
+    try {
+      stat = lstatSync(entryPath)
+    } catch (err) {
+      if ((err as NodeJS.ErrnoException).code === 'ENOENT') continue
+      throw err
+    }
+    const uid = currentUid()
+    if (stat.isSymbolicLink() || !stat.isFile() || (uid !== undefined && stat.uid !== uid)) {
+      throw new Error(`${entryPath} is not a current-user-owned regular file-lock entry.`)
+    }
+    if (processIsAlive(entry.pid)) {
+      live.push(entry)
+      continue
+    }
+    observe?.({ phase: 'stale-entry', entry: name })
+    try {
+      // Recheck the unique dead owner's inode so delayed recovery cannot reap
+      // a replacement published at the same path by external interference.
+      const current = lstatSync(entryPath)
+      if (current.dev === stat.dev && current.ino === stat.ino) unlinkSync(entryPath)
+    } catch {
+      // Another contender already recovered this exact dead owner's unique path.
+    }
+  }
+  return live
+}
+
+function publishEmpty(file: string): FileIdentity {
+  const handle = openSync(file, 'wx', 0o600)
+  try {
+    const stat = fstatSync(handle)
+    return { dev: stat.dev, ino: stat.ino }
+  } finally {
+    closeSync(handle)
+  }
+}
+
+function publishChoosing(
+  directory: string,
+  name: string,
+  deadline: number,
+  observe: FileLockOptions['observe'],
+): { file: string; fileIdentity: FileIdentity; directoryIdentity: FileIdentity } {
+  const file = path.join(directory, name)
+  for (;;) {
+    try {
+      mkdirSync(directory, { recursive: true, mode: 0o700 })
+      const directoryIdentity = assertOwnedDirectory(directory)
+      chmodSync(directory, 0o700)
+      // Recover before registration so a delayed stale cleanup can only name an
+      // old owner's unique path, never this contender's future one.
+      liveEntries(directory, directoryIdentity, observe)
+      const fileIdentity = publishEmpty(file)
+      assertSameDirectory(directory, directoryIdentity)
+      return { file, fileIdentity, directoryIdentity }
+    } catch (err) {
+      if ((err as NodeJS.ErrnoException).code !== 'ENOENT') throw err
+      // The previous holder removed an empty rendezvous directory between our
+      // mkdir and publication. Recreate it; once our entry exists, no cooperating
+      // releaser can remove the non-empty directory underneath us.
+      if (Date.now() >= deadline) {
+        throw new Error(`timed out publishing file lock contender in ${directory}`)
+      }
+      Atomics.wait(lockSleep, 0, 0, FILE_LOCK_POLL_MS)
+    }
+  }
+}
+
+function comesBefore(entry: TicketEntry, ticket: bigint, pid: number, token: string): boolean {
+  if (entry.ticket !== ticket) return entry.ticket < ticket
+  if (entry.pid !== pid) return entry.pid < pid
+  return entry.token < token
+}
+
+export function withFileLock<T>(file: string, action: () => T, options: FileLockOptions = {}): T {
+  const waitMs = options.waitMs ?? FILE_LOCK_WAIT_MS
+  const deadline = Date.now() + waitMs
+  const pid = process.pid
+  const token = randomBytes(FILE_LOCK_TOKEN_BYTES).toString('hex')
+  const choosingName = `choosing-${pid}-${token}`
+  let ownedPath: string | null = null
+  let ownedIdentity: FileIdentity | null = null
+  let directoryIdentity: FileIdentity | null = null
+  let operationFailed = false
+
+  try {
+    const published = publishChoosing(file, choosingName, deadline, options.observe)
+    ownedPath = published.file
+    ownedIdentity = published.fileIdentity
+    directoryIdentity = published.directoryIdentity
+    options.observe?.({ phase: 'choosing-published', entry: choosingName })
+    let highest = 0n
+    for (const entry of liveEntries(file, directoryIdentity, options.observe)) {
+      if (entry.kind === 'ticket' && entry.ticket > highest) highest = entry.ticket
+    }
+    const ticket = highest + 1n
+    const ticketName = `ticket-${ticket}-${pid}-${token}`
+    const ticketPath = path.join(file, ticketName)
+
+    // The rename is the doorway: observers see either a chooser or its complete
+    // ticket, never a gap in which a live contender has no published state.
+    renameSync(ownedPath, ticketPath)
+    ownedPath = ticketPath
+
+    for (;;) {
+      const blockers: string[] = []
+      for (const entry of liveEntries(file, directoryIdentity, options.observe)) {
+        if (entry.pid === pid && entry.token === token) continue
+        if (entry.kind === 'choosing' || comesBefore(entry, ticket, pid, token)) {
+          blockers.push(entry.name)
+        }
+      }
+      if (blockers.length === 0) {
+        assertSameDirectory(file, directoryIdentity)
+        return action()
+      }
+      options.observe?.({ phase: 'waiting', blockers })
+      if (Date.now() >= deadline) throw new Error(`timed out waiting for file lock ${file}`)
+      Atomics.wait(lockSleep, 0, 0, FILE_LOCK_POLL_MS)
+    }
+  } catch (err) {
+    operationFailed = true
+    throw err
+  } finally {
+    let releaseChanged = false
+    if (ownedPath !== null && ownedIdentity !== null) {
+      try {
+        if (sameIdentity(ownedPath, ownedIdentity)) unlinkSync(ownedPath)
+        else releaseChanged = true
+      } catch {
+        // External cleanup cannot turn a release failure into a caller failure.
+      }
+    }
+    try {
+      if (directoryIdentity !== null) assertSameDirectory(file, directoryIdentity)
+      rmdirSync(file)
+    } catch {
+      // Another contender has published, or external cleanup already removed it.
+    }
+    if (releaseChanged && options.strictRelease === true && !operationFailed) {
+      throw new Error(`${ownedPath ?? file} changed while held; refusing to remove the replacement.`)
+    }
+  }
+}
+
+/**
+ * Serialize a read/merge/write transaction for one user-owned target file.
+ *
+ * This is the single installer-facing lock policy: the target's direct parent
+ * is a real current-user-owned directory, remains the same inode throughout,
+ * and the bakery rendezvous lives beside the target rather than inside it.
+ */
+export function withTargetFileLock<T>(
+  target: string,
+  action: () => T,
+  options: Omit<FileLockOptions, 'strictRelease'> = {},
+): T {
+  const parent = path.dirname(target)
+  mkdirSync(parent, { recursive: true })
+  const parentIdentity = assertOwnedDirectory(parent)
+  const lockDirectory = path.join(parent, `.${path.basename(target)}.notifai.lock`)
+  return withFileLock(
+    lockDirectory,
+    () => {
+      assertSameDirectory(parent, parentIdentity)
+      return action()
+    },
+    { ...options, strictRelease: true },
+  )
+}

package/src/harnesses.test.ts

@@ -0,0 +1,34 @@
+import { describe, expect, it } from 'vitest'
+import { HARNESS_CAPABILITIES, HARNESSES } from './harnesses.js'
+
+describe('harness continuation contract', () => {
+  it('requires one explicit native delivery contract for every shipped harness', () => {
+    expect(Object.keys(HARNESS_CAPABILITIES).sort()).toEqual([...HARNESSES].sort())
+    expect(HARNESS_CAPABILITIES).toEqual({
+      'claude-code': {
+        stopContinuation: 'decision-block',
+        deliveryRoutes: ['hook-continuation', 'inbox-socket', 'cold-resume', 'hold-for-next-turn'],
+        deliveryContract:
+          'the Stop hook returns at once and waits out of band, then posts the answer into this same session over its own inbox socket; a session that has stopped is resumed only once a liveness probe proves it stopped',
+      },
+      codex: {
+        stopContinuation: 'decision-block',
+        deliveryRoutes: ['hook-continuation', 'cold-resume', 'hold-for-next-turn'],
+        deliveryContract:
+          'live Stop continuation while the turn is held; once it returns, a stopped thread is resumed behind its writer lock and anything else waits for the next turn',
+      },
+      cursor: {
+        stopContinuation: 'unsupported',
+        deliveryRoutes: ['unsupported'],
+        deliveryContract:
+          'the hook can return a live follow-up, but the invoking shell exposes no exact conversation id; asynchronous ask is unsupported',
+      },
+      opencode: {
+        stopContinuation: 'unsupported',
+        deliveryRoutes: ['unsupported'],
+        deliveryContract:
+          'no proven answer continuation after session.idle; use a blocking reply command',
+      },
+    })
+  })
+})

package/src/harnesses.ts

@@ -0,0 +1,57 @@
+/** Every harness Notifai ships. This is the sole source of the harness union. */
+export const HARNESSES = ['claude-code', 'codex', 'cursor', 'opencode'] as const
+
+export type Harness = (typeof HARNESSES)[number]
+
+export type DeliveryRoute =
+  | 'hook-continuation'
+  | 'inbox-socket'
+  | 'owned-control-plane'
+  | 'cold-resume'
+  | 'hold-for-next-turn'
+  | 'unsupported'
+
+export type StopContinuation =
+  | 'decision-block'
+  | 'followup-message'
+  | 'unsupported'
+
+export interface HarnessCapability {
+  /** How an answer is admitted to another turn in the already-open session. */
+  stopContinuation: StopContinuation
+  /** Available answer-delivery routes, best current route first. */
+  deliveryRoutes: readonly DeliveryRoute[]
+  /** Concise, honest readiness text for doctor and installation guidance. */
+  deliveryContract: string
+}
+
+/**
+ * Exhaustive runtime contract. Adding a harness without deciding every
+ * continuation joint is a type error, not a silently degraded notification.
+ */
+export const HARNESS_CAPABILITIES: Record<Harness, HarnessCapability> = {
+  'claude-code': {
+    stopContinuation: 'decision-block',
+    deliveryRoutes: ['hook-continuation', 'inbox-socket', 'cold-resume', 'hold-for-next-turn'],
+    deliveryContract:
+      'the Stop hook returns at once and waits out of band, then posts the answer into this same session over its own inbox socket; a session that has stopped is resumed only once a liveness probe proves it stopped',
+  },
+  codex: {
+    stopContinuation: 'decision-block',
+    deliveryRoutes: ['hook-continuation', 'cold-resume', 'hold-for-next-turn'],
+    deliveryContract:
+      'live Stop continuation while the turn is held; once it returns, a stopped thread is resumed behind its writer lock and anything else waits for the next turn',
+  },
+  cursor: {
+    stopContinuation: 'unsupported',
+    deliveryRoutes: ['unsupported'],
+    deliveryContract:
+      'the hook can return a live follow-up, but the invoking shell exposes no exact conversation id; asynchronous ask is unsupported',
+  },
+  opencode: {
+    stopContinuation: 'unsupported',
+    deliveryRoutes: ['unsupported'],
+    deliveryContract:
+      'no proven answer continuation after session.idle; use a blocking reply command',
+  },
+}