weir-harness 1.2.2 → 2.0.0

package/src/edit-lock/publisher.js

@@ -1,191 +0,0 @@
-import { lstatSync } from 'node:fs'
-import { dirname, isAbsolute, join, relative, resolve as resolvePath } from 'node:path'
-import { createResourceIdentity } from './resource-identity.js'
-import { canonicalRequestData } from './request-data.js'
-
-/** Bind the original host filesystem once; never substitute a Node write fallback.
- * The trusted host owns policy provenance, execution authentication, exclusive
- * manager lifetime and exclusion of external topology writers.
- * @param {{manager: ReturnType<typeof import('./manager.js').createEditLockManager>,
- * fs: {resolve: (path: string, options: {cwd: string}) => Promise<any>, writeText: (...args: any[]) => Promise<{version: string}>}, root: string, excluded?: string[], assertExclusive?: () => void}} options */
-export function createPublisher({ manager, fs, root, excluded = [], assertExclusive = () => {} }) {
-  if (!isAbsolute(root)) throw new Error('absolute domain root required')
-  const resolve = fs.resolve.bind(fs)
-  const writeText = fs.writeText.bind(fs)
-  const identity = createResourceIdentity()
-  /** @type {WeakMap<object, () => void>} */
-  const listeners = new WeakMap()
-  /** @param {string} path */
-  function contained(path) {
-    const suffix = relative(root, path)
-    if (suffix === '..' || suffix.startsWith('../') || isAbsolute(suffix)) throw new Error('outside management domain')
-    for (const protectedPath of excluded) {
-      const inner = relative(protectedPath, path)
-      if (inner === '' || (!inner.startsWith('..') && !isAbsolute(inner))) throw new Error('Edit Lock authority files are not editable')
-    }
-  }
-  return Object.freeze({
-    /** Canonical identity of one existing in-domain regular file; never a
-     * creation key and never a permission. @param {string} path @param {string} cwd */
-    resource(path, cwd) {
-      assertExclusive()
-      const observation = identity.resolve(path, { cwd })
-      if (observation.kind !== 'file') throw new Error('lock target must be an existing regular file')
-      contained(observation.resourceId)
-      return observation.resourceId
-    },
-    /** Release observations are subtractive only; never publication authority.
-     * @param {string} path @param {string} cwd */
-    releaseResource(path, cwd) {
-      assertExclusive()
-      const observation = identity.resolve(path, { cwd })
-      const resourceId = observation.kind === 'file' ? observation.resourceId : resolvePath(cwd, path)
-      contained(resourceId)
-      if (observation.kind === 'missing' &&
-          (path.split(/[\\/]/).includes('..') || resourceId !== join(observation.ancestor, observation.suffix) || !missingTarget(resourceId))) {
-        throw new Error('Edit Lock release refused: missing target is not proven')
-      }
-      return { resourceId, observation }
-    },
-    /** Explicit owner release: preserve ordinary admission, but recheck missing
-     * evidence inside the manager FIFO rather than trusting a preflight scan.
-     * @param {import('./state.js').Ownership} token
-     * @param {ReturnType<typeof identity.resolve>} observation */
-    async release(token, observation) {
-      assertExclusive()
-      token = { ...token }
-      if (observation.kind === 'file') return manager.release(token)
-      const status = manager.status()
-      if (token.managerIncarnation !== status.managerIncarnation) throw new Error('stale incarnation')
-      const lock = status.locks.find(item => item.resourceId === token.resourceId)
-      if (!lock || lock.owner !== token.sessionId) throw new Error('lock not owned by this session')
-      const result = await manager.releaseStale([{
-        resourceId: token.resourceId, owner: token.sessionId, generation: token.generation,
-        executionEpoch: token.executionEpoch, status: lock.status,
-      }], resourceId => {
-        assertExclusive()
-        identity.revalidate(observation)
-        return missingTarget(resourceId)
-      })
-      const refusal = [...result.skipped, ...result.failed]
-      if (refusal.length || result.released.length !== 1) {
-        throw new Error(`Edit Lock release refused: ${refusal.map(item => item.reason).join('; ') || 'release not confirmed'}`)
-      }
-    },
-    /** Resolve the entire existing-file set before atomic ownership acquisition.
-     * @param {import('./state.js').Execution} execution
-     * @param {string[]} paths @param {string} cwd */
-    acquireBatch(execution, paths, cwd) {
-      assertExclusive()
-      const observations = paths.map(path => {
-        const observation = identity.resolve(path, { cwd })
-        if (observation.kind !== 'file') throw new Error('rename requires existing regular files')
-        contained(observation.resourceId)
-        return observation
-      })
-      if (new Set(observations.map(item => item.resourceId)).size !== paths.length) throw new Error('duplicate canonical rename target')
-      return manager.acquireMany(execution, observations.map(item => item.resourceId)).then(ownership => ({
-        ...ownership, ordered: observations.map(item => ownership.tokens.find(/** @param {import('./state.js').Ownership} token */ token => token.resourceId === item.resourceId)),
-      }))
-    },
-    /** Trusted adapter only: content is the fully synthesized original tool payload.
-     * @param {import('./state.js').Execution} execution
-     * @param {{operationId: string, tool: 'write'|'hash_edit'|'lsp_rename', filePath: string, cwd: string,
-     * args: unknown, content: string, effectivePolicy: any,
-     * batchOwnership?: import('./state.js').Ownership,
-     * expected: {kind: 'createIfAbsent'}|{kind: 'replaceIfVersion', version: string}}} request
-     * @param {AbortSignal} signal */
-    async prepare(execution, request, signal) {
-      const data = JSON.parse(canonicalRequestData(request))
-      execution = { ...execution }
-      const historical = manager.history(execution.sessionId, data.operationId)
-      if (historical) {
-        if (canonicalRequestData(data.expected) !== canonicalRequestData(historical.binding.target.policy)) throw new Error('ID_REUSE: original guard differs')
-        return manager.prepare(execution, { ...data, target: historical.binding.target }, {
-          validate() { throw new Error('historical operation cannot dispatch') },
-          publish() { throw new Error('historical operation cannot dispatch') },
-          identify() { throw new Error('historical operation cannot dispatch') },
-        })
-      }
-      const abort = () => {
-        try { void manager.cancel(execution).catch(() => {}) } catch { /* stale execution cannot revoke a newer one */ }
-      }
-      signal.addEventListener('abort', abort, { once: true })
-      if (signal.aborted) abort()
-      const detach = () => signal.removeEventListener('abort', abort)
-      try {
-      if (signal.aborted) throw new Error('call aborted')
-      if (!['workspace-write', 'danger-full-access'].includes(data.effectivePolicy?.mode)) throw new Error('writable effective policy required')
-      const observation = identity.resolve(data.filePath, { cwd: data.cwd })
-      contained(observation.kind === 'file' ? observation.resourceId : observation.ancestor)
-      // The lexical creation target too: a missing protected subtree is not an escape.
-      if (observation.kind === 'missing') contained(join(observation.ancestor, observation.suffix))
-      const target = await resolve(data.filePath, { cwd: data.cwd })
-      let descriptor
-      if (observation.kind === 'missing') {
-        if (data.tool !== 'write' || data.expected.kind !== 'createIfAbsent') throw new Error('creation requires explicit write intent')
-        descriptor = { kind: 'create', ancestor: observation.ancestor, suffix: observation.suffix, policy: data.expected }
-      } else {
-        if (data.expected.kind !== 'replaceIfVersion') throw new Error('existing resource requires original version guard')
-        let ownership = data.batchOwnership
-        if (data.tool === 'lsp_rename') {
-          if (!ownership || ownership.resourceId !== observation.resourceId || ownership.sessionId !== execution.sessionId ||
-              ownership.executionEpoch !== execution.executionEpoch || ownership.managerIncarnation !== execution.managerIncarnation) throw new Error('rename batch ownership changed')
-          manager.checkWrite(ownership)
-        } else {
-          const acquired = await manager.acquireMany(execution, [observation.resourceId])
-          ownership = acquired.tokens[0]
-        }
-        descriptor = { kind: 'update', resourceId: observation.resourceId, generation: ownership.generation, policy: data.expected }
-      }
-      const validate = () => {
-        assertExclusive()
-        if (signal.aborted) throw new Error('call aborted')
-        if (data.effectivePolicy?.mode === 'read-only') throw new Error('read-only policy')
-        identity.revalidate(observation)
-      }
-      const ready = await manager.prepare(execution, { ...data, target: descriptor }, {
-        validate,
-        // Admission still observes the turn signal. Once invoked, join the host
-        // commit independently: Stop revokes future work, not this dispatched write.
-        publish: () => writeText(target, data.content, data.expected, new AbortController().signal, data.effectivePolicy),
-        identify: () => {
-          const current = identity.resolve(data.filePath, { cwd: data.cwd })
-          if (current.kind !== 'file') throw new Error('published resource missing')
-          contained(current.resourceId)
-          if (observation.kind === 'missing') {
-            const suffix = relative(observation.ancestor, current.resourceId)
-            if (suffix === '..' || suffix.startsWith('../') || isAbsolute(suffix)) throw new Error('published resource escaped fence')
-          }
-          return current.resourceId
-        },
-      })
-      if (ready.kind === 'ready' && ready.submission) listeners.set(ready.submission, detach)
-      else detach()
-      return ready
-      } catch (error) { detach(); throw error }
-    },
-    /** @param {object} submission */
-    async commit(submission) {
-      try { return await manager.commit(submission) }
-      finally { listeners.get(submission)?.(); listeners.delete(submission) }
-    },
-  })
-}
-
-/** ENOENT alone is insufficient through a symlink or non-directory ancestor.
- * Walk every surviving component without following links; all ambiguity refuses.
- * @param {string} resourceId */
-function missingTarget(resourceId) {
-  try { lstatSync(resourceId); return false } catch (error) {
-    if (/** @type {any} */ (error)?.code !== 'ENOENT') throw error
-  }
-  for (let parent = dirname(resourceId); ; parent = dirname(parent)) {
-    try {
-      if (!lstatSync(parent).isDirectory()) return false
-    } catch (error) {
-      if (/** @type {any} */ (error)?.code !== 'ENOENT' || parent === dirname(parent)) throw error
-    }
-    if (parent === dirname(parent)) return true
-  }
-}

