weir-harness 2.0.0 → 2.1.0

package/src/file-lease/tools.js

@@ -1,6 +1,6 @@
 // The model-facing tool surface of the file-lease feature (design D4, D5, D13).
 //
-// Six pure definitions. They own no state: the arbiter is the only authority
+// Seven pure definitions. They own no state: the arbiter is the only authority
 // (D6/D8), so a tool translates a model intent into one protocol call and
 // translates the verdict back into something a model can act on. Nothing here
 // re-derives ownership, remembers it, or waits for it.
@@ -18,9 +18,18 @@
 // short paths against the session cwd on the way in and render short names
 // relative to that same cwd on the way out. An absolute path never lands in a
 // message body.
+//
+// Normalization is lexical and it happens HERE, for every tool input: `resolve`
+// folds `.`, `..`, repeated and trailing separators and keeps an absolute input
+// absolute, so one file has one spelling for arbitration and for the
+// subscription table. The broker deliberately does not normalize — there string
+// equality IS a path (docs/features/edit-lock-protocol.md) — so a verbatim `..`
+// spelling would be granted a SECOND lease on a file another session holds, and
+// `edit_lock_watch` would miss the held canonical path entirely.
 
-import { basename, isAbsolute, relative, resolve } from 'node:path'
+import { basename, relative, resolve } from 'node:path'
 import { isLeaseConflict } from './client.js'
+import { createWatchCoordinator } from './watch.js'
 
 /** Retention bound in minutes; the protocol clamps here and so does the tool. */
 export const MAX_HOLD_MINUTES = 60
@@ -28,17 +37,191 @@ export const MAX_HOLD_MINUTES = 60
 /** The negotiation reply tool: registered only while a request is pending. */
 export const REPLY_TOOL = 'edit_lock_reply'
 
