weir-harness 1.2.2 → 2.0.0

package/src/edit-lock/store.js

@@ -1,327 +0,0 @@
-import { createHash, randomUUID } from 'node:crypto'
-import { open, rename, lstat, readdir } from 'node:fs/promises'
-import { constants } from 'node:fs'
-import { join, resolve } from 'node:path'
-import { validateOperationTransitions } from './operation-history.js'
-import { canonical, parseSnapshot, validateImage } from './snapshot.js'
-import { validateAdminTransition } from './admin-ledger.js'
-
-// Directory fsync is POSIX-only (EPERM on win32, Node v24 — same stance as
-// reservation.js SYNC_SUPPORTED): the win32 row persists with file fsync +
-// atomic rename and skips the directory sync steps.
-const DIR_SYNC_SUPPORTED = process.platform === 'darwin' || process.platform === 'linux'
-
-/**
- * Unmounted historical Edit Lock snapshot storage, NOT a kernel restore interface.
- * The caller MUST already hold an externally proven exclusive directory lifecycle
- * and establish old-publisher quiescence (or explicit audited administrator risk
- * acceptance for the scoped historical writer), continuously through close(). This module
- * supplies neither singleton election nor cross-handle CAS, authentication or live fences.
- * Operation history shares this image; it cannot publish files or restore authority.
- * Receipts are process-local capabilities and MUST NOT be persisted.
- * POSIX local-filesystem foundation: the dedicated directory and its ancestors
- * must remain under the caller's exclusive control, with no concurrent mutation.
- * No cleanup/repair is automatic; failed creates may leave a temp or snapshot.
- * Recover reads only snapshot.json; integrity is a checksum, not authentication.
- * Unsupported directory sync semantics fail the open/write, never weaken the ack.
- * A poisoned handle rejects reads too, so stale memory cannot imply rollback.
- * close() drains and releases admission only; record promises carry write errors.
- *
- * @typedef {{ sessionId: string, executionEpoch: number, interrupted: boolean }} Session
- * @typedef {{ resourceId: string, generation: number }} Generation
- * @typedef {{ resourceId: string, owner: string, generation: number, status: 'active'|'user-interrupted'|'pending-confirmation'|'abnormal', reason?: string }} Lock
- * @typedef {{ sessionId: string, requestId: string }} IssuedRequest
- * @typedef {{ sessionId: string, attempts: number, elapsedMs: number, pauseMs: number }} Recovery
- * Retention (design D1) is a session-level budget: one lock batch shares one
- * cumulative allowance, and `holdUntil` is an absolute epoch-ms instant. A held
- * lock keeps its ordinary status, so `holds` is a separate table, never a lock
- * status. Version 3 adds it; a version 2 image is upgraded losslessly on recover
- * (one empty retention row per session). Version 4 preserves v2/v3 historical
- * assertions as inert records; the next durable write uses version 4.
- * @typedef {{ sessionId: string, holding: boolean, holdUntil: number|null, holdCumulativeMs: number }} HoldState
- * @typedef {{ version: 4|5|6, adminRecoveries?: any[], incarnations?: import('./incarnations.js').IncarnationEntry[], managerIncarnation: string|null, sessions: Session[], generations: Generation[], locks: Lock[], issuedRequests: IssuedRequest[], recovery: Recovery[], holds: HoldState[], operations: import('./operation-history.js').Operation[] }} AuthorityImage
- * @typedef {{ revision: number, state: AuthorityImage }} Snapshot
- */
-
-/**
- * snapshot() and record() return detached historical data, never live authority.
- * record() captures input before yielding; acknowledgement follows directory sync
- * and close. Revisions are local to this handle, not a singleton mechanism.
- * @param {{ directory: string, domainId: string, mode: 'create'|'recover', maxSnapshotBytes?: number }} options
- * @param {{ checkpoint?: (point: string) => void|Promise<void> }} [testing]
- * Test-only syscall barriers surround REAL IO; they never replace filesystem calls.
- */
-export async function openEditLockStore({ directory, domainId, mode, maxSnapshotBytes }, testing = {}) {
-  valid(id(directory) && id(domainId) && (mode === 'create' || mode === 'recover'), 'store options')
-  directory = resolve(directory)
-  valid((await lstat(directory)).isDirectory(), 'store directory')
-  if (mode === 'create') valid((await readdir(directory)).length === 0, 'create requires empty directory')
-  const target = join(resolve(directory), 'snapshot.json')
-  /** @type {Snapshot} */
-  let current
-  /** @param {Snapshot} snapshot */
-  async function persist(snapshot) {
-    const payload = { version: snapshot.state.version, domainId, ...snapshot }
-    const body = canonical(payload)
-    const bytes = canonical({ payload, checksum: createHash('sha256').update(body).digest('hex') })
-    const temporary = join(resolve(directory), `.snapshot-${randomUUID()}.tmp`)
-    /** @type {import('node:fs/promises').FileHandle|undefined} */
-    let file
-    /** @type {import('node:fs/promises').FileHandle|undefined} */
-    let dir
-    let renameStarted = false
-    /** @param {string} step @param {() => Promise<void>} operation */
-    async function io(step, operation) {
-      await testing.checkpoint?.(`before:${step}`)
-      await operation()
-      await testing.checkpoint?.(`after:${step}`)
-    }
-    try {
-      await io('temp-open', async () => { file = await open(temporary, 'wx', 0o600) })
-      valid(file, 'opened snapshot descriptor')
-      const openedFile = file
-      await io('write', async () => { await openedFile.writeFile(bytes, 'utf8') })
-      await io('file-sync', async () => { await openedFile.sync() })
-      await io('file-close', async () => { await openedFile.close(); file = undefined })
-      await io('rename', async () => { renameStarted = true; await rename(temporary, target) })
-      // The directory steps fire on every platform — checkpoint cadence is a
-      // contract; only the real directory fsync is POSIX-only (EPERM on win32,
-      // same stance as reservation.js SYNC_SUPPORTED).
-      await io('directory-open', async () => { dir = DIR_SYNC_SUPPORTED ? await open(directory, constants.O_RDONLY | (constants.O_DIRECTORY ?? 0) | (constants.O_NOFOLLOW ?? 0)) : undefined })
-      if (DIR_SYNC_SUPPORTED) valid(dir, 'opened directory descriptor')
-      const openedDirectory = dir
-      await io('directory-sync', async () => { await openedDirectory?.sync() })
-      await io('directory-close', async () => { await openedDirectory?.close(); dir = undefined })
-      committedBytes = Buffer.from(bytes, 'utf8')
-    } catch (cause) {
-      // Never remove/promote a temp or roll back a rename. Once rename was
-      // attempted its result is conservatively uncertain, including syscall errors.
-      const error = Object.assign(new Error('snapshot persistence failed; handle poisoned', { cause }), {
-        code: 'EDIT_LOCK_STORE_PERSISTENCE', commitStatus: renameStarted ? 'uncertain' : 'not-renamed',
-      })
-      // Close any acquired descriptors, but cleanup cannot turn failure into ack.
-      await Promise.allSettled([file?.close(), dir?.close()])
-      throw error
-    }
-  }
-  /** The exact committed bytes of the CURRENT snapshot: the pre-image an
-   * online administrative commit (design D4) backs up before writing. Set on
-   * open and after every successful persist. */
-  let committedBytes
-  /** The exact committed bytes read at open (recover mode only): the
-   * pre-image a composed administrative commit backs up before writing. */
-  let recoveredBytes
-  if (mode === 'create') {
-    current = { revision: 0, state: { version: 4, managerIncarnation: null, sessions: [], generations: [], locks: [], issuedRequests: [], recovery: [], holds: [], operations: [] } }
-    await persist(current)
-  } else {
-    valid((await lstat(target)).isFile(), 'snapshot must be regular file')
-    // win32: O_NOFOLLOW/O_NONBLOCK are undefined — the lstat above and the post-open
-    // stat below carry the identity checks (same stance as read-authority.js).
-    const file = await open(target, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0) | (constants.O_NONBLOCK ?? 0))
-    try {
-      valid((await file.stat()).isFile(), 'snapshot must be regular file')
-      let bytes
-      if (maxSnapshotBytes !== undefined) {
-        valid(integer(maxSnapshotBytes, 1), 'snapshot byte limit')
-        const stat = await file.stat()
-        valid(stat.size <= maxSnapshotBytes, 'snapshot byte limit')
-        bytes = Buffer.alloc(stat.size + 1)
-        let count = 0
-        while (count < bytes.length) {
-          const read = await file.read(bytes, count, bytes.length - count, count)
-          if (!read.bytesRead) break
-          count += read.bytesRead
-        }
-        valid(count === stat.size, 'snapshot size changed')
-        bytes = bytes.subarray(0, count)
-      } else bytes = await file.readFile()
-      // The byte-level validation (canonical form, version, domain, checksum,
-      // lossless upgrades, image invariants) lives in ./snapshot.js, shared
-      // verbatim with the read-only maintenance inspector: a snapshot the
-      // inspector calls valid is exactly one this recover accepts.
-      current = parseSnapshot(bytes, domainId)
-      recoveredBytes = Buffer.from(bytes)
-      committedBytes = Buffer.from(bytes)
-    } finally { await file.close() }
-  }
-  let tail = Promise.resolve()
-  let closed = false
-  /** @type {unknown} */
-  let poison
-  function healthy() { if (poison) throw new Error('store poisoned; recover under exclusive lifecycle', { cause: poison }) }
-  /** Process-local evidence is issued only after permanently closing a live attempt. */
-  const undispatched = new WeakMap()
-  const administrativeInputs = new WeakSet()
-  const recoveredKeys = new Set(current.state.operations.map(o => canonical([o.sessionId, o.operationId])))
-  const api = {
-    snapshot() { healthy(); return structuredClone(current) },
-    /** Committed bytes as read at open; undefined for a created store. The
-     * caller uses them only as the pre-image backup of an administrative
-     * commit in this handle's first record. @returns {Buffer|undefined} */
-    recoveredBytes() { healthy(); return recoveredBytes ? Buffer.from(recoveredBytes) : undefined },
-    /** Exact bytes of the current committed snapshot, updated after every
-     * successful persist. The online administrative transaction (design D4)
-     * backs these up as the pre-image of its commit; it never uses the
-     * open-time recovered bytes, which may be many revisions behind.
-     * @returns {Buffer|undefined} */
-    currentBytes() { healthy(); return committedBytes ? Buffer.from(committedBytes) : undefined },
-    /** @param {{ expectedRevision: number, nextState: AuthorityImage, base?: AuthorityImage }} input */
-    async record(input) {
-      if (closed) throw new Error('store closed')
-      healthy()
-      const proof = undispatched.get(input)
-      const administrative = administrativeInputs.delete(input)
-      undispatched.delete(input)
-      shape(input, administrative && Object.hasOwn(input, 'base') ? ['expectedRevision', 'nextState', 'base'] : ['expectedRevision', 'nextState'])
-      const { expectedRevision, nextState } = input
-      valid(integer(expectedRevision), 'expected revision')
-      validateImage(nextState)
-      const state = structuredClone(nextState)
-      validateImage(state)
-      const pending = tail.then(async () => {
-        healthy()
-        if (expectedRevision !== current.revision) throw new Error('revision conflict')
-        let previous = current.state
-        if (proof) {
-          const index = previous.operations.findIndex(o => o.sessionId === proof.sessionId && o.operationId === proof.operationId)
-          valid(index >= 0 && canonical(previous.operations[index]) === proof.operation, 'undispatched binding')
-          previous = structuredClone(previous)
-          // Validate the ordinary prepared -> not-published transition, only for
-          // the privately proven never-invoked operation. All other invariants remain.
-          previous.operations[index].phase = 'prepared'
-          previous.operations[index].fence = null
-        }
-        validateTransition(previous, state)
-        const base = administrative && Object.hasOwn(input, 'base') ? input.base : undefined
-        if (base !== undefined) {
-          // The composed administrative commit (design D3): the supplied base
-          // is the ordinary part of the transition and must itself validate.
-          validateImage(base)
-          validateTransition(previous, base)
-        }
-        validateAdminTransition(previous, state, administrative, base)
-        if (administrative) valid(state.adminRecoveries?.at(-1)?.committedRevision === current.revision + 1, 'administrative revision')
-        valid(integer(current.revision + 1), 'revision overflow')
-        const next = { revision: current.revision + 1, state }
-        try { await persist(next) } catch (error) { poison = error; throw error }
-        current = next
-        return structuredClone(current)
-      })
-      tail = pending.then(() => {}, () => {})
-      return pending
-    },
-    /** Trusted offline maintenance seam. Caller owns the publisher reservation,
-     * validated durable backup and operator authorization; never exposed to tools.
-     * @param {{ expectedRevision: number, nextState: AuthorityImage }} input */
-    recordAdministrativeRecovery(input) {
-      administrativeInputs.add(input)
-      return api.record(input)
-    },
-    /** Internal manager seam, not a tool API or an authorization check.
-     * The caller exclusively owns the original mutation closure and lifecycle.
-     * @template T
-     * @param {{ expectedRevision: number, nextState: AuthorityImage }} input
-     * @param {{sessionId: string, operationId: string}} key
-     * @param {() => T} mutation */
-    async beginPublication(input, key, mutation) {
-      healthy()
-      valid(typeof mutation === 'function', 'original mutation')
-      const sessionId = key.sessionId, operationId = key.operationId
-      const old = current.state.operations.find(o => o.sessionId === sessionId && o.operationId === operationId)
-      valid(old?.phase === 'prepared' && !recoveredKeys.has(canonical([sessionId, operationId])), 'live prepared attempt required')
-      const next = input.nextState.operations.find(o => o.sessionId === sessionId && o.operationId === operationId)
-      valid(next?.phase === 'publishing', 'publishing intent required')
-      const saved = await api.record(input)
-      const operation = saved.state.operations.find(o => o.sessionId === sessionId && o.operationId === operationId)
-      let available = true
-      function consume() {
-        if (!available) throw new Error('publication attempt closed')
-        available = false
-        healthy()
-        if (closed || current.revision !== saved.revision) throw new Error('publication attempt stale or store closed')
-      }
-      return Object.freeze({
-        invoke() { consume(); return mutation() },
-        /** @param {'cancelled-before-dispatch'|'rejected-before-dispatch'} reason */
-        async finishWithoutDispatch(reason) {
-          consume()
-          const state = structuredClone(saved.state)
-          const op = state.operations.find(o => o.sessionId === sessionId && o.operationId === operationId)
-          if (!op) throw new Error('missing publication')
-          op.phase = 'not-published'; op.fence = null
-          op.outcome = { kind: 'not-published', reason }
-          const settlement = { expectedRevision: saved.revision, nextState: state }
-          undispatched.set(settlement, { sessionId, operationId, operation: canonical(operation) })
-          return api.record(settlement)
-        },
-      })
-    },
-    async close() { closed = true; await tail },
-  }
-  return Object.freeze(api)
-}
-/** @param {unknown} condition @param {string} message @returns {asserts condition} */
-function valid(condition, message) {
-  if (!condition) throw new Error(`invalid ${message}`)
-}
-/** @param {unknown} value @returns {value is string} */
-function id(value) { return typeof value === 'string' && value.length > 0 }
-/** @param {unknown} value @param {number} [minimum] @returns {value is number} */
-function integer(value, minimum = 0) { return typeof value === 'number' && Number.isSafeInteger(value) && !Object.is(value, -0) && value >= minimum }
-/** @param {unknown} value @param {string[]} keys @returns {asserts value is Record<string, unknown>} */
-function shape(value, keys) {
-  valid(value !== null && typeof value === 'object' && !Array.isArray(value), 'object')
-  valid(Object.getPrototypeOf(value) === Object.prototype || Object.getPrototypeOf(value) === null, 'object prototype')
-  valid(Reflect.ownKeys(value).length === keys.length && keys.every(key => Object.hasOwn(value, key)), 'schema keys')
-  for (const key of keys) {
-    const descriptor = Object.getOwnPropertyDescriptor(value, key)
-    valid(descriptor && 'value' in descriptor && descriptor.enumerable, 'data property')
-  }
-}
-
-/** Storage invariants, not authorization of a kernel transition.
- * Counters are cumulative lifetime charges, never resettable retry policy.
- * @param {AuthorityImage} before @param {AuthorityImage} after */
-function validateTransition(before, after) {
-  validateOperationTransitions(before, after)
-  valid(before.managerIncarnation === null || after.managerIncarnation !== null, 'incarnation history')
-  const sessions = new Map(after.sessions.map(s => [s.sessionId, s]))
-  for (const old of before.sessions) {
-    const next = sessions.get(old.sessionId)
-    valid(next && next.executionEpoch >= old.executionEpoch, 'epoch history')
-    if (next.interrupted !== old.interrupted) valid(next.executionEpoch > old.executionEpoch, 'interruption epoch')
-  }
-  const generations = new Map(after.generations.map(g => [g.resourceId, g.generation]))
-  const previousGenerations = new Map(before.generations.map(g => [g.resourceId, g.generation]))
-  const previousLocks = new Map(before.locks.map(lock => [lock.resourceId, lock]))
-  for (const old of before.generations) valid((generations.get(old.resourceId) ?? 0) >= old.generation, 'generation history')
-  for (const lock of after.locks) {
-    const old = previousLocks.get(lock.resourceId)
-    if (!old || old.owner !== lock.owner) valid(lock.generation > (previousGenerations.get(lock.resourceId) ?? 0), 'new ownership generation')
-    if (old?.status === 'abnormal' && old.generation === lock.generation) valid(lock.status === 'abnormal', 'retained abnormal classification')
-  }
-  const requests = new Set(after.issuedRequests.map(r => canonical([r.sessionId, r.requestId])))
-  for (const old of before.issuedRequests) valid(requests.has(canonical([old.sessionId, old.requestId])), 'request tombstone removal')
-  const recoveries = new Map(after.recovery.map(r => [r.sessionId, r]))
-  for (const old of before.recovery) {
-    const next = recoveries.get(old.sessionId)
-    valid(next && next.attempts >= old.attempts && next.elapsedMs >= old.elapsedMs && next.pauseMs >= old.pauseMs, 'recovery history')
-  }
-  // Retention history: the cumulative allowance only ever grows inside a batch.
-  // A row may appear or disappear (a batch starts with the first lock and ends
-  // with the last), but an existing row never loses allowance, and starting a
-  // fresh batch is only legitimate when the session held no lock at all.
-  const previousHolds = new Map(before.holds.map(held => [held.sessionId, held]))
-  for (const held of after.holds) {
-    const old = previousHolds.get(held.sessionId)
-    if (old) {
-      // The allowance never shrinks inside a batch; it returns to zero only when the
-      // batch has ended, i.e. the session holds no lock any more.
-      const batchEnded = !after.locks.some(lock => lock.owner === held.sessionId)
-      valid(held.holdCumulativeMs >= old.holdCumulativeMs || (batchEnded && held.holdCumulativeMs === 0), 'retention history')
-    } else {
-      valid(held.holdCumulativeMs === 0 || !before.locks.some(lock => lock.owner === held.sessionId), 'retention batch restart')
-    }
-  }
-}