package/src/edit-lock/read-authority.js

@@ -1,101 +0,0 @@
-// Read-only authority snapshot bytes: the one bounded, symlink-pinned,
-// identity-checked read shared by the maintenance inspector and the cold
-// status view (design D1). No runtime open, no reservation, no mutation —
-// the file, the reservation and every history are left byte-identical.
-import { lstatSync, openSync, closeSync, fstatSync, readSync, constants } from 'node:fs'
-import { join, resolve, parse, relative, sep } from 'node:path'
-
-/** Same ceiling the maintenance inspector enforces (16 MiB). */
-export const MAX_SNAPSHOT_BYTES = 16 * 1024 * 1024
-
-// Pin every component, including the trusted root's ancestors. Node exposes no
-// portable openat: compare identities before/after opening and before/after read.
-// NOFOLLOW protects the leaf; NONBLOCK prevents swapped FIFO/device hangs.
-// These checks fail closed on observed races, not an atomic hostile-rename proof.
-export function checkedPath(path) {
-  const absolute = resolve(path)
-  let current = parse(absolute).root
-  const pins = []
-  for (const part of relative(current, absolute).split(sep).filter(Boolean)) {
-    current = join(current, part)
-    const stat = lstatSync(current)
-    if (stat.isSymbolicLink()) throw new Error('symlink authority component refused')
-    pins.push({ path: current, stat })
-  }
-  return pins
-}
-/** @param {import('node:fs').Stats} a @param {import('node:fs').Stats} b */
-export function sameNode(a, b) { return a.dev === b.dev && a.ino === b.ino && a.mode === b.mode }
-/** @param {{ path: string, stat: import('node:fs').Stats }[]} pins */
-export function verifyPins(pins) {
-  for (const pin of pins) if (!sameNode(pin.stat, lstatSync(pin.path))) throw new Error('authority path changed during inspection')
-}
-/** @param {unknown} error */
-export function missing(error) { return error !== null && typeof error === 'object' && 'code' in error && error.code === 'ENOENT' }
-/** @param {unknown} error */
-export function errorMessage(error) { return error instanceof Error ? error.message : String(error) }
-
-/**
- * @typedef {{ presence: 'valid', bytes: Buffer }
- *   | { presence: 'no-authority' }
- *   | { presence: 'no-snapshot' }
- *   | { presence: 'not-a-file' }
- *   | { presence: 'unreadable', message: string }} SnapshotRead
- */
-
-/**
- * Read `<authorityDir>/snapshot.json` with the full read-only discipline:
- * ancestor pins, O_NOFOLLOW leaf, bounded read, before/after identity checks.
- * The bytes are validated nowhere here — the caller runs `parseSnapshot`.
- *
- * Presence facts, never inferred: 'valid' (bytes returned), 'no-authority'
- * (a path component or the directory itself is absent), 'no-snapshot' (the
- * directory stands but no snapshot leaf exists; history indeterminate),
- * 'not-a-file', 'unreadable' (IO failure or an observed race, message kept).
- * @param {string} authorityDir @returns {SnapshotRead}
- */
-export function readSnapshotBytes(authorityDir) {
-  let parents
-  try {
-    parents = checkedPath(authorityDir)
-  } catch (error) {
-    if (missing(error)) return { presence: 'no-authority' }
-    return { presence: 'unreadable', message: errorMessage(error) }
-  }
-  let fd
-  try {
-    const path = join(authorityDir, 'snapshot.json')
-    let leaf
-    try { leaf = lstatSync(path) } catch (error) { if (!missing(error)) throw error }
-    if (!leaf) {
-      verifyPins(parents)
-      return { presence: 'no-snapshot' }
-    }
-    if (!leaf.isFile() || leaf.isSymbolicLink()) return { presence: 'not-a-file' }
-    // Windows exposes no O_NOFOLLOW/O_NONBLOCK (constants undefined): the leaf
-    // lstat above already refused a symlink and the post-open fstat identity
-    // check below bounds the swap window (symlink creation needs privilege on
-    // Windows; the residual TOCTOU gap is documented in edit-lock.md).
-    fd = openSync(path, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0) | (constants.O_NONBLOCK ?? 0))
-    const opened = fstatSync(fd)
-    if (!opened.isFile() || !sameNode(leaf, opened)) throw new Error('opened snapshot identity changed')
-    verifyPins(parents)
-    if (!sameNode(opened, lstatSync(path))) throw new Error('snapshot replaced before read')
-    if (opened.size > MAX_SNAPSHOT_BYTES) throw new Error('snapshot exceeds inspection byte limit')
-    const buffer = Buffer.alloc(Math.min(opened.size + 1, MAX_SNAPSHOT_BYTES + 1))
-    let length = 0
-    while (length < buffer.length) {
-      const count = readSync(fd, buffer, length, buffer.length - length, length)
-      if (!count) break
-      length += count
-    }
-    const after = fstatSync(fd)
-    verifyPins(parents)
-    if (!sameNode(opened, lstatSync(path)) || after.size !== opened.size || after.mtimeMs !== opened.mtimeMs || after.ctimeMs !== opened.ctimeMs || length !== opened.size) {
-      throw new Error('snapshot changed during bounded read')
-    }
-    return { presence: 'valid', bytes: buffer.subarray(0, length) }
-  } catch (error) {
-    return { presence: 'unreadable', message: errorMessage(error) }
-  } finally { if (fd !== undefined) closeSync(fd) }
-}