+/** The release-subscription tool: one path, one in-memory subscription. */
+export const WATCH_TOOL = 'edit_lock_watch'
+
 /** Default retention when the model asks for one without a length. */
 export const DEFAULT_HOLD_MINUTES = MAX_HOLD_MINUTES
 
 /**
- * Single-field text rendering, the shape every tool in this bundle uses.
- * @param {string} field
+ * UI-only presentation data handed from `execute` to `presentationMeta`
+ * (openspec edit-lock-tool-cards, design D1). The conversation cards need a
+ * few facts the model never reads — the try_steal deadline, the per-row
+ * validity of a status answer, the paths of a degraded call — and the hard
+ * constraint is that the result object stays field-for-field what it was. So
+ * those facts never become result fields: `execute` files them here and
+ * `presentationMeta` takes them out again.
+ *
+ * The handoff is keyed by the result's JSON text, not by object identity: the
+ * tool registry snapshots the value `execute` returned (a lossless-JSON copy,
+ * then deep-frozen) and hands that COPY to `render` and `presentationMeta`, so
+ * an identity-keyed WeakMap never hits. A copy serializes to the same text,
+ * so the same key finds the entry. Each entry is taken once (a queue per key
+ * keeps two identical concurrent answers apart), the table is bounded, and a
+ * result with no entry still gets the subset its own fields can carry.
+ * @type {Map<string, Record<string, any>[]>}
+ */
+const presented = new Map()
+
+/** Upper bound on filed-but-never-read entries (a result the host dropped). */
+const MAX_PRESENTED = 256
+
+/** @param {unknown} value @returns {string | undefined} */
+function presentationKey(value) {
+  if (value === null || typeof value !== 'object') return undefined
+  try {
+    return JSON.stringify(value)
+  } catch {
+    return undefined
+  }
+}
+
+/** @param {unknown} value @returns {Record<string, any> | undefined} */
+function takePresented(value) {
+  const key = presentationKey(value)
+  if (key === undefined) return undefined
+  const queue = presented.get(key)
+  if (queue === undefined) return undefined
+  const fields = queue.shift()
+  if (queue.length === 0) presented.delete(key)
+  return fields
+}
+
+/** Presentation metadata schema version; the client narrows on it. */
+export const LEASE_META_VERSION = 1
+
+/**
+ * The closed state set per tool (design D1). Anything outside it is never
+ * emitted, so the client can treat an unknown state as malformed metadata.
+ * @type {Record<string, readonly string[]>}
+ */
+export const LEASE_META_STATES = Object.freeze({
+  edit_lock_acquire: Object.freeze(['claimed', 'degraded']),
+  edit_lock_release: Object.freeze(['released', 'degraded']),
+  edit_lock_hold: Object.freeze(['held', 'degraded']),
+  edit_lock_status: Object.freeze(['status', 'degraded']),
+  edit_lock_try_steal: Object.freeze(['pending', 'free', 'self', 'degraded']),
+  edit_lock_reply: Object.freeze(['transferred', 'declined', 'degraded']),
+  edit_lock_watch: Object.freeze(['watching', 'free', 'self', 'released', 'reset', 'unsupported', 'cancelled', 'degraded']),
+})
+
+/**
+ * File the presentation data for one result and hand the result back
+ * untouched: nothing is added to the object the model reads.
+ * @template {object} T
+ * @param {T} value
+ * @param {Record<string, any> | undefined} fields
+ * @returns {T}
+ */
+function present(value, fields) {
+  const key = presentationKey(value)
+  if (fields === undefined || key === undefined) return value
+  const queue = presented.get(key)
+  if (queue === undefined) presented.set(key, [fields])
+  else queue.push(fields)
+  // Insertion order is age order: drop the oldest key once over the bound.
+  if (presented.size > MAX_PRESENTED) {
+    const oldest = presented.keys().next().value
+    if (oldest !== undefined) presented.delete(oldest)
+  }
+  return value
+}
+
+/**
+ * File a degraded (arbiter-unreachable) answer: the card shows "protection
+ * temporarily unavailable", never a refusal, plus what the call was about.
+ * @template {{ code: string }} T
+ * @param {T} value
+ * @param {Record<string, any>} about
+ * @returns {T}
+ */
+function presentDegraded(value, about) {
+  return present(value, { state: 'degraded', code: value.code, ...about })
+}
+
+/** @param {unknown} list @returns {string[]} */
+function strings(list) {
+  return Array.isArray(list) ? list.filter((entry) => typeof entry === 'string') : []
+}
+
+/** @param {any} holder */
+function holderOf(holder) {
+  return holder && typeof holder === 'object' && typeof holder.label === 'string' && typeof holder.session === 'string'
+    ? { label: holder.label, session: holder.session }
+    : undefined
+}
+
+/**
+ * The presentation fields one result's OWN fields can carry. This is both the
+ * base every `execute` extends and the whole answer for a result that has no
+ * filed entry.
+ * @param {string} tool
+ * @param {any} value
+ * @returns {Record<string, any> | undefined}
+ */
+function derivedFields(tool, value) {
+  if (value === null || typeof value !== 'object') return undefined
+  if (value.degraded === true) {
+    const code = typeof value.code === 'string' ? value.code : 'internal'
+    // A watch without release events or one cancelled underneath it is not an
+    // unreachable arbiter, and the card must not read it as one.
+    if (tool === WATCH_TOOL && code === 'release-events-unsupported') return { state: 'unsupported', code }
+    if (tool === WATCH_TOOL && code === 'watch-cancelled') return { state: 'cancelled', code }
+    return { state: 'degraded', code }
+  }
+  switch (tool) {
+    case 'edit_lock_acquire':
+      return { state: 'claimed', paths: strings(value.paths) }
+    case 'edit_lock_release':
+      return { state: 'released', released: strings(value.released), notOwned: strings(value.notOwned) }
+    case 'edit_lock_hold':
+      return {
+        state: 'held',
+        held: (Array.isArray(value.held) ? value.held : []).map((/** @type {any} */ row) => ({ path: String(row?.path ?? ''), holdUntil: typeof row?.holdUntil === 'number' ? row.holdUntil : null })),
+      }
+    case 'edit_lock_status':
+      return { state: 'status', mine: strings(value.mine).map((path) => ({ path })), others: [] }
+    case 'edit_lock_try_steal': {
+      if (!['pending', 'free', 'self'].includes(value.state)) return undefined
+      const holder = holderOf(value.holder)
+      return { state: value.state, ...(typeof value.request_id === 'string' ? { requestId: value.request_id } : {}), ...(holder ? { holder } : {}) }
+    }
+    case REPLY_TOOL:
+      return {
+        state: value.state === 'transferred' ? 'transferred' : 'declined',
+        ...(typeof value.request_id === 'string' ? { requestId: value.request_id } : {}),
+        ...(typeof value.decision === 'string' ? { decision: value.decision } : {}),
+      }
+    case WATCH_TOOL: {
+      if (!LEASE_META_STATES[WATCH_TOOL].includes(value.state)) return undefined
+      const holder = holderOf(value.holder)
+      return { state: value.state, ...(typeof value.file_path === 'string' ? { path: value.file_path } : {}), ...(holder ? { holder } : {}) }
+    }
+    default:
+      return undefined
+  }
+}
+
+/**
+ * The output contract of every edit-lock tool. `render` is byte-identical to
+ * the single-field text rendering it replaces (the model reads `message` and
+ * nothing else from the text channel); `presentationMeta` is the UI-only
+ * channel the conversation cards read from the persisted tool result.
+ * Short names only and epoch-ms instants: an absolute path never appears
+ * here either.
+ * @param {string} tool
  */
