weir-harness 2.1.1 → 2.1.3

package/src/file-lease/plugin.js

@@ -33,6 +33,7 @@
 import { createLineageResolver } from './lineage.js'
 import { userTextMessage } from '../shared/user-message.js'
 import { createLeaseTools, REPLY_TOOL, shortName } from './tools.js'
+import { createTransferNegotiation } from './negotiation.js'
 import { createWatchCoordinator } from './watch.js'
 import { AUDIT_TYPES, createAudit } from '../shared/audit.js'
 import { getSharedLeaseClient } from './singleton.js'
@@ -410,8 +411,10 @@ export function createFileLeasePlugin(options = {}) {
     if (config?.enabled === false) return undefined
     /** @type {(() => void)[]} */
     const disposers = []
-    /** @type {WeakMap<object, Map<string, { path: string, from: any }>>} */
-    const pendingByAgent = new WeakMap()
+    // Pending requests and their outcome/lifetime rules belong to THIS mount,
+    // just like its conditional tool registrations (D11). Process-wide delivery
+    // dedupe stays in noticedByAgent; the broker remains the request authority.
+    const negotiation = createTransferNegotiation()
     /** @type {WeakMap<object, { dispose: () => void }>} */
     const replyTools = new WeakMap()
     /** @type {Set<any>} agents whose reply tool this mount registered */
@@ -520,15 +523,6 @@ export function createFileLeasePlugin(options = {}) {
       }
     }
 
-    /** @param {any} agent @returns {Map<string, { path: string, from: any }>} */
-    function pendingOf(agent) {
-      let pending = pendingByAgent.get(agent)
-      if (pending === undefined) {
-        pending = new Map()
-        pendingByAgent.set(agent, pending)
-      }
-      return pending
-    }
 
     /**
      * Register the reply tool on THIS AGENT's scope (not the mount's): the tool
@@ -569,25 +563,32 @@ export function createFileLeasePlugin(options = {}) {
       return {
         ...definition,
         async execute(/** @type {any} */ args, /** @type {any} */ exec) {
+          /** @type {any} */
+          let outcome
           try {
-            return await definition.execute(args, exec)
+            const result = await definition.execute(args, exec)
+            outcome = result
+            return result
+          } catch (error) {
+            // Domain errors retain their structured code through tools.js; no
+            // message parsing belongs in this registration adapter.
+            outcome = error
+            throw error
           } finally {
-            answered(agent, args?.request_id)
+            finishReply(agent, args?.request_id, outcome)
           }
         },
       }
     }
 
     /**
-     * One pending request is gone; the reply tool follows when none is left.
-     * @param {any} agent @param {unknown} requestId
+     * Reconcile one reply attempt with its own local request. The negotiation
+     * instance decides whether the window survives; the adapter only retires
+     * the registration when no request remains.
+     * @param {any} agent @param {unknown} requestId @param {any} outcome
      */
