weir-harness 1.2.0 → 1.2.2

package/src/edit-lock/admin-ledger.js

@@ -2,6 +2,7 @@
 // of publication outcome or old-writer quiescence. It lives in the atomic image.
 import { createHash } from 'node:crypto'
 import { canonical } from './snapshot.js'
+import { revokedOwner } from './derived-facts.js'
 import { expectedRegistry, isRegistryUpgrade } from './incarnations.js'
 
 export const LATE_WRITER_RISK = 'Detached historic writers may still modify files after this override.'
@@ -12,17 +13,13 @@ export const ONLINE_RECOVERY_ACTOR = 'online-administrator'
  * settlement (design D3) are the only writers. */
 const ACTORS = ['authenticated-settings-administrator', AUTOMATIC_RECOVERY_ACTOR, ONLINE_RECOVERY_ACTOR]
 export const digest = value => createHash('sha256').update(canonical(value)).digest('hex')
-export const dispositionFor = (state, op) => state.adminRecoveries?.find(row => row.owner === op.sessionId && row.operations.some(item => item.operationId === op.operationId))
-/** Epoch-scoped revocation: a disposition revokes its owner's execution
- * authority exactly at the recorded revokedEpoch. The owner stays revoked
- * while its recorded epoch is within it; a trusted resume advances the epoch
- * past every revokedEpoch and ends the revoked state atomically, without any
- * ledger change (append-only: dispositions are never removed or altered). */
-export const revokedOwner = (state, owner) => {
-  const session = state.sessions?.find(s => s.sessionId === owner)
-  if (!session) return false
-  return state.adminRecoveries?.some(row => row.owner === owner && session.executionEpoch <= row.revokedEpoch) === true
-}
+// Epoch-scoped revocation (`revokedOwner`) and the disposition lookup
+// (`dispositionFor`) live in derived-facts.js (change edit-lock-deepening,
+// design D1) — one pure home shared by the manager status path, the cold view
+// and the inspector; `revokedOwner` is imported above for this module's own
+// validation. The re-export keeps existing external importers working (the
+// integration scenario child imports dispositionFor from this module).
+export { dispositionFor, revokedOwner } from './derived-facts.js'
 
 function requireThat(condition, message) { if (!condition) throw new Error(`invalid administrative recovery: ${message}`) }
 function keys(value, names) {

package/src/edit-lock/admin-recovery.js

@@ -6,7 +6,8 @@ import { createHash } from 'node:crypto'
 import { reservePublisher } from './reservation.js'
 import { openEditLockStore } from './store.js'
 import { canonical, parseSnapshot, validateImage } from './snapshot.js'
-import { administrativeState, digest, dispositionFor, LATE_WRITER_RISK } from './admin-ledger.js'
+import { administrativeState, digest, LATE_WRITER_RISK } from './admin-ledger.js'
+import { dispositionFor } from './derived-facts.js'
 
 export const MAX_RECOVERY_BYTES = 16 * 1024 * 1024
 const sha256 = bytes => createHash('sha256').update(bytes).digest('hex')

package/src/edit-lock/admission.js

@@ -2,8 +2,15 @@ import { posix, win32 } from 'node:path'
 
 /** Candidates describe effects, not merely explicit API arguments. Session-wide
  * operations must enumerate affected ownership at their FIFO position.
+ * Modes: 'normal' covers every mutating ingress; 'release' is pure removal and
+ * must retain the ownership unresolved updates require; 'revocation' is strictly
+ * subtractive and crosses fences. 'resume' is reserved for session-level
+ * recovery transactions (the trusted Continue): it publishes nothing, so an
+ * unresolved resource-level fence never denies it, while domain fences and
+ * every shape denial bind it exactly as they bind 'normal'. It must never be
+ * used for a transaction that publishes, confirms, acquires or releases.
  * @typedef {{kind: 'resources', resourceIds: string[]} | {kind: 'scope', ancestor: string} | {kind: 'none'}} Candidate
- * @typedef {'normal'|'release'|'revocation'} Mode
+ * @typedef {'normal'|'release'|'revocation'|'resume'} Mode
  */
 
 /** Shape check only, NOT filesystem proof. The trusted manager ingress already
@@ -59,7 +66,10 @@ export function admitMutation(operations, candidate, mode = 'normal') {
       for (const resourceId of candidate.resourceIds) {
         if (!canonicalResource(resourceId)) deny('identity-unproved')
         if (fence?.kind !== 'resource') deny('scope-continuity-unproved')
-        if (fence?.kind === 'resource' && (!canonicalResource(fence.resourceId) || fence.resourceId === resourceId)) deny('resource-conflict')
+        // 'resume' publishes nothing: a resource-level fence never bars the
+        // session-level recovery transaction; it keeps barring the resource
+        // itself on every other mode until administrative settlement.
+        if (mode !== 'resume' && fence?.kind === 'resource' && (!canonicalResource(fence.resourceId) || fence.resourceId === resourceId)) deny('resource-conflict')
       }
     }
   }

package/src/edit-lock/binding-guidance.js

@@ -8,14 +8,32 @@ export function bindingRefusalReason(pid, attestation) {
   return `session already bound: holder=${holder}${pid !== undefined ? `; pid=${pid}` : ''}`
 }
 
-/** Render only publisher-classified facts. Unrecognized/legacy reasons are unknown.
- * @param {string} sessionId @param {string} reason */
-export function bindingGuidance(sessionId, reason) {
-  const facts = /^session already bound: holder=(serving-idle|serving|same-process-unattestable|cross-process-pid|unknown)(?:; pid=([1-9]\d*))?$/.exec(reason)
-  const classification = facts?.[1]
-  const pid = facts?.[2]
+/** The wire/minted holder classes. */
+const HOLDER_KINDS = Object.freeze(['revocation-failed', 'serving', 'transferable', 'cross-process', 'unknown'])
+
+/** Validate a structured binding refusal — exactly the minted four-field
+ * shape crosses the wire or reaches a classifier; anything else degrades to
+ * the text channel (display only, never a decision input).
+ * @param {unknown} value @returns {{code: 'binding-duplicate', retryable: true, holderKind: string, holderPid: number | null} | undefined} */
+export function asBindingFailure(value) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return undefined
+  if (Object.keys(value).sort().join(',') !== 'code,holderKind,holderPid,retryable') return undefined
+  const { code, retryable, holderKind, holderPid } = /** @type {any} */ (value)
+  if (code !== 'binding-duplicate' || retryable !== true || !HOLDER_KINDS.includes(holderKind)) return undefined
+  if (holderPid !== null && !(Number.isSafeInteger(holderPid) && holderPid > 0)) return undefined
+  return { code, retryable, holderKind, holderPid }
+}
+
+/** Render only publisher-classified facts — the STRUCTURED bindingFailure,
+ * never a re-parse of the display text (spec: presentation must not infer
+ * state by matching human-readable text; change edit-lock-deepening D2).
+ * Unrecognized or missing structure renders as unknown.
+ * @param {string} sessionId @param {any} failure */
+export function bindingGuidance(sessionId, failure) {
+  const classification = failure?.code === 'binding-duplicate' ? failure?.holderKind : undefined
+  const pid = typeof failure?.holderPid === 'number' ? failure.holderPid : undefined
   let holder
-  if (classification === 'serving-idle') {
+  if (classification === 'transferable') {
     // Transferable (change edit-lock-binding-transfer): an idle same-process
     // holder is taken over by the next driving ingress — calm copy, no pid,
     // no window hunt, and NEVER the publisher-reservation warning.
@@ -25,14 +43,14 @@ export function bindingGuidance(sessionId, reason) {
     // channel proxy): name what is happening and when to retry. No window
     // hunt (single-instance hosts exist) and no process management.
     holder = `session ${sessionId} is being edited in another attachment right now. Wait for that turn to finish, then use /edit-lock retry in this session; retry does not Continue editing.`
-  } else if (classification === 'same-process-unattestable' && pid !== undefined) {
+  } else if (classification === 'unknown' && pid !== undefined) {
     holder = `session ${sessionId} has a binding in this same process (pid ${pid}) that cannot be safely reclaimed. A stale runtime incarnation may still hold its channel. Wait for the original holder to disconnect or for confirmed process shutdown.`
-  } else if (classification === 'cross-process-pid' && pid !== undefined) {
+  } else if (classification === 'cross-process' && pid !== undefined) {
     holder = `session ${sessionId} has a binding held by process pid ${pid}. Quit that holder process or disconnect the original holder, and wait for confirmation.`
   } else {
     holder = `session ${sessionId} has a binding whose holder cannot be attested. Wait for the original holder to disconnect or for confirmed process shutdown.`
   }
-  if (classification === 'serving-idle' || classification === 'serving') return holder
+  if (classification === 'transferable' || classification === 'serving') return holder
   return `${holder} Then use /edit-lock retry in the original session when available; retry does not Continue editing. Do NOT remove the publisher reservation (.weir/.edit-lock.publisher-reservation) while its process is alive — removing it would split the edit authority.`
 }
 

package/src/edit-lock/binding-machine.js

@@ -0,0 +1,312 @@
+/** Per-agent binding state machine (change edit-lock-deepening, design D3):
+ * setupAgentOnce / setupAgent / retryBinding / disposeAgent / startupFailure /
+ * dispositionFor and the closure state they share, extracted from the
+ * composition (index.js), which now keeps pure wiring: tool registration, the
+ * pre-execute guard, HTTP endpoints, the /edit-lock command, drivers and event
+ * listeners. The move is mechanical — no logic changed; every container keeps
+ * exactly the lifetime it had in the mount closure.
+ *
+ * Lifetime table (itemized BEFORE the move; the move changed nothing in it):
+ *
+ *   state               lifetime       home after the move
+ *   ------------------  -------------  --------------------------------------
+ *   settled             cross-mount    sharedDomainRegistryFor entry (existing
+ *                       precedent, with recoveryNotices); INJECTED, not owned
+ *   writeScopes         host-lifetime  writeScopesFor(host) store, surviving a
+ *                       preset rebind; INJECTED — the preset-rebind survival
+ *                       semantics and the `ctx.root ?? ctx` host key are
+ *                       unchanged
+ *   disposedAgents      per-mount      this module (WeakSet)
+ *   startFailures       per-mount      this module (WeakMap)
+ *   bindingFailures     per-mount      this module (WeakMap)
+ *   setupInFlight       per-mount      this module (WeakMap)
+ *   boundAgents         per-mount      this module (Map by session id)
+ *   dispositions        per-mount      this module (Map by session id; the
+ *                       latest incarnation stays joinable after synchronous
+ *                       cleanup)
+ *   agentDispositions   per-mount      this module (WeakMap)
+ *   disposalTasks       per-mount      this module (WeakMap)
+ *   pendingAutoResume   per-mount      composition turn wiring; INJECTED (a
+ *                       successful retry clears an armed auto-resume)
+ *   delegateResumes     per-mount      composition delegate-lifecycle wiring;
+ *                       INJECTED (a fresh bind replays a pending resume)
+ *   turnClassifications per-mount      composition turn/end listener; INJECTED
+ *                       (dispose awaits the durable classification first)
+ *   replyTools          per-mount      composition negotiation wiring;
+ *                       INJECTED (dispose retires the reply tool)
+ *   expiry              per-mount      composition retention-timer wiring;
+ *                       INJECTED (dispose clears the timer)
+ *
+ * Cross-mount state rides the EXISTING sharedDomainRegistryFor entry — no new
+ * cross-mount container is introduced. Mount-generation flags arrive as
+ * getters (isClosed/platformFailure) so the machine reads the live value.
+ * @param {{
+ *   ctx: any, sessionOf: (agent: any) => string | undefined, GUARDED_TOOLS: readonly string[],
+ *   options: any, registry: any, settled: WeakMap<object, any>, writeScopes: WeakMap<object, import('./write-scopes.js').WriteScopeEntry>,
+ *   domainOf: (agent: any) => Promise<any>, servingRuntime: (sessionId: string) => any,
+ *   ownAgent: (agent: any) => boolean, installWriteScope: (agent: any) => import('./write-scopes.js').WriteScopeEntry,
+ *   evidence: any, audit: (session: any, type: any, data: any, options?: any) => void, deliverLocal: (agent: any, text: string, wake?: boolean) => void,
+ *   pendingAutoResume: WeakMap<object, boolean>, delegateResumes: Map<string, any>, turnClassifications: WeakMap<object, Promise<unknown>>,
+ *   replyTools: WeakMap<object, {dispose: () => void, stale: boolean}>, expiry: WeakMap<object, {timer?: any}>, settle: any,
+ *   isClosed: () => boolean, platformFailure: () => any,
+ * }} deps
+ */
+import { AUDIT_TYPES } from '../shared/audit.js'
+import { disposeWriteScope } from './write-scopes.js'
+
+/** In-session binding-failure notice copy (change edit-lock-binding-transfer,
+ * design D4): the transferable class (same-process idle holder) is a calm
+ * self-heal announcement rather than an editing-disabled alarm and never
+ * carries the raw holder classification or the reservation warning; a mid-turn
+ * holder names the real state and the retry moment. Template layer stays
+ * English (AGENTS §3.7). @param {string} reason @param {any} failure */
+function bindingFailureNotice(reason, failure) {
+  if (failure?.code === 'binding-duplicate' && failure.holderKind === 'transferable') {
+    return "Edit Lock: this session's editing authority is held by an inactive attachment of this same session; it transfers automatically when you send a message."
+  }
+  if (failure?.code === 'binding-duplicate' && failure.holderKind === 'serving') {
+    return "Edit Lock: this session is being edited in another attachment right now; managed file editing stays unavailable until that turn finishes. Do not retry the failed edit; use /edit-lock retry (or the panel's Retry connection) once it finishes — retry does not Continue editing."
+  }
+  return `Edit Lock could not start this session's edit domain (${reason}); managed file editing is temporarily unavailable. ${failure?.code === 'binding-duplicate' ? 'Do not retry the failed edit: the binding is retried automatically when the user next sends a message, after which editing works normally. Never remove a live publisher reservation.' : 'Inspect Edit Lock maintenance before continuing.'}`
+}
+
+export function createBindingMachine(deps) {
+  const {
+    ctx, sessionOf, GUARDED_TOOLS, options, registry, settled, writeScopes,
+    domainOf, servingRuntime, ownAgent, installWriteScope,
+    evidence, audit, deliverLocal,
+    pendingAutoResume, delegateResumes, turnClassifications, replyTools, expiry, settle,
+    isClosed, platformFailure,
+  } = deps
+  /** Agents disposed in this mount; their undispatched sweep work cancels.
+   * @type {WeakSet<object>} */
+  const disposedAgents = new WeakSet()
+  /** Why registration failed for an agent, for the panel. @type {WeakMap<object, string>} */
+  const startFailures = new WeakMap()
+  /** Publisher-classified failures, never inferred from text. @type {WeakMap<object, any>} */
+  const bindingFailures = new WeakMap()
+  /** In-flight setup per agent, shared by every entry point (creation,
+   * preset-switch, catch-up, lazy re-bind) so concurrent callers can never
+   * double-register. @type {WeakMap<object, Promise<void>>} */
+  const setupInFlight = new WeakMap()
+  const boundAgents = new Map()
+  // Keep the latest incarnation joinable even after synchronous binding cleanup.
+  // Exact-handle waiters retain their own record when a session activates again.
+  const dispositions = new Map()
+  const agentDispositions = new WeakMap()
+  const disposalTasks = new WeakMap()
+
+  function dispositionFor(agent) {
+    let record = agentDispositions.get(agent)
+    if (!record) {
+      record = Promise.withResolvers()
+      record.promise.catch(() => {}) // emit initiators have no awaiting caller
+      agentDispositions.set(agent, record)
+      dispositions.set(agent.id, record)
+    }
+    return record
+  }
+
+  /** Only this live Agent's diagnostic; no domain reads or startup side effects. @param {any} agent */
+  function startupFailure(agent) {
+    const platform = platformFailure()
+    if (platform) return { state: 'unavailable', reason: platform.message, bindingFailure: null }
+    if (!agent || settled.has(agent) || !startFailures.has(agent)) return null
+    let eligible = false
+    try {
+      const serving = servingRuntime(agent.id)
+      eligible = !isClosed() && !disposedAgents.has(agent) && ownAgent(agent)
+        && (serving === agent
+          // The registry names ANOTHER live local agent — the dual-agent defect
+          // this change heals (edit-lock-binding-transfer). The recorded
+          // duplicate-binding failure is still THIS agent's honest panel state:
+          // show it, with its Retry action, instead of hiding behind the ghost's
+          // healthy binding. An empty registry stays hidden (unattestable).
+          || (serving !== undefined && bindingFailures.get(agent)?.code === 'binding-duplicate'))
+    } catch { /* no trusted live identity */ }
+    if (!eligible) return null
+    const failure = bindingFailures.get(agent)
+    return { state: 'unavailable', reason: startFailures.get(agent),
+      bindingFailure: failure ? { ...failure, inFlight: setupInFlight.has(agent) } : null }
+  }
+
+  /** Per-agent Edit Lock setup, shared by the creation listener, the
+   * preset-switch re-bind, the late-mount catch-up and the guard/acquire lazy
+   * re-bind, so the paths can never diverge. Root selection and successful
+   * startup are separate: explicit binding retry reuses the existing scope
+   * and root, while ordinary entry points never repeat a failed startup.
+   * @param {any} agent @param {boolean} [retry] @param {boolean} [transfer]
+   * transfer (change edit-lock-binding-transfer) marks the driving-ingress
+   * transfer admission: the domain's transferStart re-adjudicates holder
+   * idleness at execution, and the post-bind registry-identity check is
+   * skipped because the registry legitimately still names the idle holder. */
+  async function setupAgentOnce(agent, retry = false, transfer = false) {
+    if (isClosed() || settled.has(agent)) return
+    // No writer scope, root resolution, directory, reservation or session
+    // authority may be installed when the mount preflight failed.
+    if (platformFailure()) return
+    if (!registry.rootOf(agent)) try {
+      // A previous generation's managed write survives in the agent's own
+      // scope layer (a preset rebind never disposes own-layer registrations);
+      // retire it first or the scope registry throws duplicate-registration
+      // and the re-bind dies here (design D3).
+      disposeWriteScope(writeScopes, agent)
+      writeScopes.set(agent, installWriteScope(agent))
+      registry.bind(agent, options.fixed?.root ?? agent?.session?.header?.cwd)
+    } catch (error) {
+      // The denial itself must never escape: restrict() throws on names the
+      // agent's composition does not know, and an escape from this setup path
+      // is fiber-fatal during a reload (2026-10-05 host crash). Deny only the
+      // guarded tools the agent actually has.
+      try {
+        const known = GUARDED_TOOLS.filter(name => ctx.tools?.get?.(name, agent) !== undefined)
+        if (known.length > 0) agent?.ctx?.tools?.restrict?.({ deny: [...known] })
+      } catch { /* the denial is best-effort; the records below are the visible account */ }
+      // Failure visibility (design D4): the same reason lands in the panel
+      // state, the maintenance evidence, an in-session notice and the durable
+      // audit; the warn stays as the host ring-buffer copy.
+      const reason = String(/** @type {any} */ (error)?.message ?? error)
+      startFailures.set(agent, reason)
+      try { evidence?.recordSessionFailure?.(sessionOf(agent), reason) } catch { /* reporting only */ }
+      audit(agent?.session ?? null, AUDIT_TYPES.editLockMaintenance, { kind: 'setup-failed', sessionId: sessionOf(agent) ?? null, reason })
+      try { deliverLocal(agent, `Edit Lock is unavailable for this session (${reason}); managed file editing is disabled and the failed edit must not be retried. This failure is not repaired automatically: the user can restart DeepSeek Harness or start a new conversation.`) } catch { /* the audit record is the durable account */ }
+      ctx.logger?.warn?.(`edit lock scope failed; edit tools denied: ${reason}`)
+      return
+    }
+    try {
+      const domain = await domainOf(agent)
+      if (transfer) await domain.transferStart(agent)
+      else if (retry) await domain.retryStart(agent)
+      else await domain.start(agent)
+      if (isClosed() || disposedAgents.has(agent) || (retry && (!ownAgent(agent) || (!transfer && servingRuntime(agent.id) !== agent)))) {
+        await domain.forget(agent)
+        throw new Error('Edit Lock mount changed during binding')
+      }
+      startFailures.delete(agent)
+      bindingFailures.delete(agent)
+      try { evidence?.clearSessionFailure?.(sessionOf(agent)) } catch { /* reporting cannot undo a successful bind */ }
+      // A genuine message from a turn that ran while binding was unavailable
+      // is not a Continue receipt for a later injected wake after connection retry.
+      if (retry) pendingAutoResume.delete(agent)
+      settled.set(agent, domain)
+      boundAgents.set(agent.id, agent)
+      dispositionFor(agent)
+      if (!retry) await delegateResumes.get(agent.id)?.resume(agent, domain)
+    } catch (error) {
+      // Kept so the panel can say WHY editing is unavailable instead of
+      // showing "starting" forever; the notice aligns this catch with the
+      // write-scope failure above.
+      const reason = String(/** @type {any} */ (error)?.message ?? error)
+      startFailures.set(agent, reason)
+      const failure = /** @type {any} */ (error)?.bindingFailure
+      if (failure?.code === 'binding-duplicate') bindingFailures.set(agent, failure)
+      else bindingFailures.delete(agent)
+      try { evidence?.recordSessionFailure?.(sessionOf(agent), reason) } catch { /* reporting only */ }
+      try { deliverLocal(agent, bindingFailureNotice(reason, failure)) } catch { /* the panel record remains */ }
+      ctx.logger?.warn?.(`edit lock registration failed for ${sessionOf(agent)}: ${reason}`)
+    }
+  }
+  /** Concurrent entry points (agent/created, preset-switch, lazy re-bind)
+   * share one in-flight setup per agent; a completed setup short-circuits on
+   * the root binding. @param {any} agent @returns {Promise<void>} */
+  function setupAgent(agent) {
+    const pending = setupInFlight.get(agent)
+    if (pending) return pending
+    if (isClosed() || settled.has(agent) || registry.rootOf(agent)) return Promise.resolve()
+    const inner = setupAgentOnce(agent)
+    const task = inner.finally(() => { if (setupInFlight.get(agent) === task) setupInFlight.delete(agent) })
+    setupInFlight.set(agent, task)
+    return task
+  }
+  /** Trusted driving ingresses only: the explicit /edit-lock retry (and panel
+   * action), the message-armed pre-step retry, and the write-guard lazy
+   * re-bind. Same Agent/root/mount; no writer reinstallation. Every attempt
+   * past the eligibility gate is audited — a silently swallowed refusal is a
+   * defect (change edit-lock-binding-transfer, design D3/D5).
+   * @param {any} agent @param {'command' | 'message' | 'write-guard'} [via] */
+  async function retryBinding(agent, via = 'command') {
+    if (isClosed() || disposedAgents.has(agent) || !ownAgent(agent)) throw new Error('Edit Lock retry requires the current live Agent of this mount')
+    if (!registry.rootOf(agent) || bindingFailures.get(agent)?.code !== 'binding-duplicate') throw new Error('Edit Lock startup failure is not eligible for binding retry')
+    const cause = bindingFailures.get(agent)
+    const sessionId = sessionOf(agent) ?? null
+    const root = registry.rootOf(agent) ?? undefined
+    /** @param {string} result @param {Record<string, unknown>} [extra] */
+    const record = (result, extra = {}) => audit(agent?.session ?? null, AUDIT_TYPES.editLockMaintenance, {
+      kind: 'binding-transfer', sessionId, code: cause?.code ?? 'binding-duplicate', result, ...extra,
+    }, { root })
+    // Attestation trichotomy (design D5): the registry naming THIS claimant
+    // keeps the existing superseded rebind; naming ANOTHER live local agent
+    // routes to the transfer admission (holder idleness is re-adjudicated at
+    // execution, publisher-side); an unavailable or empty registry stays
+    // fail-closed — the holder cannot be attested.
+    let serving
+    try { serving = servingRuntime(agent.id) } catch { serving = undefined }
+    if (serving === undefined) {
+      const error = new Error('Edit Lock binding retry refused: the agent registry is unavailable or names no live agent for this session, so the holder cannot be attested. The recorded cause stays; a later retry remains possible.')
+      record('refused', { reason: 'registry-unattestable', detail: error.message })
+      throw error
+    }
+    const transfer = serving !== agent
+    try {
+      let task = setupInFlight.get(agent)
+      if (!task) {
+        const inner = setupAgentOnce(agent, true, transfer)
+        task = inner.finally(() => { if (setupInFlight.get(agent) === task) setupInFlight.delete(agent) })
+        setupInFlight.set(agent, task)
+      }
+      await task
+    } catch (error) {
+      record('refused', { reason: /** @type {any} */ (error)?.bindingFailure?.holderKind ?? 'retry-refused', detail: String(/** @type {any} */ (error)?.message ?? error) })
+      throw error
+    }
+    const failure = startFailures.get(agent)
+    if (failure || !settled.has(agent)) {
+      // setupAgentOnce records instead of rethrowing: the refusal's holder
+      // class comes from the freshly re-recorded structured failure.
+      const error = new Error(failure ?? 'Edit Lock binding remains unavailable')
+      record('refused', { reason: bindingFailures.get(agent)?.holderKind ?? 'binding-unavailable', detail: error.message })
+      throw error
+    }
+    if (transfer) {
+      record('transferred', { holder: cause?.holderKind ?? null })
+    } else if (via === 'message') {
+      // The message-armed superseded success keeps its established audit shape
+      // (pinned by the editlock-binding-auto-retry integration scenario).
+      audit(agent?.session ?? null, AUDIT_TYPES.editLockMaintenance, {
+        kind: 'binding-auto-retry', sessionId, code: cause?.code ?? 'binding-duplicate', result: 'recovered',
+      }, { root })
+    }
+    return 'Edit Lock connection recovered. Editing remains interrupted; use Continue editing when ready. No failed edit was replayed.'
+  }
+  function disposeAgent(agent) {
+    if (disposedAgents.has(agent)) return disposalTasks.get(agent) ?? Promise.resolve()
+    if (boundAgents.get(agent.id) === agent) boundAgents.delete(agent.id)
+    // Undispatched sweep work armed by this agent cancels here (an in-flight
+    // authority transaction is never cancelled or reinterpreted).
+    disposedAgents.add(agent)
+    // The managed write lives on the agent's own scope layer, which dies with
+    // the agent: retire the host-lifetime registration here (design D3).
+    disposeWriteScope(writeScopes, agent)
+    replyTools.get(agent)?.dispose()
+    replyTools.delete(agent)
+    const timer = expiry.get(agent)?.timer
+    if (timer) clearTimeout(timer)
+    expiry.delete(agent)
+    settle.settled(agent)
+    const domain = settled.get(agent)
+    settled.delete(agent)
+    // The emit hook must cancel timers/scopes/sweeps synchronously. Only the
+    // final authority disposal waits for durable abnormal classification.
+    const record = dispositionFor(agent)
+    const task = Promise.resolve(turnClassifications.get(agent)).then(() => domain?.dispose(agent))
+    task.then(record.resolve, record.reject)
+    disposalTasks.set(agent, record.promise)
+    return record.promise
+  }
+
+  return {
+    disposedAgents, startFailures, bindingFailures, setupInFlight,
+    boundAgents, dispositions, agentDispositions,
+    setupAgent, retryBinding, disposeAgent, startupFailure,
+  }
+}

package/src/edit-lock/derived-facts.js

@@ -0,0 +1,67 @@
+/** Ledger derived facts (change edit-lock-deepening, design D1): the three
+ * derivation rules an authority image supports — epoch-scoped revocation
+ * (`revokedOwner`), read-time hold settlement (`settleHoldFacts`) and the
+ * administrative disposition lookup (`dispositionFor`) — in ONE pure home,
+ * shared by the manager status path, the kernel's settleHold, the cold view
+ * and the maintenance inspector. Pure: no IO, no clock, no ctx, no imports.
+ *
+ * Each rule takes a `partial` option for the cold read (buildColdView): the
+ * panel is deliberately more tolerant than the kernel — a partial image (a
+ * missing collection, a malformed row) degrades to "not revoked / no hold"
+ * instead of throwing on data the kernel would already have rejected at parse
+ * time. The strict default is byte-identical to the kernel/ledger rules the
+ * call sites previously inlined or imported. */
+
+/**
+ * Epoch-scoped revocation: a disposition revokes its owner's execution
+ * authority exactly at the recorded revokedEpoch; the owner stays revoked
+ * while its recorded epoch is within it, and a trusted resume advancing the
+ * epoch past every revokedEpoch ends the revoked state without any ledger
+ * change (append-only: dispositions are never removed or altered). Extracted
+ * from admin-ledger.js; the cold view applied the same rule inline.
+ * @param {any} state the authority image (or the in-memory status state)
+ * @param {string} owner
+ * @param {{ partial?: boolean }} [options] partial tolerates a partial image:
+ *   missing collections read as empty and malformed rows are skipped; the
+ *   strict default trusts the validated image.
+ */
+export function revokedOwner(state, owner, { partial = false } = {}) {
+  if (partial) {
+    const sessions = Array.isArray(state?.sessions) ? state.sessions : []
+    const session = sessions.find(row => row?.sessionId === owner) ?? null
+    if (session == null) return false
+    const ledger = Array.isArray(state?.adminRecoveries) ? state.adminRecoveries : []
+    return ledger.some(row => row?.owner === owner && Number.isSafeInteger(row?.revokedEpoch) && session.executionEpoch <= row.revokedEpoch)
+  }
+  const session = state.sessions?.find(s => s.sessionId === owner)
+  if (!session) return false
+  return state.adminRecoveries?.some(row => row.owner === owner && session.executionEpoch <= row.revokedEpoch) === true
+}
+
+/**
+ * Read-time retention settlement (design D5), byte-identical to the kernel's
+ * settleHold rule it was extracted from (state.js): 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. The caller keeps its container lookup and its empty
+ * case (the kernel's zero row vs the cold view's null): `held` is the
+ * session's PRESENT hold row, `owns` whether the session owns any lock, `now`
+ * the read instant.
+ * @param {string} sessionId @param {any} held @param {boolean} owns @param {number} now
+ * @param {{ partial?: boolean }} [options] partial keeps the cold path's
+ *   defensive tolerance of a partial image: an undefined holdUntil reads as no
+ *   expiry and only a literal `holding === true` counts.
+ */
+export function settleHoldFacts(sessionId, held, owns, now, { partial = false } = {}) {
+  const until = held.holdUntil
+  const remainingMs = (partial ? until == null : until === null) ? 0 : Math.max(0, until - now)
+  const holding = (partial ? held.holding === true : held.holding) && owns
+  return { sessionId, held: holding, expired: holding && until !== null && remainingMs === 0,
+    holdUntil: until, remainingMs, holdCumulativeMs: held.holdCumulativeMs }
+}
+
+/**
+ * The administrative disposition covering one operation, if any. Extracted
+ * verbatim from admin-ledger.js; the maintenance inspector's inline copy was
+ * identical (inspect.js). @param {any} state @param {any} op */
+export const dispositionFor = (state, op) => state.adminRecoveries?.find(row => row.owner === op.sessionId && row.operations.some(item => item.operationId === op.operationId))