package/src/edit-lock/tool-scope.js

@@ -1,29 +0,0 @@
-import { createManagedWriteTool } from './write-tool.js'
-
-/** Install before an agent is published. The composition must already have
- * mounted hash_edit/LSP with THIS service captured; late replacement is unsafe.
- * Only inherited stock tools are supported. Own-scope stock definitions must be
- * disposed by their owning composition before calling this function.
- * @param {any} agent
- * @param {any} ctx
- * @param {any} service
- * @param {any} sandboxPolicy */
-export function installEditLockWriteScope(agent, ctx, service, sandboxPolicy) {
-  if (!agent?.ctx?.tools || !service?.publish || !service?.publishBatch) throw new Error('edit lock tool scope requires managed service')
-  // Restrictions remain on teardown: unmount must never expose stock writers.
-  agent.ctx.tools.restrict({deny:['write','edit']})
-  const definition = createManagedWriteTool(ctx, service, sandboxPolicy)
-  // Composition guards admit only claimed definitions.
-  service.claim?.(definition)
-  const dispose = agent.ctx.tools.register(definition)
-  if (ctx.tools.get('edit',agent) || ctx.tools.get('write',agent) !== definition) {
-    dispose()
-    throw new Error('edit lock scope did not exclusively replace stock writers')
-  }
-  let closed = false
-  return () => {
-    if (closed) return
-    closed = true
-    dispose()
-  }
-}