-function textOutput(field) {
+function leaseOutput(tool) {
   return {
     schema: { type: 'object' },
-    render: (/** @type {any} */ _args, /** @type {any} */ result) => [{ type: 'text', text: result[field] }],
+    render: (/** @type {any} */ _args, /** @type {any} */ result) => [{ type: 'text', text: result.message }],
+    // `null`, never `undefined`, for a value it cannot describe: the registry
+    // rejects a non-JSON projection, which would turn the call into an error.
+    presentationMeta: (/** @type {any} */ _args, /** @type {any} */ value) => {
+      const fields = takePresented(value) ?? derivedFields(tool, value)
+      if (fields === undefined || !LEASE_META_STATES[tool]?.includes(fields.state)) return null
+      return { editLock: { v: LEASE_META_VERSION, tool, ...fields } }
+    },
   }
 }
 
@@ -93,8 +276,29 @@ export function shortName(path, cwd) {
 }
 
 /**
- * Resolve the model's path batch to the absolute, de-duplicated list the
- * protocol accepts.
+ * One file, one spelling: the lexical normalization every tool input passes
+ * through before it can become a claim, a retention, a release, a transfer
+ * request or a release subscription.
+ *
+ * `resolve` is the right instrument and no other is needed: it folds `.`,
+ * `..`, repeated and trailing separators, keeps an absolute input absolute
+ * (the base is then ignored) and resolves a relative one against the session
+ * cwd. It touches no filesystem, so symlinks and case are left alone — the
+ * protocol makes that the client's call, and it keys leases by string equality,
+ * which is exactly why `/p/src/../src/a.js` and `/p/src/a.js` must never reach
+ * it as two paths.
+ * @param {string} raw
+ * @param {string} cwd
+ * @returns {string}
+ */
+function canonicalPath(raw, cwd) {
+  return resolve(cwd, raw)
+}
+
+/**
+ * Resolve the model's path batch to the canonical, de-duplicated list the
+ * protocol accepts. Normalization happens before the de-duplication, so two
+ * spellings of one file collapse into one entry instead of becoming two claims.
  * @param {unknown} paths
  * @param {string} cwd
  * @returns {string[]}
@@ -106,13 +310,15 @@ function absoluteBatch(paths, cwd) {
   for (const entry of paths) {
     const raw = text(entry)
     if (raw === undefined) throw new Error('every entry of paths must be a non-empty string')
-    const absolute = isAbsolute(raw) ? raw : resolve(cwd, raw)
+    const absolute = canonicalPath(raw, cwd)
     if (!out.includes(absolute)) out.push(absolute)
   }
   return out
 }
 
 /**
+ * The single-path form of {@link absoluteBatch}: normalize before the path can
+ * reach the arbiter or the subscription coordinator.
  * @param {unknown} filePath
  * @param {string} cwd
  * @returns {string}
@@ -120,7 +326,7 @@ function absoluteBatch(paths, cwd) {
 function absoluteOne(filePath, cwd) {
   const raw = text(filePath)
   if (raw === undefined) throw new Error('file_path must be a non-empty string')
-  return isAbsolute(raw) ? raw : resolve(cwd, raw)
+  return canonicalPath(raw, cwd)
 }
 
 /** `2026-05-05T12:00:00.000Z` for a validity instant. @param {number} at epoch ms */
@@ -177,6 +383,70 @@ 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
+ * @returns {any}
+ */
+function cancelledOutcome(short) {
+  return {
+    degraded: true,
+    code: 'watch-cancelled',
+    message: `The release subscription for ${short} was cancelled before it could be established (this agent or the feature was shut down), so nothing is pending. Call edit_lock_watch again in a live agent if you still need the path.`,
+  }
+}
+
+/**
+ * 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}
+ */
+function stillWatching(watches, entry) {
+  return entry.state === 'watching' && watches.peek(entry.sessionId, entry.path) === entry
+}
+
 /**
  * Create the tool definitions.
  *
@@ -185,10 +455,15 @@ export function describeConflicts(error, cwd, at) {
  * @param {(agent: any) => { id: string, session: string, label: string }} options.ownerOf
  * @param {(agent: any, text: string) => any} [options.deliverNotice] model-facing
  *   notice channel, used only where a tool result cannot carry the outcome
- * @returns {any[]} six definitions, `REPLY_TOOL` included (the plugin decides
+ * @param {import('./watch.js').WatchCoordinator} [options.watchCoordinator] the
+ *   subscription coordinator shared with the plugin's event routing
+ * @param {import('./watch.js').WatchMount} [options.mount] the mount reference
+ *   that owns this call's subscription, when a mount is in play
+ * @returns {any[]} seven definitions, `REPLY_TOOL` included (the plugin decides
  *   when that one becomes visible)
  */
-export function createLeaseTools({ client, ownerOf, deliverNotice = () => {} }) {
+export function createLeaseTools({ client, ownerOf, deliverNotice = () => {}, watchCoordinator = createWatchCoordinator(), mount }) {
+  const watches = watchCoordinator
   return [
     {
       name: 'edit_lock_acquire',
@@ -201,7 +476,7 @@ export function createLeaseTools({ client, ownerOf, deliverNotice = () => {} })
         },
         required: ['paths'],
       },
-      output: textOutput('message'),
+      output: leaseOutput('edit_lock_acquire'),
       async execute(/** @type {any} */ args, /** @type {any} */ exec) {
         const owner = ownerOf(exec?.agent)
         const cwd = requireCwd(exec)
@@ -210,15 +485,16 @@ export function createLeaseTools({ client, ownerOf, deliverNotice = () => {} })
           const reply = await client.acquire(owner, paths, cwd)
           const granted = Array.isArray(reply?.granted) ? reply.granted : []
           const claimed = granted.map((/** @type {any} */ lease) => shortName(String(lease?.path ?? ''), cwd))
-          return {
+          const result = {
             paths: claimed,
             message: claimed.length > 0
               ? `Claimed ${claimed.length} path(s) for this turn: ${claimed.join(', ')}.`
               : 'Nothing was claimed.',
           }
+          return present(result, { state: 'claimed', paths: [...claimed] })
         } catch (error) {
           if (isLeaseConflict(error)) throw new Error(describeConflicts(error, cwd, Date.now()))
-          if (isTransport(error)) return unavailable(error, 'nothing was claimed')
+          if (isTransport(error)) return presentDegraded(unavailable(error, 'nothing was claimed'), { paths: paths.map((path) => shortName(path, cwd)) })
           throw error
         }
       },
@@ -235,7 +511,7 @@ export function createLeaseTools({ client, ownerOf, deliverNotice = () => {} })
         },
         required: ['paths'],
       },
-      output: textOutput('message'),
+      output: leaseOutput('edit_lock_release'),
       async execute(/** @type {any} */ args, /** @type {any} */ exec) {
         const owner = ownerOf(exec?.agent)
         const cwd = requireCwd(exec)
@@ -244,7 +520,7 @@ export function createLeaseTools({ client, ownerOf, deliverNotice = () => {} })
         try {
           reply = await client.request('release', { owner, paths })
         } catch (error) {
-          if (isTransport(error)) return unavailable(error, 'the release was not confirmed')
+          if (isTransport(error)) return presentDegraded(unavailable(error, 'the release was not confirmed'), { paths: paths.map((path) => shortName(path, cwd)) })
           throw error
         }
         const released = (Array.isArray(reply?.released) ? reply.released : []).map((/** @type {any} */ path) => shortName(String(path), cwd))
@@ -252,13 +528,13 @@ export function createLeaseTools({ client, ownerOf, deliverNotice = () => {} })
         const lines = []
         lines.push(released.length > 0 ? `Released ${released.length} path(s): ${released.join(', ')}.` : 'Released nothing.')
         if (notOwned.length > 0) lines.push(`Not held by this session, so there was nothing to release: ${notOwned.join(', ')}.`)
-        return { released, notOwned, message: lines.join('\n') }
+        return present({ released, notOwned, message: lines.join('\n') }, { state: 'released', released: [...released], notOwned: [...notOwned] })
       },
     },
 
     {
       name: 'edit_lock_hold',
-      description: `Keep paths this session already owns past the end of this turn, for up to ${MAX_HOLD_MINUTES} minutes from now. Use it when the work continues after this turn; the paths stay yours and other sessions are refused until the deadline. A longer request is clamped, not ignored. When the deadline passes the paths become available and nothing is announced.`,
+      description: `Keep paths this session already owns past the end of this turn, for up to ${MAX_HOLD_MINUTES} minutes from now. Use it when the work continues after this turn; the paths stay yours and other sessions are refused until the deadline. A longer request is clamped, not ignored. When the deadline passes the paths become available again, and the expiry is announced only to a session that explicitly subscribed to that path's release with edit_lock_watch: a matching subscriber gets the usual notice that it may claim the path again, while with no subscriber nothing is announced.`,
       parameters: {
         type: 'object',
         properties: {
@@ -270,7 +546,7 @@ export function createLeaseTools({ client, ownerOf, deliverNotice = () => {} })
         },
         required: ['paths'],
       },
-      output: textOutput('message'),
+      output: leaseOutput('edit_lock_hold'),
       async execute(/** @type {any} */ args, /** @type {any} */ exec) {
         const owner = ownerOf(exec?.agent)
         const cwd = requireCwd(exec)
@@ -286,23 +562,26 @@ export function createLeaseTools({ client, ownerOf, deliverNotice = () => {} })
           if (code === 'not-owned') {
             throw new Error(`This session does not own ${paths.map((path) => shortName(path, cwd)).join(', ')}. Retention only extends ownership that already exists — claim the paths with edit_lock_acquire first.`)
           }
-          if (isTransport(error)) return unavailable(error, 'no retention was recorded')
+          if (isTransport(error)) return presentDegraded(unavailable(error, 'no retention was recorded'), { paths: paths.map((path) => shortName(path, cwd)) })
           throw error
         }
         const held = Array.isArray(reply?.held) ? reply.held : []
         const at = Date.now()
+        /** @type {{ path: string, holdUntil: number }[]} */
+        const shown = []
         const entries = held.map((/** @type {any} */ row) => {
           const until = typeof row?.holdUntil === 'number' ? row.holdUntil : typeof row?.expiresAt === 'number' ? row.expiresAt : at
+          shown.push({ path: shortName(String(row?.path ?? ''), cwd), holdUntil: until })
           return `${shortName(String(row?.path ?? ''), cwd)} until ${instant(until)} (about ${Math.ceil(secondsUntil(until, at) / 60)}m from now)`
         })
-        return {
+        return present({
           // Short names only: an absolute path never appears in a tool result,
           // not even in a structured field the model also reads.
           held: held.map((/** @type {any} */ row) => ({ path: shortName(String(row?.path ?? ''), cwd), holdUntil: row?.holdUntil ?? null })),
           message: entries.length > 0
-            ? `Kept ${entries.length} path(s) past this turn: ${entries.join(', ')}. At most ${MAX_HOLD_MINUTES} minutes per request; a deadline that passes announces nothing — the paths simply become available.`
+            ? `Kept ${entries.length} path(s) past this turn: ${entries.join(', ')}. At most ${MAX_HOLD_MINUTES} minutes per request; a deadline that passes simply makes the paths available, and the expiry is announced only to a session that explicitly subscribed to that path with edit_lock_watch — a matching subscriber gets the usual chance to claim it again, while with no subscriber nothing is announced.`
             : 'Nothing was retained.',
-        }
+        }, { state: 'held', held: shown })
       },
     },
 
