weir-harness 2.1.1 → 2.1.3

package/src/capabilities/mcp-runtime.js

@@ -72,32 +72,6 @@ export function createMcpRuntime() {
   }
 }
 
-/**
- * Per-identity FIFO for every operation that opens a runtime fence
- * (runtime.begin). Same-identity operations run strictly one after another
- * (design D6), so a Restart can never begin while an edit-mode Test holds the
- * fence and leave the server mounted but refusing calls. A task's failure never
- * poisons the queue; different identities never wait on each other. Not
- * reentrant: callers already inside serialize() pass their token instead.
- */
-export function createMcpIdentityLock() {
-  const tails = new Map()
-  return function serialize(identity, task) {
-    const previous = tails.get(identity) ?? Promise.resolve()
-    const run = previous.then(() => task())
-    const tail = run.then(() => {}, () => {})
-    tails.set(identity, tail)
-    void tail.then(() => { if (tails.get(identity) === tail) tails.delete(identity) })
-    return run
-  }
-}
-
-const fallbackLocks = new WeakMap()
-/** The manager's own lock, or one stable lock per manager object for fakes/older faces. */
-export function mcpIdentityLockFor(manager) {
-  if (typeof manager?.serialize === 'function') return (identity, task) => manager.serialize(identity, task)
-  if (!manager || (typeof manager !== 'object' && typeof manager !== 'function')) return createMcpIdentityLock()
-  let lock = fallbackLocks.get(manager)
-  if (!lock) { lock = createMcpIdentityLock(); fallbackLocks.set(manager, lock) }
-  return lock
-}
+// Compatibility exports: the implementations live with the manager-owned
+// coordinator so queue/fence/drain rules have one semantic implementation.
+export { createMcpIdentityLock, mcpIdentityLockFor } from './mcp-operation-coordinator.js'

package/src/capabilities/skill-inventory.js

@@ -3,6 +3,8 @@ import { dirname, join, resolve } from 'node:path'
 import { createHash } from 'node:crypto'
 import { createSkillIdentity } from './skill-identity.js'
 import { parseSkillText } from './frontmatter.js'
+import { canonicalPathKey } from './skill-applicability.js'
+import { requireSkillScanPaths } from './skill-scan-path-registry.js'
 
 export const SKILL_ROOT_RANKS = Object.freeze({ 'project-dsh': 100, 'project-agents': 200, custom: 300, 'user-dsh': 400, 'user-agents': 500, bundled: 600 })
 
@@ -19,7 +21,7 @@ export async function findProjectRoot(cwd, fs = nodeFs) {
 }
 
 /** Homes are supplied by the host adapter, not inferred from the process profile. */