package/src/edit-lock/view.js

@@ -1,170 +0,0 @@
-/** Structured status view for the Edit Lock panel (design D6).
- *
- * The panel derives colour and controls from THIS shape, never from the
- * human-readable command text, so wording can change without silently breaking
- * the panel. Pure: no IO, no clock (the caller supplies `now`), no ctx.
- *
- * The primary view speaks the user's language: what state the session is in,
- * which files it holds (short names), and the one thing to do next. Technical
- * identifiers (session id, execution epoch, generation, absolute paths) are kept
- * in `technical` and per-lock `detail`, for the expandable detail only.
- */
-import { isAbsolute, relative, sep } from 'node:path'
-import { revokedOwner, settleHoldFacts } from './derived-facts.js'
-
-/** Session states the panel renders, in precedence order. */
-export const VIEW_STATES = Object.freeze(['revoked', 'unavailable', 'stopped', 'attention', 'confirm', 'holding', 'editing', 'idle'])
-
-/** Short, stable name for a file: relative to the work directory when inside it.
- * @param {string} path @param {string | undefined} cwd */
-export function shortName(path, cwd) {
-  if (typeof cwd === 'string' && isAbsolute(path) && isAbsolute(cwd)) {
-    const rel = relative(cwd, path)
-    if (rel && !rel.startsWith('..') && !isAbsolute(rel)) return rel.split(sep).join('/')
-  }
-  return path
-}
-
-/** The single next action for one row, or null. Own active locks can be released
- * by the human; another session's lock only needs a human when that session can
- * no longer act on it (stopped or abnormal). An actively edited foreign file has
- * no action: the right move is to wait or let the assistant ask for it.
- * @param {any} lock @param {boolean} mine */
-function rowAction(lock, mine) {
-  if (mine) {
-    if (lock.status === 'pending-confirmation') return 'confirm'
-    return 'release'
-  }
-  if (lock.status === 'abnormal' || lock.status === 'user-interrupted') return 'unlock'
-  return null
-}
-
-/**
- * @param {{
- *   status: { sessionId: string, state: string, interrupted: boolean|null, revoked?: boolean|null, executionEpoch: number|null, locks: any[], recovery?: any, retention?: any },
- *   locks: any[],
- *   recoveryState?: { pausedUntil?: number|null }|null,
- *   cwd?: string,
- *   root?: string,
- *   mode?: string,
- *   now: number,
- * }} input
- */
-export function buildView({ status, locks, recoveryState, cwd, root, mode, now }) {
-  const own = status.locks ?? []
-  const retention = status.retention ?? null
-  const recovery = status.recovery ?? null
-  const held = Boolean(retention?.held && retention.remainingMs > 0)
-  // This is the existing lifecycle restriction, not an inferred driver/timer state.
-  const cleanupOnly = status.state === 'recovering' && status.revoked !== true
-  // Only the owning live driver's future deadline establishes a pause.
-  // Cumulative usage survives expiry and cold reads; it grants no live state.
-  const pausedUntil = cleanupOnly && typeof recoveryState?.pausedUntil === 'number'
-    && Number.isFinite(recoveryState.pausedUntil) && recoveryState.pausedUntil > now
-    ? recoveryState.pausedUntil : null
-  /** @type {typeof VIEW_STATES[number]} */
-  let state
-  // Revoked wins over everything: an administrative revocation is a distinct,
-  // durable fact the user must see. It is repairable, not terminal: the panel
-  // offers the same continue-editing path as for a stopped session.
-  if (status.revoked === true) state = 'revoked'
-  else if (status.state === 'stopped' || status.state === 'resuming') state = 'stopped'
-  else if (status.state === 'recovering' || own.some(lock => lock.status === 'abnormal')) state = 'attention'
-  else if (own.some(lock => lock.status === 'pending-confirmation')) state = 'confirm'
-  else if (held) state = 'holding'
-  else if (own.length > 0) state = 'editing'
-  else state = 'idle'
-
-  const rows = (locks ?? []).map(lock => {
-    const mine = lock.owner === status.sessionId
-    return {
-      name: shortName(lock.resourceId, cwd),
-      mine,
-      status: lock.status,
-      reason: lock.reason ?? null,
-      action: mine && cleanupOnly ? 'release' : rowAction(lock, mine),
-      detail: { path: lock.resourceId, owner: lock.owner, generation: lock.generation },
-    }
-  })
-  // Own files first, then files that need a human, then everything else.
-  const rank = (/** @type {any} */ row) => (row.mine ? 0 : row.action ? 1 : 2)
-  rows.sort((a, b) => rank(a) - rank(b) || a.name.localeCompare(b.name))
-
-  return {
-    state,
-    cleanupOnly,
-    pausedUntil,
-    files: rows,
-    ownCount: own.length,
-    pendingCount: own.filter(lock => lock.status === 'pending-confirmation').length,
-    hold: held ? { until: retention.holdUntil, remainingMinutes: Math.ceil(retention.remainingMs / 60_000), usedMinutes: Math.round(retention.holdCumulativeMs / 60_000) } : null,
-    // Usage is cumulative history: pauseMs cannot establish a current pause.
-    recovery: recovery && (cleanupOnly || recovery.attempts || recovery.elapsedMs || recovery.pauseMs)
-      ? { attempts: recovery.attempts, elapsedSeconds: Math.round(recovery.elapsedMs / 1000), pauseMinutes: Math.round(recovery.pauseMs / 60_000) }
-      : null,
-    technical: { sessionId: status.sessionId, executionEpoch: status.executionEpoch, root: root ?? null, mode: mode ?? null, at: now },
-  }
-}
-
-/** View for a session the host cannot resolve right now. Without a reason it is
- * still starting; with one, registration failed and the reason is shown, because
- * a permanent "starting" hides a fail-closed workspace. Only a trusted live
- * binding diagnostic can enable connection retry; never editing authority.
- * @param {string | null} [reason] @param {any} [bindingFailure] */
-export function unavailableView(reason = null, bindingFailure = null) {
-  return { state: 'unavailable', reason: reason ?? null, ...(bindingFailure ? { bindingFailure } : {}), files: [], ownCount: 0, pendingCount: 0, hold: null, recovery: null, technical: null }
-}
-
-/**
- * Cold-session view (design D2): map one validated authority image into the
- * same buildView input a live status read would produce, so a restored session
- * shows its TRUE recorded state — interrupted as stopped, an ADMIN OVERRIDE as
- * repairable revoked (epoch-scoped: the owner is revoked only while its
- * recorded epoch is within the disposition's revokedEpoch), its own locks and
- * the domain's locks, retention settled against the read instant — never a
- * reasonless "starting". The `cold` marker
- * tells the panel to replace live-only actions with activation guidance, and
- * the auto-resume gate travels with the view so the guidance matches the
- * committed setting. Pure like buildView: no IO, no clock, no ctx — the caller
- * supplies the parsed image and `now`.
- * @param {{
- *   image: any,
- *   sessionId: string,
- *   cwd?: string,
- *   root?: string,
- *   autoResume?: boolean,
- *   now: number,
- * }} input
- */
-export function buildColdView({ image, sessionId, cwd, root, autoResume = true, now }) {
-  const sessions = Array.isArray(image?.sessions) ? image.sessions : []
-  const locks = (Array.isArray(image?.locks) ? image.locks : []).filter(lock => lock !== null && typeof lock === 'object')
-  const holds = Array.isArray(image?.holds) ? image.holds : []
-  const recoveries = Array.isArray(image?.recovery) ? image.recovery : []
-  const session = sessions.find(row => row?.sessionId === sessionId) ?? null
-  // The manager derives the revoked flag from the administrative ledger at
-  // status time (revokedOwner); the cold read applies the SAME shared rule in
-  // its deliberately tolerant partial mode (design D1).
-  const revoked = revokedOwner(image, sessionId, { partial: true })
-  // Read-time retention settlement through the shared derived fact (design D5,
-  // partial mode — byte-equivalent to the kernel's settleHold): a hold counts
-  // only while the session owns a lock, and the remaining budget is computed
-  // against the read instant, so a missed expiry timer can never leave stale
-  // ownership behind a status read. No hold row settles to no retention (null).
-  const held = holds.find(row => row?.sessionId === sessionId) ?? null
-  const owns = locks.some(lock => lock.owner === sessionId)
-  const retention = held ? settleHoldFacts(sessionId, held, owns, now, { partial: true }) : null
-  const status = {
-    sessionId,
-    // Interrupted records a stopped session (a restarted host interrupts every
-    // known session durably). Otherwise the state derives from locks/retention.
-    state: session?.interrupted === true ? 'stopped' : 'active',
-    interrupted: session?.interrupted ?? null,
-    revoked,
-    executionEpoch: session?.executionEpoch ?? null,
-    locks: locks.filter(lock => lock.owner === sessionId),
-    recovery: recoveries.find(row => row?.sessionId === sessionId) ?? null,
-    retention,
-  }
-  return { ...buildView({ status, locks, cwd, root, now }), cold: true, autoResume: autoResume !== false }
-}