@@ -317,7 +596,7 @@ export function createLeaseTools({ client, ownerOf, deliverNotice = () => {} })
         },
         required: ['file_path'],
       },
-      output: textOutput('message'),
+      output: leaseOutput('edit_lock_try_steal'),
       async execute(/** @type {any} */ args, /** @type {any} */ exec) {
         const owner = ownerOf(exec?.agent)
         const cwd = requireCwd(exec)
@@ -328,9 +607,9 @@ export function createLeaseTools({ client, ownerOf, deliverNotice = () => {} })
           reply = await client.requestTransfer(path, owner)
         } catch (error) {
           const code = codeOf(error)
-          if (code === 'free') return { state: 'free', message: `Nobody holds ${short} right now: edit it directly, or claim it with edit_lock_acquire so another session cannot take it mid-work.` }
-          if (code === 'self') return { state: 'self', message: `This session already owns ${short}; no transfer is needed.` }
-          if (isTransport(error)) return unavailable(error, 'no transfer request was created')
+          if (code === 'free') return present({ state: 'free', message: `Nobody holds ${short} right now: edit it directly, or claim it with edit_lock_acquire so another session cannot take it mid-work.` }, { state: 'free', path: short })
+          if (code === 'self') return present({ state: 'self', message: `This session already owns ${short}; no transfer is needed.` }, { state: 'self', path: short })
+          if (isTransport(error)) return presentDegraded(unavailable(error, 'no transfer request was created'), { path: short })
           throw error
         }
         const requestId = text(reply?.requestId) ?? ''