-export async function resolveSkillRoots({ cwd, dshHome, agentsHome, customSkillDirs = [], bundledSkillDir, weirBuiltinDir, includeDefaultRoots = true }, fs = nodeFs) {
+export async function resolveSkillRoots({ cwd, dshHome, agentsHome, customSkillDirs = [], bundledSkillDir, weirBuiltinDir, includeDefaultRoots = true, skillScanPathRegistry }, fs = nodeFs) {
   const roots = []
   const add = (path, source, scope, extra = {}) => roots.push({ path: resolve(path), source, scope, rank: SKILL_ROOT_RANKS[source], ...extra })
   if (includeDefaultRoots && cwd !== undefined) {
@@ -37,7 +39,21 @@ export async function resolveSkillRoots({ cwd, dshHome, agentsHome, customSkillD
   }
   // Host bundles are not automatically Weir-owned or selected.
   if (bundledSkillDir !== undefined) add(bundledSkillDir, 'bundled', 'custom', { trustedHost: true })
-  return roots
+  // Existing composition/default roots keep their source, scope and rank. User
+  // registry roots append in registry order and never replace Creative's roots.
+  if (skillScanPathRegistry) {
+    for (const path of await requireSkillScanPaths(skillScanPathRegistry)) add(path, 'custom', 'custom')
+  }
+  // Canonical identity, not lexical spelling, controls enumeration. A root whose
+  // canonical key cannot be proven stays independent so discovery's established
+  // partial-failure path reports its real unreadable/missing outcome.
+  const seen = new Set()
+  return roots.filter((root, index) => {
+    const key = canonicalPathKey(root.path) ?? `unresolved:${index}`
+    if (seen.has(key)) return false
+    seen.add(key)
+    return true
+  })
 }
 
 const rootKey = root => JSON.stringify([resolve(root.path), root.source, root.scope, root.rank])

package/src/capabilities/skill-scan-path-registry.js

@@ -0,0 +1,238 @@
+// Profile-scoped, user-managed Skill discovery roots. The capability store owns
+// locking, revisions and crash-safe writes; this module owns strict payload
+// validation and canonical directory semantics. No mutation executes a command,
+// appends to a session, or treats a failed write as a discovery change.
+import { constants } from 'node:fs'
+import { access, realpath, stat } from 'node:fs/promises'
+import { homedir } from 'node:os'
+import * as nodePath from 'node:path'
+import { canonicalPathKey } from './skill-applicability.js'
+
+export const SKILL_SCAN_PATH_UNIT = Object.freeze({ kind: 'skill-scan-paths' })
+
+const message = error => error instanceof Error ? error.message : String(error)
+const codeOf = error => error?.code
+const missing = error => ['ENOENT', 'ENOTDIR'].includes(codeOf(error))
+const denied = error => ['EACCES', 'EPERM'].includes(codeOf(error))
+const clone = paths => [...paths]
+
+class SkillPathFailure extends Error {
+  constructor(code, text, result = undefined) {
+    super(text)
+    this.name = 'SkillPathFailure'
+    this.code = code
+    this.result = result
+  }
+}
+
+const validation = (code, text) => ({
+  status: 'validation-failed', saved: false, revision: null, paths: null,
+  error: { code, message: text },
+})
+
+const unavailable = (code, text, revision = null) => ({
+  status: 'unavailable', saved: false, revision, paths: null,
+  error: { code, message: text },
+})
+
+/**
+ * Comparison of paths already canonicalized by realpath. Registry payloads never
+ * store this folded key: the canonical spelling remains the display/read value.
+ */
+function storedPathKey(path, pathApi, platform) {
+  let key = pathApi.normalize(path)
+  if (platform === 'win32') key = key.replaceAll('\\', '/').toLowerCase()
+  return key.replace(/\/+$/, '')
+}
+
+/** Strict payload shape: unknown or malformed records are never repaired. */
+function payloadPaths(payload, pathApi, platform) {
+  if (payload === undefined) return []
+  if (payload === null || typeof payload !== 'object' || Array.isArray(payload)
+    || Object.keys(payload).length !== 1 || !Array.isArray(payload.paths)
+    || !payload.paths.every(path => typeof path === 'string' && path.length > 0 && pathApi.isAbsolute(path))) {
+    throw new SkillPathFailure('invalid-payload', 'Skill scan path registry payload is invalid')
+  }
+  const seen = new Set()
+  for (const path of payload.paths) {
+    const key = storedPathKey(path, pathApi, platform)
+    if (seen.has(key)) throw new SkillPathFailure('invalid-payload', 'Skill scan path registry contains duplicate paths')
+    seen.add(key)
+  }
+  return clone(payload.paths)
+}
+
+/**
+ * @param {{
+ *   store: ReturnType<typeof import('./store/store.js').openCapabilityStore>,
+ *   fs?: { realpath(path: string): Promise<string>, stat(path: string): Promise<{ isDirectory(): boolean }>, access(path: string, mode?: number): Promise<void> },
+ *   home?: string,
+ *   platform?: string,
+ *   pathApi?: typeof nodePath,
+ * }} options
+ */
+export function createSkillScanPathRegistry(options) {
+  const store = options.store
+  const fs = options.fs ?? { realpath, stat, access }
+  const platform = options.platform ?? process.platform
+  const pathApi = options.pathApi ?? (platform === 'win32' ? nodePath.win32 : nodePath)
+  const home = options.home ?? homedir()
+  const unit = SKILL_SCAN_PATH_UNIT
+
+  const pathKey = path => storedPathKey(path, pathApi, platform)
+
+  function expanded(input) {
+    if (typeof input !== 'string') throw new SkillPathFailure('path-invalid', 'Skill scan path must be a string')
+    const trimmed = input.trim()
+    if (!trimmed) throw new SkillPathFailure('path-empty', 'Skill scan path cannot be empty')
+    let value = trimmed
+    if (trimmed === '~') value = home
+    else if (trimmed.startsWith('~/') || (platform === 'win32' && trimmed.startsWith('~\\'))) {
+      if (typeof home !== 'string' || !pathApi.isAbsolute(home)) throw new SkillPathFailure('home-unavailable', 'Home directory is unavailable')
+      value = pathApi.resolve(home, trimmed.slice(2))
+    }
+    if (!pathApi.isAbsolute(value)) throw new SkillPathFailure('path-not-absolute', 'Skill scan path must be absolute or start with ~')
+    return value
+  }
+
+  async function canonicalForAdd(input) {
+    const value = expanded(input)
+    let canonical
+    try { canonical = await fs.realpath(value) }
+    catch (error) {
+      if (missing(error)) throw new SkillPathFailure('path-missing', `Skill scan path does not exist: ${value}`)
+      if (denied(error)) throw new SkillPathFailure('path-unreadable', `Skill scan path is unreadable: ${value}`)
+      throw new SkillPathFailure('path-canonicalization-failed', `Cannot canonicalize Skill scan path: ${message(error)}`)
+    }
+    let info
+    try { info = await fs.stat(canonical) }
+    catch (error) {
+      throw new SkillPathFailure(denied(error) ? 'path-unreadable' : 'path-missing', `Cannot inspect Skill scan path: ${message(error)}`)
+    }
+    if (!info.isDirectory()) throw new SkillPathFailure('path-not-directory', `Skill scan path is not a directory: ${canonical}`)
+    try { await fs.access(canonical, constants.R_OK) }
+    catch (error) { throw new SkillPathFailure('path-unreadable', `Skill scan path is not readable: ${message(error)}`) }
+    return { path: canonical, key: pathKey(canonical) }
+  }
+
+  async function keyForRemove(input) {
+    const value = expanded(input)
+    try { return pathKey(await fs.realpath(value)) }
+    catch (error) {
+      if (!missing(error)) {
+        throw new SkillPathFailure(denied(error) ? 'path-unreadable' : 'path-canonicalization-failed', `Cannot canonicalize Skill scan path: ${message(error)}`)
+      }
+      // Removal must remain possible after a directory disappears. The shared
+      // platform key canonicalizes the deepest surviving ancestor without
+      // requiring the removed directory itself to exist.
+      const key = canonicalPathKey(value, platform)
+      if (key === null) throw new SkillPathFailure('path-canonicalization-failed', `Cannot canonicalize Skill scan path: ${value}`)
+      return key
+    }
+  }
+
+  async function read() {
+    let record
+    try { record = await store.read(unit) }
+    catch (error) { return unavailable('read-failed', `Skill scan path registry is unreadable: ${message(error)}`) }
+    if (record.kind === 'absent') return { status: 'ok', revision: 0, paths: [] }
+    if (record.kind !== 'ok') return unavailable(record.kind, `Skill scan path registry is ${record.kind}`)
+    try {
+      return { status: 'ok', revision: record.revision, paths: payloadPaths(record.payload, pathApi, platform) }
+    } catch (error) {
+      return unavailable(error?.code ?? 'invalid-payload', message(error), record.revision)
+    }
+  }
+
+  async function currentAfterConflict(result) {
+    const current = await read()
+    if (current.status === 'ok') return { revision: current.revision, paths: current.paths, error: null }
+    return {
+      revision: result.revision ?? current.revision ?? null,
+      paths: null,
+      error: { code: 'current-state-unavailable', message: `Revision conflict; current registry state is unavailable: ${current.error?.message ?? current.status}` },
+    }
+  }
+
+  async function mutate(kind, input, expectedRevision, options = {}) {
+    if (!Number.isSafeInteger(expectedRevision) || expectedRevision < 0) {
+      return validation('revision-invalid', 'expectedRevision must be a non-negative safe integer')
+    }
+    let candidate
+    try { candidate = kind === 'add' ? await canonicalForAdd(input) : { key: await keyForRemove(input) } }
+    catch (error) {
+      if (error instanceof SkillPathFailure) return validation(error.code, error.message)
+      return validation('path-validation-failed', message(error))
+    }
+
+    let result
+    try {
+      result = await store.commit(unit, expectedRevision, async payload => {
+        let paths
+        try { paths = payloadPaths(payload, pathApi, platform) }
+        catch (error) {
+          throw new SkillPathFailure(error?.code ?? 'invalid-payload', message(error), unavailable(error?.code ?? 'invalid-payload', message(error)))
+        }
+        const index = paths.findIndex(path => pathKey(path) === candidate.key)
+        if (kind === 'add' && index >= 0) {
+          throw new SkillPathFailure('duplicate', `Skill scan path is already registered: ${paths[index]}`, {
+            status: 'duplicate', saved: false, revision: expectedRevision, paths: clone(paths),
+            error: { code: 'duplicate', message: `Skill scan path is already registered: ${paths[index]}` },
+          })
+        }
+        if (kind === 'remove' && index < 0) {
+          throw new SkillPathFailure('not-found', `Skill scan path is not registered: ${input}`, {
+            status: 'not-found', saved: false, revision: expectedRevision, paths: clone(paths),
+            error: { code: 'not-found', message: `Skill scan path is not registered: ${input}` },
+          })
+        }
+        // Ownership is rechecked under the unit lock, immediately before the
+        // payload is handed to the store's atomic write phase.
+        await options.assertOwner?.()
+        return { paths: kind === 'add' ? [...paths, candidate.path] : paths.filter((_, i) => i !== index) }
+      })
+    } catch (error) {
+      if (error?.code === 'owner-changed') throw error
+      if (error instanceof SkillPathFailure && error.result) return error.result
+      return {
+        status: 'storage-failed', saved: false, revision: null, paths: null,
+        error: { code: 'storage-failed', message: message(error) },
+      }
+    }
+
+    if (result.status === 'committed') {
+      return {
+        status: kind === 'add' ? 'saved' : 'removed', saved: true,
+        revision: result.revision, paths: clone(result.payload.paths), error: null,
+      }
+    }
+    if (result.status === 'revision-conflict') {
+      const current = await currentAfterConflict(result)
+      return {
+        status: 'revision-conflict', saved: false, revision: current.revision, paths: current.paths,
+        error: current.error ?? { code: 'revision-conflict', message: `Skill scan path registry revision ${expectedRevision} is stale` },
+      }
+    }
+    return {
+      status: result.status === 'write-failed' ? 'indeterminate' : result.status,
+      saved: false, revision: result.revision ?? null, paths: null,
+      error: { code: result.kind ?? result.status, message: result.reason ?? message(result.error ?? `Skill scan path registry write failed: ${result.status}`) },
+    }
+  }
+
+  return {
+    unit,
+    read,
+    add: (path, expectedRevision, options) => mutate('add', path, expectedRevision, options),
+    remove: (path, expectedRevision, options) => mutate('remove', path, expectedRevision, options),
+  }
+}
+
+/** Registry read failures must become visible inventory/roots failures. */
+export async function requireSkillScanPaths(registry) {
+  const result = await registry.read()
+  if (result.status !== 'ok') {
+    throw new Error(`Skill scan path registry unavailable: ${result.error?.message ?? result.status}`)
+  }
+  return result.paths
+}

package/src/capabilities/skill-selection-plugin.js

@@ -7,12 +7,14 @@ import { fileURLToPath } from 'node:url'
 import { createSkillIdentity, skillIdentityKey } from './skill-identity.js'
 import { openCapabilityStore } from './store/store.js'
 import { discoverSkillInventory, resolveSkillRoots } from './skill-inventory.js'
+import { createSkillScanPathRegistry } from './skill-scan-path-registry.js'
 import { createSkillSelectionProvider } from './skill-selection-provider.js'
 import { assertBuiltinSkillMigration } from './skill-builtin-migration.js'
 import { createOfficeAdapter, officeDenials } from './skill-office-adapter.js'
 import { createPresetInvalidation, emitPresetSelected } from './preset-invalidation.js'
 import { createLifecycleSnapshots } from './lifecycle-snapshot.js'
 import { preloadLifecycleSnapshots } from './lifecycle-preload.js'
+import { lifecycleFeedRegistry } from './lifecycle-feed.js'
 import { classifySelectionFailure } from './selection-status.js'
 import { resolveInitialSelection, baselineSkillIdentities, bindDefaultSkillNames } from './initial-selection.js'
 import { partitionUnresolvedSkills } from './skill-applicability.js'
@@ -66,6 +68,9 @@ export function createSkillSelectionPlugin(dependencies = {}) {
     /** Task 6.5 initialization reports per session (manager surface). */
     let initialReports = new Map()
     let lifecycle = null
+    const scanPathRegistry = dependencies.skillScanPathRegistry ?? createSkillScanPathRegistry({
+      store: openCapabilityStore({ profileContext: ctx.get?.('profileContext') }),
+    })
     try {
       ctx.skills.registerProvider(control => {
         const readSelection = dependencies.readSelection ?? (async options => {
@@ -133,6 +138,7 @@ export function createSkillSelectionPlugin(dependencies = {}) {
             customSkillDirs: config.customSkillDirs ?? [],
             bundledSkillDir: config.bundledSkillDir ?? process.env.DSH_BUNDLED_SKILL_DIR,
             weirBuiltinDir: config.weirBuiltinDir ?? fileURLToPath(new URL('../../skills/', import.meta.url)),
+            skillScanPathRegistry: scanPathRegistry,
           })
           const snapshot = await discoverSkillInventory({ roots, machineId, previous })
           // First-run migration check (D-H 6): a non-equivalent builtin
@@ -322,6 +328,7 @@ export function createSkillSelectionPlugin(dependencies = {}) {
         customSkillDirs: config.customSkillDirs ?? [],
         bundledSkillDir: config.bundledSkillDir ?? process.env.DSH_BUNDLED_SKILL_DIR,
         weirBuiltinDir: config.weirBuiltinDir ?? fileURLToPath(new URL('../../skills/', import.meta.url)),
+        skillScanPathRegistry: scanPathRegistry,
       })
     }
     // The shared cold-safe audit channel (cordis emit + .weir/audit.jsonl
@@ -646,6 +653,13 @@ export function createSkillSelectionPlugin(dependencies = {}) {
     }
     mounted.set(ctx, face)
     processFace = face
+    // Admission ownership is per mounted revision, not the process-local face.
+    // Resolve the manager lazily so either row may mount first; the effect owns
+    // exactly this token and its idempotent release cannot remove a replacement.
+    ctx.effect?.(() => lifecycleFeedRegistry.register({
+      lifecycle,
+      manager: () => ctx.get?.('weirMcpManager'),
+    }), 'weir-capability-lifecycle-feed')
     // The Host remote can see only this explicitly labeled preset's faces.
     // Its sessionQuery observation, not any creation-time cwd cache, owns routing.
     try {

package/src/capabilities/store/paths.js

@@ -38,6 +38,7 @@ export function resolveStoreRoot(profileContext) {
  *   | { kind: 'preset', scope: 'global', presetId: string }
  *   | { kind: 'preset', scope: 'workspace', workspaceKey: string, presetId: string }
  *   | { kind: 'mcp-registry' }
+ *   | { kind: 'skill-scan-paths' }
  *   | { kind: 'distribution', scope: string }} Unit
  */
 
@@ -77,6 +78,8 @@ export function unitLayout(unit) {
       break
     case 'mcp-registry':
       return layout(['mcp'], 'registry')
+    case 'skill-scan-paths':
+      return layout(['skills'], 'scan-paths')
     case 'distribution':
       need(u.scope)
       return layout(['distribution', /** @type {string} */ (u.scope)], 'active')

package/src/file-lease/client.js

@@ -1063,6 +1063,29 @@ export function createLeaseClient({
   // Release and replay
   // ---------------------------------------------------------------------
 
+  /**
+   * Release an explicit batch for `owner` (the `edit_lock_release` form).
+   *
+   * The ledger entry goes BEFORE the frame, and it goes even when the frame
+   * never reaches the arbiter: an explicit release is the caller's intent, and
+   * an unconfirmed transport must not resurrect a path the caller already let
+   * go of — a replay on the next connection would re-take it. Only entries this
+   * owner's lineage holds are forgotten; which of the rest the broker actually
+   * released is still its verdict (`released` / `notOwned`).
+   * @param {any} owner
+   * @param {string[]} paths
+   * @returns {Promise<any>}
+   */
+  async function release(owner, paths) {
+    const holder = normalizeOwner(owner)
+    const list = normalizePaths(paths)
+    for (const path of list) {
+      const record = ledger.get(path)
+      if (record !== undefined && record.lineage === holder.id) ledger.delete(path)
+    }
+    return await request('release', { owner: holder, paths: list })
+  }
+
   /**
    * Release everything this session holds EXCEPT retentions (design D10): the
    * `turn/end` rule. A failure is swallowed — turn-boundary release is an
@@ -1142,6 +1165,24 @@ export function createLeaseClient({
     return attempt
   }
 
+  /**
+   * Reconcile a grant whose replay record was superseded while on the wire.
+   * A newer ledger record is newer intent and must not be released by this stale
+   * operation. No record means the path was released; a grant that nevertheless
+   * arrived late needs its own release because the explicit one may have won the
+   * broker race before the grant existed.
+   * @param {any} reply
+   * @param {'granted' | 'held'} field
+   * @param {{ id: string, session: string, label: string }} owner
+   * @param {string} path
+   */
+  async function releaseStaleReplayGrant(reply, field, owner, path) {
+    if (ledger.get(path) !== undefined) return
+    const grants = Array.isArray(reply?.[field]) ? reply[field] : []
+    if (!grants.some((entry) => entry?.path === path)) return
+    await request('release', { owner, paths: [path] })
+  }
+
   /**
    * @returns {Promise<{ replayed: number, dropped: number }>}
    */
@@ -1153,11 +1194,25 @@ export function createLeaseClient({
       if (record.holdUntil === null || record.holdUntil <= at) continue
       const owner = ownerOf(record.lineage, record.session)
       const scope = lastScope
+      let current = record
       try {
         // Re-acquire first: after a daemon restart the table is empty, so a bare
-        // `hold` would be `not-owned`. The pair is idempotent by protocol.
-        await acquire(owner, [path], requireScope(scope))
+        // `hold` would be `not-owned`. The pair is idempotent by protocol. Unlike
+        // an ordinary acquire, replay must prove its snapshot is still current
+        // before either response writes the path back into the ledger.
+        const leaseScope = requireScope(scope)
+        const acquired = await request('acquire', { owner, scope: leaseScope, paths: [path] })
+        if (ledger.get(path) !== record) {
+          await releaseStaleReplayGrant(acquired, 'granted', owner, path)
+          continue
+        }
+        if (Array.isArray(acquired.granted)) remember(acquired.granted, owner, leaseScope)
+        current = ledger.get(path) ?? record
         const response = await request('hold', { owner, paths: [path], minutes: holdMinutes(record.holdUntil - at) })
+        if (ledger.get(path) !== current) {
+          await releaseStaleReplayGrant(response, 'held', owner, path)
+          continue
+        }
         applyHold(response, owner)
         replayed += 1
       } catch (error) {
@@ -1166,7 +1221,9 @@ export function createLeaseClient({
           // rather than forgetting a retention nobody has seen fail.
           break
         }
-        ledger.delete(path)
+        // A late failure is stale for the same reason as a late grant: neither
+        // may delete a newer record installed after this snapshot was taken.
+        if (ledger.get(path) === current) ledger.delete(path)
         dropped += 1
       }
     }
@@ -1290,6 +1347,7 @@ export function createLeaseClient({
     reply,
     releaseSession,
     releaseAll,
+    release,
     replayHolds,
     onEvent,
     onReset,

package/src/file-lease/negotiation.js

@@ -0,0 +1,89 @@
+// Transfer Negotiation owns the local reply window, not the broker request.
+//
+// One instance belongs to one plugin mount, matching the mount's conditional
+// tool registrations. Process-wide request dedupe remains in the plugin: a
+// sibling mount that did not deliver a request has no local window to close.
+// The broker remains the only ownership and request-settlement authority.
+
+/** @param {unknown} value @returns {string | undefined} */
+function text(value) {
+  return typeof value === 'string' && value.length > 0 ? value : undefined
+}
+
+/**
+ * Whether one structured tool outcome closes its local request.
+ *
+ * `transferred` and `declined` are broker settlements; `expired` and `stale`
+ * say the broker request is already over; `not-holder` closes only this
+ * unauthorized agent's local window. A transport result contains no broker
+ * verdict, so a valid pending request survives for an idempotent retry.
+ * Unknown results and failures retain the old finally-block behaviour and
+ * close the local request rather than inventing a new retry contract.
+ *
+ * @param {any} outcome a reply result or thrown error carrying state/code
+ * @returns {boolean}
+ */
+function closesLocalRequest(outcome) {
+  const code = text(outcome?.code)
+  const state = text(outcome?.state)
+  if (code === 'transport') return false
+  if (state === 'transferred' || state === 'declined') return true
+  if (code === 'expired' || code === 'stale' || code === 'not-holder') return true
+  return true
+}
+
+/**
+ * Create the pending-request and reply-window state for one plugin mount.
+ *
+ * This module never calls the client. In particular, local `not-holder`
+ * cleanup cannot consume the broker request, which remains answerable by the
+ * real holder.
+ */
+export function createTransferNegotiation() {
+  /** @type {WeakMap<object, Map<string, { path: string, from: any }>>} */
+  const pendingByAgent = new WeakMap()
+
+  return {
+    /**
+     * Add or refresh one request in an agent's local reply window.
+     * @param {object} agent
+     * @param {string} requestId
+     * @param {{ path: string, from: any }} request
+     */
+    openRequest(agent, requestId, request) {
+      let pending = pendingByAgent.get(agent)
+      if (pending === undefined) {
+        pending = new Map()
+        pendingByAgent.set(agent, pending)
+      }
+      pending.set(requestId, request)
+    },
+
+    /**
+     * Apply one reply attempt's structured outcome to its own request id.
+     *
+     * @param {object} agent
+     * @param {unknown} requestId
+     * @param {any} outcome reply result or thrown error
+     * @returns {number | undefined} requests still pending, or undefined when
+     * this agent has no local window (the adapter then has nothing to retire)
+     */
+    finishReply(agent, requestId, outcome) {
+      const pending = pendingByAgent.get(agent)
+      if (pending === undefined) return undefined
+      const id = text(requestId)
+      if (closesLocalRequest(outcome) && id !== undefined) pending.delete(id)
+      if (pending.size === 0) pendingByAgent.delete(agent)
+      return pending.size
+    },
+
+    /**
+     * Close every local request for an agent. Turn end, disposal and unmount
+     * call this independently of any broker outcome.
+     * @param {object} agent
+     */
+    closeAgent(agent) {
+      pendingByAgent.delete(agent)
+    },
+  }
+}