package/src/edit-lock/write-scopes.js

@@ -1,48 +0,0 @@
-// Host-lifetime registry of per-agent managed write scopes (change
-// edit-lock-binding-self-heal, design D3).
-//
-// installEditLockWriteScope registers the managed write tool into the agent's
-// OWN scope layer, and that layer survives a preset rebind: recompose only
-// rebinds the agent's scope parent chain, it never disposes own-layer
-// registrations (dsh-tools view semantics). A later setup — after a preset
-// switch, a bundle re-apply, or a lazy re-bind at the write guard — must
-// therefore dispose the previous generation's registration BEFORE registering,
-// or the scope registry throws duplicate-registration and the re-bind dies in
-// the setup catch (this is what made even a manual re-bind fail). The disposer
-// cannot live in the mount closure: a preset switch orphans the whole mount
-// generation while the agent and its own layer live on. Like the settings
-// evidence store, the container is keyed by host root and never disposed with
-// a mount; entries are keyed by agent and released at agent/disposed.
-
-/**
- * @typedef {{ owner: object, dispose: () => void }} WriteScopeEntry
- *   `owner` is the installing mount's service object, so a reader can tell a
- *   stale foreign-generation layer apart from its own.
- */
-
-/** @type {WeakMap<object, WeakMap<object, WriteScopeEntry>>} */
-const scopesByHost = new WeakMap()
-
-/** The host's entry store, created on first use. Weak keys isolate hosts and
- * release stopped ones; weak agent keys release disposed agents.
- * @param {object} host @returns {WeakMap<object, WriteScopeEntry>} */
-export function writeScopesFor(host) {
-  let scopes = scopesByHost.get(host)
-  if (!scopes) {
-    scopes = new WeakMap()
-    scopesByHost.set(host, scopes)
-  }
-  return scopes
-}
-
-/** Dispose and forget the agent's previous registration, whatever generation
- * installed it: even a same-generation re-entry (a retry after a
- * half-finished setup) must not double-register. A stale layer must never
- * block re-installation, so disposal failures are swallowed.
- * @param {WeakMap<object, WriteScopeEntry>} scopes @param {object} agent */
-export function disposeWriteScope(scopes, agent) {
-  const entry = scopes.get(agent)
-  if (!entry) return
-  scopes.delete(agent)
-  try { entry.dispose() } catch { /* disposal is best-effort */ }
-}