@@ -338,12 +617,12 @@ export function createLeaseTools({ client, ownerOf, deliverNotice = () => {} })
         const label = text(holder.label) ?? 'the holder'
         const session = text(holder.session) ?? 'unknown'
         const expiresAt = typeof reply?.expiresAt === 'number' ? reply.expiresAt : Date.now()
-        return {
+        return present({
           state: 'pending',
           request_id: requestId,
           holder: { label, session },
           message: `Request ${requestId} for ${short} is pending with "${label}" (session ${session}). Do not modify ${short} until ownership is granted — a pending request is not an approval, and edits keep being refused meanwhile. The holder answers with edit_lock_reply (release hands it over, keep keeps it); an unanswered request expires in about ${secondsUntil(expiresAt, Date.now())}s and ownership stays where it is. A message will tell you how it settled.`,
-        }
+        }, { state: 'pending', path: short, requestId, holder: { label, session }, expiresAt })
       },
     },
 
@@ -359,7 +638,7 @@ export function createLeaseTools({ client, ownerOf, deliverNotice = () => {} })
         },
         required: ['request_id', 'decision'],
       },
-      output: textOutput('message'),
+      output: leaseOutput(REPLY_TOOL),
       async execute(/** @type {any} */ args, /** @type {any} */ exec) {
         const owner = ownerOf(exec?.agent)
         const requestId = text(args?.request_id)
@@ -374,7 +653,7 @@ export function createLeaseTools({ client, ownerOf, deliverNotice = () => {} })
           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 (isTransport(error)) return unavailable(error, 'the answer was not delivered')
+          if (isTransport(error)) return presentDegraded(unavailable(error, 'the answer was not delivered'), { requestId, decision })
           throw error
         }
         const state = text(reply?.state) ?? 'declined'