package/src/edit-lock/recovery.js

@@ -1,139 +0,0 @@
-/** Cleanup-only automatic recovery for Edit Lock (design D4).
- *
- * Classification uses only the durable turn/end reason. A provider error that
- * ends a turn while the session holds locks marks them abnormal; the session
- * may then only release, answer transfer requests or pause. Attempts, elapsed
- * recovery time and pause time are charged durably and never refunded by a
- * restart. Expiry re-evaluates; it never releases or extends. Exhaustion hands
- * the locks to a human. Business authority returns only via /edit-lock resume.
- */
-export const RECOVERY_LIMITS = Object.freeze({
-  attempts: 3,
-  elapsedMs: 5 * 60_000,
-  backoffMs: Object.freeze([15_000, 30_000, 60_000]),
-  singlePauseMs: 15 * 60_000,
-  cumulativePauseMs: 30 * 60_000,
-})
-
-/** @param {{attempts: number, elapsedMs: number}} usage @param {number} pendingElapsedMs */
-export function recoveryBudgetLeft(usage, pendingElapsedMs = 0) {
-  return usage.attempts < RECOVERY_LIMITS.attempts && usage.elapsedMs + pendingElapsedMs < RECOVERY_LIMITS.elapsedMs
-}
-
-/** @param {{resourceId: string, status: string, reason?: string}[]} locks @param {number} attempt */
-export function cleanupPrompt(locks, attempt) {
-  const lines = locks.filter(lock => lock.status === 'abnormal').map(lock => `- ${lock.resourceId} (${lock.reason ?? 'abnormal'})`)
-  return [
-    `Edit Lock cleanup-only recovery (attempt ${attempt} of ${RECOVERY_LIMITS.attempts}). The previous turn failed while this session held file ownership, so these locks are now abnormal:`,
-    ...lines,
-    'Business edits and new ownership are denied in this state. You may only: release a lock you no longer need (edit_lock_release), answer a pending ownership request (edit_lock_reply), or request a bounded pause while an external problem clears (edit_lock_pause). Do not attempt other file changes.',
-    'When cleanup is done, stop. The user resumes normal editing from the Edit Lock panel.',
-  ].join('\n')
-}
-
-/** @param {{
- *   domainFor: (agent: object) => Promise<any> | undefined,
- *   followup: (agent: object, text: string) => void,
- *   notify: (agent: object, text: string) => void,
- *   now?: () => number,
- *   setTimer?: (fn: () => void, ms: number) => any, clearTimer?: (handle: any) => void,
- *   warn?: (message: string) => void,
- * }} options */
-export function createRecoveryDriver(options) {
-  const now = options.now ?? Date.now
-  const setTimer = options.setTimer ?? ((fn, ms) => { const handle = setTimeout(fn, ms); handle.unref?.(); return handle })
-  const clearTimer = options.clearTimer ?? (handle => clearTimeout(handle))
-  /** @typedef {{since: number, timer?: any, pausedUntil?: number, done?: boolean}} Recovery */
-  /** @type {WeakMap<object, Recovery>} */
-  const active = new WeakMap()
-  let closed = false
-
-  /** Charge time spent recovering since the last mark (pauses excluded).
-   * @param {any} domain @param {object} agent @param {Recovery} recovery @param {{attempts?: number}} [extra] */
-  async function chargeElapsed(domain, agent, recovery, extra = {}) {
-    const elapsedMs = Math.max(0, now() - recovery.since)
-    recovery.since = now()
-    return domain.chargeRecovery(agent, { ...extra, elapsedMs })
-  }
-  /** @param {object} agent @param {Recovery} recovery */
-  function cancel(agent, recovery) {
-    if (recovery.timer) clearTimer(recovery.timer)
-    recovery.timer = undefined
-    recovery.done = true
-    active.delete(agent)
-  }
-  /** @param {object} agent @param {Recovery} recovery @param {number} delayMs */
-  function schedule(agent, recovery, delayMs) {
-    if (recovery.timer) clearTimer(recovery.timer)
-    recovery.timer = setTimer(() => { recovery.timer = undefined; void attempt(agent, recovery) }, delayMs)
-  }
-  /** @param {object} agent @param {Recovery} recovery */
-  async function attempt(agent, recovery) {
-    if (closed || recovery.done || active.get(agent) !== recovery) return
-    try {
-      const domain = await options.domainFor(agent)
-      const status = await domain.status(agent)
-      if (status.state !== 'recovering') { cancel(agent, recovery); return }
-      if (!status.locks.some(/** @param {any} lock */ lock => lock.status === 'abnormal')) {
-        cancel(agent, recovery)
-        options.notify(agent, 'Edit Lock cleanup complete: no abnormal locks remain. Editing stays paused until the user chooses Continue editing.')
-        return
-      }
-      const usage = await domain.recoveryUsage(agent)
-      if (!recoveryBudgetLeft(usage, now() - recovery.since)) {
-        await chargeElapsed(domain, agent, recovery)
-        cancel(agent, recovery)
-        options.notify(agent, `Edit Lock automatic cleanup stopped after ${RECOVERY_LIMITS.attempts} attempts or ${RECOVERY_LIMITS.elapsedMs / 60_000} minutes. The remaining files stay locked for the user to release or unlock from the Edit Lock panel.`)
-        return
-      }
-      const charged = await chargeElapsed(domain, agent, recovery, { attempts: 1 })
-      options.followup(agent, cleanupPrompt(status.locks, charged.attempts))
-    } catch (error) {
-      options.warn?.(`edit lock recovery attempt failed: ${/** @type {any} */ (error)?.message ?? error}`)
-    }
-  }
-
-  return Object.freeze({
-    /** Durable turn/end feed for one agent. @param {object} agent @param {any} reason */
-    async onTurnEnd(agent, reason) {
-      if (closed) return
-      const domain = await options.domainFor(agent)
-      if (!domain) return
-      let recovery = active.get(agent)
-      if (reason?.kind === 'aborted') { if (recovery) cancel(agent, recovery); return }
-      if (!recovery) {
-        if (reason?.kind !== 'error') return
-        const marked = await domain.classifyAbnormal(agent, 'provider-error')
-        if (!marked.length) return
-        recovery = { since: now() }
-        active.set(agent, recovery)
-        options.notify(agent, `Edit Lock: the turn failed while this session held files; ${marked.length} lock(s) are now abnormal and editing is limited to cleanup.`)
-      }
-      if (recovery.pausedUntil && recovery.pausedUntil > now()) return
-      const usage = await domain.recoveryUsage(agent)
-      schedule(agent, recovery, RECOVERY_LIMITS.backoffMs[Math.min(usage.attempts, RECOVERY_LIMITS.backoffMs.length - 1)])
-    },
-    /** Pause request from the cleanup turn; expiry re-evaluates.
-     * @param {object} agent @param {number} minutes */
-    async pause(agent, minutes) {
-      const recovery = active.get(agent)
-      if (!recovery) throw new Error('no automatic recovery is in progress for this session')
-      const domain = await options.domainFor(agent)
-      const result = await domain.pause(agent, minutes)
-      await chargeElapsed(domain, agent, recovery)
-      recovery.pausedUntil = now() + result.pausedMs
-      if (recovery.timer) clearTimer(recovery.timer)
-      // Elapsed recovery time restarts after the pause, not during it.
-      recovery.timer = setTimer(() => {
-        recovery.timer = undefined
-        recovery.since = now()
-        recovery.pausedUntil = undefined
-        void attempt(agent, recovery)
-      }, result.pausedMs)
-      return result
-    },
-    /** @param {object} agent */
-    state(agent) { const recovery = active.get(agent); return recovery ? { pausedUntil: recovery.pausedUntil ?? null } : null },
-    close() { closed = true },
-  })
-}