package/src/edit-lock/write-tool.js

@@ -1,45 +0,0 @@
-import { probeEscalation, resolveCallPolicy } from '../hashline-edit/sandbox.js'
-import { diffResult } from '../hashline-edit/diff.js'
-
-/** Build only; the lifecycle mount must hide the inherited stock definition
- * before registering this tool. Never falls back to local mutation.
- * @param {any} ctx @param {{publish: (exec: any, request: any) => Promise<any>}} host
- * @param {any} sandboxPolicy */
-export function createManagedWriteTool(ctx, host, sandboxPolicy) {
-  const escalation = probeEscalation(ctx.fs)
-  return {
-    name: 'write',
-    description: 'Create or fully replace a UTF-8 text file through Edit Lock. Read an existing file before overwriting it.',
-    parameters: { type: 'object', properties: {
-      file_path: { type: 'string', description: 'Path to write, resolved by the filesystem backend.' },
-      content: { type: 'string', description: 'Full UTF-8 text content to write.' },
-      ...(escalation?.fields ?? {}),
-    }, required: ['file_path', 'content'] },
-    output: {
-      schema: { type: 'object' },
-      render: (/** @type {any} */ _args, /** @type {any} */ value) => [{ type: 'text', text: `${value.operation === 'create' ? 'Created' : 'Updated'} file: ${value.path}` }],
-      presentationMeta: (/** @type {any} */ _args, /** @type {any} */ value) => ({ diffs: value.fragments }),
-    },
-    async execute(/** @type {any} */ args, /** @type {any} */ exec) {
-      if (typeof args.file_path !== 'string' || !args.file_path.trim() || typeof args.content !== 'string') throw new Error('write requires file_path and content strings')
-      const { policy, resolveCwd } = await resolveCallPolicy(args, {
-        escalation, sandboxPolicy, session: exec.agent?.session, sessionCwd: exec.agent?.session?.header?.cwd,
-        approval: { approver: ctx.get?.('approval'), agent: exec.agent, toolName: 'write',
-          ...(exec.callId !== undefined ? {callId: exec.callId} : {}), ...(exec.signal ? {signal: exec.signal} : {}) },
-      })
-      if (!resolveCwd || !policy) throw new Error('managed write requires trusted cwd and effective policy')
-      const target = await ctx.fs.resolve(args.file_path, {cwd: resolveCwd})
-      // Keep the stock observation policy's exact guard; do not stat a fresh
-      // version and thereby silently authorize an unread overwrite.
-      const intent = await ctx.waterfall('fs/write-intent', target, exec, () => undefined)
-      if (!intent || !['createIfAbsent', 'replaceIfVersion'].includes(intent.kind)) throw new Error('managed write requires an explicit observation guard')
-      const before = intent.kind === 'replaceIfVersion' ? await ctx.fs.readText(target, exec.signal) : null
-      const outcome = await host.publish(exec, {tool: 'write', filePath: args.file_path, args, content: args.content,
-        expected: intent, cwd: resolveCwd, effectivePolicy: policy})
-      if (!outcome || !('version' in outcome)) throw new Error('write publication not acknowledged')
-      ctx.emit('fs/observed', target, {kind: 'present', version: outcome.version}, exec)
-      const fragments = before === null ? [] : diffResult(target.displayPath, before, args.content).fragments
-      return {path: target.displayPath, operation: outcome.kind === 'created' ? 'create' : 'update', before, after: args.content, fragments}
-    },
-  }
-}