@@ -384,14 +663,14 @@ export function createLeaseTools({ client, ownerOf, deliverNotice = () => {} })
           // result it may have already reasoned past.
           deliverNotice(exec?.agent, `Ownership handed over: request ${requestId} is settled and this session no longer holds that path. Claim it again with edit_lock_acquire if you still need it.`)
         }
-        return {
+        return present({
           request_id: requestId,
           decision,
           state,
           message: state === 'transferred'
             ? `Request ${requestId}: transferred. The requester owns the path now; this session no longer holds it.`
             : `Request ${requestId}: declined. Ownership is unchanged and the path is still this session's.`,
-        }
+        }, { state: state === 'transferred' ? 'transferred' : 'declined', requestId, decision })
       },
     },
 
@@ -400,7 +679,7 @@ export function createLeaseTools({ client, ownerOf, deliverNotice = () => {} })
       description:
         'Read-only ownership report: the paths this session holds, and the sessions that currently hold paths in this working directory. Grants nothing and changes nothing. Ownership is arbitrated centrally, so the answer covers other processes too.',
       parameters: { type: 'object', properties: {}, required: [] },
-      output: textOutput('message'),
+      output: leaseOutput('edit_lock_status'),
       async execute(/** @type {any} */ _args, /** @type {any} */ exec) {
         const owner = ownerOf(exec?.agent)
         const cwd = requireCwd(exec)
@@ -408,7 +687,7 @@ export function createLeaseTools({ client, ownerOf, deliverNotice = () => {} })
         try {
           reply = await client.status({ scope: cwd })
         } catch (error) {
-          if (isTransport(error)) return unavailable(error, 'no ownership could be read')
+          if (isTransport(error)) return presentDegraded(unavailable(error, 'no ownership could be read'), {})
           throw error
         }
         const leases = Array.isArray(reply?.leases) ? reply.leases : []
@@ -416,12 +695,18 @@ export function createLeaseTools({ client, ownerOf, deliverNotice = () => {} })
         const mine = leases.filter((/** @type {any} */ lease) => text(lease?.owner?.id) === owner.id || text(lease?.owner?.session) === owner.session)
         const others = leases.filter((/** @type {any} */ lease) => !mine.includes(lease))
         const lines = []
+        /** @type {{ path: string, until: number, retained: boolean }[]} */
+        const shownMine = []
+        /** @type {{ path: string, label: string, session: string, until: number, lapsed: boolean }[]} */
+        const shownOthers = []
         lines.push(mine.length > 0 ? `Held by this session (${mine.length}):` : 'This session holds nothing.')
         for (const lease of mine) {
           const until = retainedUntil(lease)
+          const expiresAt = typeof lease?.expiresAt === 'number' ? lease.expiresAt : at
           const validity = until === undefined
-            ? `valid for about ${secondsUntil(typeof lease?.expiresAt === 'number' ? lease.expiresAt : at, at)}s`
+            ? `valid for about ${secondsUntil(expiresAt, at)}s`
             : `retained until ${instant(until)}`
+          shownMine.push({ path: shortName(String(lease?.path ?? ''), cwd), until: until ?? expiresAt, retained: until !== undefined })
           lines.push(`- ${shortName(String(lease?.path ?? ''), cwd)} — ${validity}`)
         }
         if (others.length > 0) {
@@ -431,10 +716,113 @@ export function createLeaseTools({ client, ownerOf, deliverNotice = () => {} })
             const label = text(holder.label) ?? 'another session'
             const session = text(holder.session) ?? 'unknown'
             const target = Math.max(typeof lease?.expiresAt === 'number' ? lease.expiresAt : 0, typeof lease?.holdUntil === 'number' ? lease.holdUntil : 0)
+            shownOthers.push({ path: shortName(String(lease?.path ?? ''), cwd), label, session, until: target, lapsed: !(target > at) })
             lines.push(`- ${shortName(String(lease?.path ?? ''), cwd)} — "${label}" (session ${session}), ${target > at ? `about ${secondsUntil(target, at)}s left` : 'lapsed, claimable'}`)
           }
         }