-    function answered(agent, requestId) {
-      const pending = pendingByAgent.get(agent)
-      if (pending === undefined) return
-      const id = text(requestId)
-      if (id !== undefined) pending.delete(id)
-      if (pending.size === 0) retireReplyTool(agent)
+    function finishReply(agent, requestId, outcome) {
+      if (negotiation.finishReply(agent, requestId, outcome) === 0) retireReplyTool(agent)
     }
 
     /**
@@ -600,7 +601,7 @@ export function createFileLeasePlugin(options = {}) {
       const registered = replyTools.get(agent)
       replyTools.delete(agent)
       replyAgents.delete(agent)
-      pendingByAgent.delete(agent)
+      negotiation.closeAgent(agent)
       noticedByAgent.delete(agent)
       if (registered === undefined) return
       try {
@@ -684,7 +685,7 @@ export function createFileLeasePlugin(options = {}) {
       const noticed = noticedFor(agent)
       if (noticed.has(requestId)) return
       noticed.add(requestId)
-      pendingOf(agent).set(requestId, { path, from: event?.from })
+      negotiation.openRequest(agent, requestId, { path, from: event?.from })
       registerReplyTool(agent)
       const from = event?.from ?? {}
       const label = text(from.label) ?? 'another session'
@@ -782,6 +783,7 @@ export function createFileLeasePlugin(options = {}) {
      */
     const routedClient = Object.freeze({
       acquire: (/** @type {any} */ owner, /** @type {any} */ paths, /** @type {any} */ scope) => client.acquire(owner, paths, scope),
+      release: (/** @type {any} */ owner, /** @type {any} */ paths) => client.release(owner, paths),
       hold: (/** @type {any} */ paths, /** @type {any} */ minutes, /** @type {any} */ owner) => client.hold(paths, minutes, owner),
       status: (/** @type {any} */ filter) => client.status(filter),
       request: (/** @type {any} */ op, /** @type {any} */ payload) => client.request(op, payload),

package/src/file-lease/tools.js

@@ -383,44 +383,6 @@ export function describeConflicts(error, cwd, at) {
   ].join('\n')
 }
 
-/**
- * The synchronous answer for a subscription that is already over. Every await in
- * the watch tool re-reads this first (design D2): a release, a reset or a
- * transfer that landed while the authoritative read was in flight is the truth,
- * and a late read result or failure may neither overwrite it nor cancel its
- * pending notice.
- * @param {import('./watch.js').WatchEntry} entry
- * @param {string} short
- * @returns {any | undefined}
- */
-function terminalOutcome(entry, short) {
-  if (entry.state === 'hit') {
-    entry.settledByTool = true
-    return {
-      state: 'released',
-      file_path: short,
-      message: `The release of ${short} happened while this subscription was being established, so nothing is pending. Claim it with edit_lock_acquire if you still need it — a release is an opportunity, not an ownership grant.`,
-    }
-  }
-  if (entry.state === 'reset') {
-    entry.settledByTool = true
-    return {
-      state: 'reset',
-      file_path: short,
-      message: `The ownership arbiter connection was reset while this subscription was being established, so nothing is pending and nothing is known about ownership. Re-check with edit_lock_status, and call edit_lock_watch again if ${short} is still held by another session.`,
-    }
-  }
-  if (entry.state === 'self') {
-    entry.settledByTool = true
-    return {
-      state: 'self',
-      file_path: short,
-      message: `This session already owns ${short} — ownership arrived while this subscription was being established — so no release subscription was kept and there is nothing to wait for.`,
-    }
-  }
-  return undefined
-}
-
 /**
  * The degraded answer for a wait that ended without an ownership fact.
  * @param {string} short
@@ -435,16 +397,67 @@ function cancelledOutcome(short) {
 }
 
 /**
- * Whether one entry is still the active wait it was. `watching` may only be
- * reported for the SAME object that is currently registered (design D2): an
- * overlapping call, a transfer or a disposal can end the wait while a read is
- * in flight, and a stale entry must never come back as `watching`.
- * @param {import('./watch.js').WatchCoordinator} watches
- * @param {import('./watch.js').WatchEntry} entry
- * @returns {boolean}
+ * Translate the coordinator's structured establishment verdict into the exact
+ * model-facing result and metadata inputs this tool has always produced. All
+ * episode state, identity, cancellation and precedence decisions stay in the
+ * coordinator; this function only renders them.
+ *
+ * @param {import('./watch.js').WatchOutcome} outcome
+ * @param {string} short
+ * @returns {any}
  */
-function stillWatching(watches, entry) {
-  return entry.state === 'watching' && watches.peek(entry.sessionId, entry.path) === entry
+function watchOutcome(outcome, short) {
+  switch (outcome.state) {
+    case 'released':
+      return {
+        state: 'released',
+        file_path: short,
+        message: `The release of ${short} happened while this subscription was being established, so nothing is pending. Claim it with edit_lock_acquire if you still need it — a release is an opportunity, not an ownership grant.`,
+      }
+    case 'reset':
+      return {
+        state: 'reset',
+        file_path: short,
+        message: `The ownership arbiter connection was reset while this subscription was being established, so nothing is pending and nothing is known about ownership. Re-check with edit_lock_status, and call edit_lock_watch again if ${short} is still held by another session.`,
+      }
+    case 'self':
+      return {
+        state: 'self',
+        file_path: short,
+        message: outcome.raced === true
+          ? `This session already owns ${short} — ownership arrived while this subscription was being established — so no release subscription was kept and there is nothing to wait for.`
+          : `This session already owns ${short}, so no release subscription was kept and there is nothing to wait for.`,
+      }
+    case 'cancelled':
+      return cancelledOutcome(short)
+    case 'free':
+      return {
+        state: 'free',
+        file_path: short,
+        message: `Nobody holds ${short} right now, so no release subscription was kept. Claim it with edit_lock_acquire (or just edit it) before working on it.`,
+      }
+    case 'unsupported':
+      return {
+        degraded: true,
+        code: 'release-events-unsupported',
+        message: `The connected arbiter does not announce release events (release-events-unsupported), so no release subscription was created for ${short}. Only this subscription is unavailable: conflicts, managed edits and negotiation behave exactly as before, and this tool can be used again once the arbiter restarts with the capability.`,
+      }
+    case 'transport':
+      return unavailable(outcome.error, 'no release subscription was created')
+    case 'watching': {
+      const holder = outcome.holder ?? {}
+      const label = text(holder.label) ?? 'another session'
+      const session = text(holder.session) ?? 'unknown'
+      return {
+        state: 'watching',
+        file_path: short,
+        holder: { label, session },
+        message: `Watching ${short} for its next release; "${label}" (session ${session}) holds it now. A release notice will arrive as a message: it means only that the path is free to compete for, so call edit_lock_acquire then. It is not an ownership grant and it reserves nothing — another waiting session may claim the path first, and the ordinary holder conflict applies.`,
+      }
+    }
+    default:
+      throw new TypeError(`Unknown watch outcome: ${String(outcome?.state)}`)
+  }
 }
 
 /**
@@ -518,7 +531,7 @@ export function createLeaseTools({ client, ownerOf, deliverNotice = () => {}, wa
         const paths = absoluteBatch(args?.paths, cwd)
         let reply
         try {
-          reply = await client.request('release', { owner, paths })
+          reply = await client.release(owner, paths)
         } catch (error) {
           if (isTransport(error)) return presentDegraded(unavailable(error, 'the release was not confirmed'), { paths: paths.map((path) => shortName(path, cwd)) })
           throw error
@@ -650,9 +663,9 @@ export function createLeaseTools({ client, ownerOf, deliverNotice = () => {}, wa
           reply = await client.reply({ requestId, owner, decision })
         } catch (error) {
           const code = codeOf(error)
-          if (code === 'expired') throw new Error(`Request ${requestId} has expired and ownership is unchanged. The requester can ask again later if it still needs the path.`)
-          if (code === 'stale') throw new Error(`Request ${requestId} is stale: ownership changed before the answer arrived, so nothing was transferred.`)
-          if (code === 'not-holder') throw new Error(`Request ${requestId} is not addressed to this session; only the current holder can answer it.`)
+          if (code === 'expired') throw Object.assign(new Error(`Request ${requestId} has expired and ownership is unchanged. The requester can ask again later if it still needs the path.`), { code })
+          if (code === 'stale') throw Object.assign(new Error(`Request ${requestId} is stale: ownership changed before the answer arrived, so nothing was transferred.`), { code })
+          if (code === 'not-holder') throw Object.assign(new Error(`Request ${requestId} is not addressed to this session; only the current holder can answer it.`), { code })
           if (isTransport(error)) return presentDegraded(unavailable(error, 'the answer was not delivered'), { requestId, decision })
           throw error
         }
@@ -752,77 +765,14 @@ export function createLeaseTools({ client, ownerOf, deliverNotice = () => {}, wa
         // callback, and one that landed before it is caught by the read below.
         // The opposite order would leave a permanent hole for that release.
         const entry = watches.register(owner.session, path, mount, exec?.agent)
-
-        /** @type {any} */
-        let reply
-        try {
-          // ONE read per entry: an overlapping call for the same session and
-          // path joins this flight instead of running its own, so both calls
-          // judge the same answer and the same entry object.
-          reply = await watches.shareStatus(entry, () => client.status({ path }))
-        } catch (error) {
-          // A terminal outcome wins over any failure (D2): a release, a reset or
-          // a transfer that landed while the read was in flight IS the answer,
-          // and its pending notice must survive. A late rejection may only
-          // cancel a plain wait.
-          const terminal = terminalOutcome(entry, short)
-          if (terminal !== undefined) return settle(terminal)
-          // No authoritative answer means no subscription: never leave a
-          // record that could wait forever for a release nobody described.
-          // The removal is conditional on THIS entry still being active, so a
-          // late caller can never cancel a newer episode.
-          watches.cancel(owner.session, path, entry)
-          if (isTransport(error)) return settle(unavailable(error, 'no release subscription was created'))
-          throw error
-        }
-
-        // Same precedence on the success path: the entry may have been consumed
-        // or ended while the read was in flight, whatever the read now says.
-        const terminal = terminalOutcome(entry, short)
-        if (terminal !== undefined) return settle(terminal)
-
-        const leases = Array.isArray(reply?.leases) ? reply.leases : []
-        if (leases.length === 0) {
-          watches.cancel(owner.session, path, entry)
-          return settle({
-            state: 'free',
-            file_path: short,
-            message: `Nobody holds ${short} right now, so no release subscription was kept. Claim it with edit_lock_acquire (or just edit it) before working on it.`,
-          })
-        }
-        const holder = leases[0]?.owner ?? {}
-        const mine = text(holder.id) === owner.id || text(holder.session) === owner.session
-        if (mine) {
-          // `self` is terminal, not merely cancelled: an overlapping call that
-          // shares this entry must read the same verdict instead of reporting a
-          // wait that no longer exists.
-          watches.cancel(owner.session, path, entry, 'self')
-          return settle({
-            state: 'self',
-            file_path: short,
-            message: `This session already owns ${short}, so no release subscription was kept and there is nothing to wait for.`,
-          })
-        }
-        if (typeof client.supportsEvent !== 'function' || client.supportsEvent('released') !== true) {
-          watches.cancel(owner.session, path, entry)
-          return settle({
-            degraded: true,
-            code: 'release-events-unsupported',
-            message: `The connected arbiter does not announce release events (release-events-unsupported), so no release subscription was created for ${short}. Only this subscription is unavailable: conflicts, managed edits and negotiation behave exactly as before, and this tool can be used again once the arbiter restarts with the capability.`,
-          })
-        }
-        // `watching` is only claimed while THIS entry is still the active one:
-        // an overlapping call or a disposal may have ended the wait while the
-        // read was in flight, and a stale entry must never read as a live wait.
-        if (!stillWatching(watches, entry)) return settle(terminalOutcome(entry, short) ?? cancelledOutcome(short))
-        const label = text(holder.label) ?? 'another session'
-        const session = text(holder.session) ?? 'unknown'
-        return settle({
-          state: 'watching',
-          file_path: short,
-          holder: { label, session },
-          message: `Watching ${short} for its next release; "${label}" (session ${session}) holds it now. A release notice will arrive as a message: it means only that the path is free to compete for, so call edit_lock_acquire then. It is not an ownership grant and it reserves nothing — another waiting session may claim the path first, and the ordinary holder conflict applies.`,
+        // The coordinator owns the complete episode: one shared status attempt,
+        // terminal precedence, identity-safe cancellation and every verdict.
+        // This adapter only renders the structured outcome it returns.
+        const outcome = await watches.status(entry, () => client.status({ path }), {
+          owner,
+          supportsRelease: () => typeof client.supportsEvent === 'function' && client.supportsEvent('released') === true,
         })
+        return settle(watchOutcome(outcome, short))
       },
     },
   ]