package/src/shared/delegate-edit-lifecycle.js

@@ -1,36 +0,0 @@
-// Same-instance bridge: trusted supervision actions, never message provenance.
-// Each Edit Lock mount claims only its own parent composition. No host service
-// or persisted/custom session event is introduced.
-const mounts = new Set()
-
-export function registerDelegateEditLifecycle(mount) {
-  mounts.add(mount)
-  return () => mounts.delete(mount)
-}
-
-export async function withSupervisedEditResume(parent, childId, deliver) {
-  const cleanups = []
-  let delivered = false
-  try {
-    for (const mount of mounts) {
-      if (mount.owns(parent)) cleanups.push(await mount.resume(childId))
-    }
-    const result = await deliver()
-    delivered = true
-    return result
-  } finally {
-    // Await rollback before reporting a failed delivery to the coordinator.
-    const outcomes = await Promise.allSettled(cleanups.map(cleanup => cleanup?.(delivered)))
-    const failed = outcomes.find(outcome => outcome.status === 'rejected')
-    if (failed?.status === 'rejected') throw failed.reason
-  }
-}
-
-// Joining is not a request to destroy a running agent. Mounts resolve only
-// after a runtime quiescence event and the ordinary disposition acknowledgement.
-// The optional exact handle pins a one-shot waiter to its incarnation.
-export async function settleDelegateEditLifecycle(parent, childId, agent) {
-  for (const mount of mounts) {
-    if (mount.owns(parent)) await mount.settle(childId, agent)
-  }
-}