-        return { mine: mine.map((/** @type {any} */ lease) => shortName(String(lease?.path ?? ''), cwd)), message: lines.join('\n') }
+        return present(
+          { mine: mine.map((/** @type {any} */ lease) => shortName(String(lease?.path ?? ''), cwd)), message: lines.join('\n') },
+          { state: 'status', at, mine: shownMine, others: shownOthers },
+        )
+      },
+    },
+
+    {
+      name: WATCH_TOOL,
+      description:
+        'Wait for the next release of one contested path without polling it. Use it after an acquisition conflict or a declined/expired transfer request. The answer says whether anything is actually pending: a path that is already free or already yours returns that immediately and keeps no subscription. While it is held by another session, this subscribes once for this session and the next release arrives as a message; a release is only an opportunity to call edit_lock_acquire, never a grant of ownership, and another waiting session may claim it first. Repeating the call is idempotent.',
+      parameters: {
+        type: 'object',
+        properties: {
+          file_path: { type: 'string', description: 'The contested file to watch for a release, absolute or relative to the session working directory.' },
+        },
+        required: ['file_path'],
+      },
+      output: leaseOutput(WATCH_TOOL),
+      async execute(/** @type {any} */ args, /** @type {any} */ exec) {
+        const owner = ownerOf(exec?.agent)
+        const cwd = requireCwd(exec)
+        const path = absoluteOne(args?.file_path, cwd)
+        const short = shortName(path, cwd)
+        // Every answer below carries the watched short path for the card, the
+        // degraded ones included (their result object has no path field).
+        const settle = (/** @type {any} */ value) => present(value, { ...derivedFields(WATCH_TOOL, value), path: short })
+        // Registration comes FIRST (D2): a release that lands between the
+        // registration and the authoritative read is caught by the event
+        // 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.`,
+        })
       },
     },
   ]