dsh-bailinghub 0.5.0 → 0.7.0

package/lib/session-scope.js

@@ -105,9 +105,10 @@ export class SessionScopeCoordinator {
           // A restored business snapshot is not a current authorization proof.
           // This in-memory fence never rewrites its identities or CAS revision.
           entry.retryRequired = Boolean(entry.record?.authorizations.length)
-        } catch {
+        } catch (error) {
           entry.blocked = true
           entry.loadFailed = true
+          entry.failureCode = error?.code === 'INVALID_SCOPE_SNAPSHOT' ? error.code : 'SCOPE_STORE_UNAVAILABLE'
         }
         entry.loaded = true
       })()
@@ -161,8 +162,12 @@ export class SessionScopeCoordinator {
     try {
       const record = this.validate(await this.store.load(entry.sessionId), entry.sessionId)
       if (JSON.stringify(record) !== JSON.stringify(original)) throw scopeError('SESSION_SCOPE_CONFLICT')
-    } catch {
-      if (entry.record === original && entry.generation === generation) entry.blocked = true
+    } catch (error) {
+      if (entry.record === original && entry.generation === generation) {
+        entry.blocked = true
+        entry.failureCode = ['SESSION_SCOPE_CONFLICT', 'SCOPE_STORE_CONFLICT', 'INVALID_SCOPE_SNAPSHOT'].includes(error?.code)
+          ? error.code : 'SCOPE_STORE_UNAVAILABLE'
+      }
     }
   }
 
@@ -360,6 +365,40 @@ export class SessionScopeCoordinator {
 
   snapshot(sessionId) { return structuredClone(this.entry(sessionId).record) }
 
+  // Read-only host projection: drafts are valid selections, not dispatch grants.
+  // Retain object identity and generation across every await, including A -> B -> A.
+  async verifiedSelection(sessionId) {
+    const entry = await this.load(this.entry(sessionId))
+    const record = entry.record
+    const generation = entry.generation
+    const settleValidation = async () => {
+      // Another read can revalidate the same original group while this reader
+      // waits for local I/O. Join that proof; never mistake its temporary closed
+      // gate for a changed identity, nor ignore its eventual revocation result.
+      while (entry.record === record && entry.generation === generation && this.isValidating(entry)) await entry.validation.promise
+    }
+    const assertCurrent = () => {
+      if (entry.record !== record || entry.generation !== generation) throw scopeError('SESSION_SCOPE_CONFLICT')
+      if (entry.pending || entry.blocked || entry.retryRequired || this.isValidating(entry) || record?.state === 'needs_selection') {
+        throw scopeError(entry.failureCode ?? 'SESSION_SCOPE_UNAVAILABLE')
+      }
+    }
+    await this.get(sessionId)
+    await settleValidation()
+    // An identity failure increments generation; preserve its authoritative code.
+    if (entry.record === record && entry.generation !== generation && (entry.blocked || entry.retryRequired) && !entry.pending) {
+      throw scopeError(entry.failureCode ?? 'SESSION_SCOPE_UNAVAILABLE')
+    }
+    assertCurrent()
+    return { record: structuredClone(record), assertCurrent, check: async () => {
+      await settleValidation()
+      assertCurrent()
+      if (record) await this.checkStored(entry)
+      await settleValidation()
+      assertCurrent()
+    } }
+  }
+
   subjectDisplay(sessionId, connectionKey) {
     return structuredClone(this.entry(sessionId).subjectDisplays?.get(connectionKey) ?? projectSubjectDisplay(null))
   }
@@ -386,8 +425,11 @@ export class SessionScopeCoordinator {
   invalidate(sessionId, error) {
     const entry = this.entry(sessionId)
     entry.generation += 1
-    entry.failureCode = error?.code
-    if (!error || definitiveAuthorizationFailure(error)) entry.blocked = true
+    const definitive = !error || definitiveAuthorizationFailure(error)
+    entry.failureCode = definitive ? error?.code === 'CROSS_HUB_SCOPE_UNSUPPORTED' ? error.code : 'AUTHORIZATION_CHANGED'
+      : error?.name === 'AgentAuthHttpError' && (error.statusCode === 429 || error.statusCode >= 500) ? 'agent_transport_unavailable'
+      : error?.publicCode ?? error?.code ?? 'AUTHORIZATION_UNVERIFIED'
+    if (definitive) entry.blocked = true
     else entry.retryRequired = true
   }
 }

package/lib/session-task-store.js

@@ -0,0 +1,275 @@
+import { createHash, randomUUID } from 'node:crypto'
+import { constants } from 'node:fs'
+import { lstat, mkdir, open, rename, unlink } from 'node:fs/promises'
+import { homedir } from 'node:os'
+import { join, resolve } from 'node:path'
+import { setTimeout as delay } from 'node:timers/promises'
+import { isProxy } from 'node:util/types'
+
+const SCHEMAS = new Set(['bailing.agent-session-task.v1'])
+const RECORD_KEYS = new Set(['schema', 'sessionId', 'revision', 'entries'])
+const MAX_BYTES = 8 * 1024 * 1024
+const LOCK_TIMEOUT_MS = 1_000
+const PRIVATE_KEYS = new Set([
+  'token', 'tokens', 'accesstoken', 'refreshtoken', 'password', 'clientsecret',
+  'authorization', 'credential', 'credentials', 'secret', 'apikey',
+  'args', 'arguments', 'content', 'contents', 'body', 'prompt', 'messages',
+])
+const MAX_DEPTH = 128
+
+function storeError(code = 'TASK_STORE_UNAVAILABLE') {
+  const error = new Error(code === 'TASK_STORE_CONFLICT'
+    ? 'The task binding changed or is being saved. Read it again before retrying.'
+    : 'The task binding store is unavailable. Recovery metadata was not safely confirmed.')
+  error.code = code
+  return error
+}
+
+function safeError(error) {
+  return ['TASK_STORE_CONFLICT', 'TASK_STORE_UNAVAILABLE'].includes(error?.code)
+    ? error : storeError()
+}
+
+function sessionKey(sessionId) {
+  if (typeof sessionId !== 'string' || !sessionId.length || sessionId.length > 4_096) throw storeError()
+  return createHash('sha256').update(sessionId).digest('hex')
+}
+
+// The coordinator validates each original execution binding. This boundary accepts
+// only JSON metadata and refuses credential or business payload fields. Tool names
+// are values, so a tool named "content" or "arguments" remains valid metadata.
+function snapshotJson(value, seen = new Set(), depth = 0) {
+  if (depth > MAX_DEPTH) throw storeError()
+  if (value === null || typeof value === 'string' || typeof value === 'boolean') return value
+  if (typeof value === 'number' && Number.isFinite(value) && !Object.is(value, -0)) return value
+  if (!value || typeof value !== 'object' || seen.has(value) || isProxy(value)) throw storeError()
+  const array = Array.isArray(value)
+  if (!array && ![Object.prototype, null].includes(Object.getPrototypeOf(value))) throw storeError()
+  seen.add(value)
+  try {
+    const entries = Reflect.ownKeys(value).filter((key) => !array || key !== 'length')
+    if (array && (entries.length !== value.length || entries.some((key, index) => key !== String(index)))) throw storeError()
+    const copy = array ? [] : {}
+    for (const key of entries) {
+      const property = Object.getOwnPropertyDescriptor(value, key)
+      if (typeof key !== 'string' || !property.enumerable || !Object.hasOwn(property, 'value') ||
+        PRIVATE_KEYS.has(key.replace(/[_-]/gu, '').toLowerCase()) || ['__proto__', 'constructor', 'prototype'].includes(key)) throw storeError()
+      copy[key] = snapshotJson(property.value, seen, depth + 1)
+    }
+    return copy
+  } finally {
+    seen.delete(value)
+  }
+}
+
+function snapshotRecord(sessionId, record) {
+  const copy = snapshotJson(record)
+  if (!copy || Array.isArray(copy) || !SCHEMAS.has(copy.schema) || copy.sessionId !== sessionId ||
+    !Number.isSafeInteger(copy.revision) || copy.revision < 1 || !Array.isArray(copy.entries) ||
+    Object.keys(copy).some((key) => !RECORD_KEYS.has(key))) throw storeError()
+  if (Buffer.byteLength(JSON.stringify(copy)) > MAX_BYTES) throw storeError()
+  return copy
+}
+
+function nextRecord(sessionId, record, expectedRevision) {
+  sessionKey(sessionId)
+  if (expectedRevision !== null && (!Number.isSafeInteger(expectedRevision) || expectedRevision < 1)) throw storeError()
+  const copy = snapshotRecord(sessionId, record)
+  if (copy.revision !== (expectedRevision ?? 0) + 1) throw storeError()
+  return copy
+}
+
+function assertRevision(current, expectedRevision) {
+  if ((current?.revision ?? null) !== expectedRevision) throw storeError('TASK_STORE_CONFLICT')
+}
+
+function assertOwned(stat, kind) {
+  if (!(kind === 'directory' ? stat.isDirectory() : stat.isFile()) ||
+    (kind === 'file' && stat.nlink !== 1) ||
+    (typeof process.getuid === 'function' && stat.uid !== process.getuid()) ||
+    (process.platform !== 'win32' && (stat.mode & 0o777) !== (kind === 'directory' ? 0o700 : 0o600))) throw storeError()
+}
+
+function sameFile(a, b) {
+  return a.dev === b.dev && a.ino === b.ino
+}
+
+function defaultDirectory() {
+  const configured = process.env.DSH_HOME
+  const base = typeof configured === 'string' && configured.trim() ? configured : join(homedir(), '.dsh')
+  const expanded = base === '~' ? homedir() : /^~[/\\]/u.test(base) ? join(homedir(), base.slice(2)) : base
+  return join(resolve(expanded), 'plugins', 'dsh-bailinghub', 'session-tasks')
+}
+
+async function ensureDirectory(directory, create) {
+  if (create) await mkdir(directory, { recursive: true, mode: 0o700 })
+  let stat
+  try {
+    stat = await lstat(directory)
+  } catch (error) {
+    if (!create && error.code === 'ENOENT') return false
+    throw error
+  }
+  assertOwned(stat, 'directory')
+  return true
+}
+
+async function readRecord(path, sessionId) {
+  let before
+  try {
+    before = await lstat(path)
+  } catch (error) {
+    if (error.code === 'ENOENT') return null
+    throw error
+  }
+  assertOwned(before, 'file')
+  if (before.size > MAX_BYTES) throw storeError()
+  const file = await open(path, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK)
+  try {
+    const opened = await file.stat()
+    assertOwned(opened, 'file')
+    if (!sameFile(before, opened) || opened.size > MAX_BYTES) throw storeError()
+    // Bound the read even if an abnormal writer grows the file after fstat.
+    const bytes = Buffer.alloc(MAX_BYTES + 1)
+    let length = 0
+    while (length < bytes.length) {
+      const result = await file.read(bytes, length, bytes.length - length, length)
+      if (!result.bytesRead) break
+      length += result.bytesRead
+    }
+    if (length > MAX_BYTES) throw storeError()
+    return snapshotRecord(sessionId, JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(bytes.subarray(0, length))))
+  } finally {
+    await file.close()
+  }
+}
+
+async function acquireLock(path) {
+  const deadline = performance.now() + LOCK_TIMEOUT_MS
+  while (true) {
+    let file
+    let stat
+    try {
+      file = await open(path, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, 0o600)
+      stat = await file.stat()
+      await file.chmod(0o600)
+      assertOwned(await file.stat(), 'file')
+      return { file, stat }
+    } catch (error) {
+      if (file) {
+        if (stat) await releaseLock(path, { file, stat })
+        else await file.close().catch(() => {})
+      }
+      if (error.code !== 'EEXIST') throw error
+      try {
+        assertOwned(await lstat(path), 'file')
+      } catch (inspectionError) {
+        if (inspectionError.code === 'ENOENT') continue
+        throw inspectionError
+      }
+      if (performance.now() >= deadline) throw storeError('TASK_STORE_CONFLICT')
+      // Never infer staleness or remove another process's lock.
+      await delay(20)
+    }
+  }
+}
+
+async function releaseLock(path, lock) {
+  try {
+    const current = await lstat(path)
+    if (!sameFile(current, lock.stat) || !current.isFile()) throw storeError()
+    await unlink(path)
+  } finally {
+    await lock.file.close()
+  }
+}
+
+async function syncDirectory(directory) {
+  // Windows does not expose fsync on directory handles through Node.
+  if (process.platform === 'win32') return
+  const handle = await open(directory, constants.O_RDONLY | constants.O_DIRECTORY | constants.O_NOFOLLOW)
+  try {
+    assertOwned(await handle.stat(), 'directory')
+    await handle.sync()
+  } finally {
+    await handle.close()
+  }
+}
+
+/** Durable execution metadata only. No user directory is touched until load/save. */
+export function createFileSessionTaskStore({ directory } = {}) {
+  if (directory !== undefined && (typeof directory !== 'string' || !directory.trim())) throw storeError()
+  const root = directory === undefined ? defaultDirectory() : resolve(directory)
+  return {
+    async load(sessionId) {
+      try {
+        const key = sessionKey(sessionId)
+        if (!await ensureDirectory(root, false)) return null
+        return await readRecord(join(root, `${key}.json`), sessionId)
+      } catch (error) {
+        throw safeError(error)
+      }
+    },
+    async save(sessionId, record, expectedRevision) {
+      let lock
+      let temporaryPath
+      const key = sessionKey(sessionId)
+      const path = join(root, `${key}.json`)
+      const lockPath = join(root, `${key}.lock`)
+      try {
+        const copy = nextRecord(sessionId, record, expectedRevision)
+        await ensureDirectory(root, true)
+        lock = await acquireLock(lockPath)
+        assertRevision(await readRecord(path, sessionId), expectedRevision)
+        temporaryPath = join(root, `.${key}.${randomUUID()}.tmp`)
+        const temporary = await open(temporaryPath, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, 0o600)
+        try {
+          await temporary.chmod(0o600)
+          assertOwned(await temporary.stat(), 'file')
+          await temporary.writeFile(JSON.stringify(copy), 'utf8')
+          await temporary.sync()
+        } finally {
+          await temporary.close()
+        }
+        await rename(temporaryPath, path)
+        temporaryPath = undefined
+        await syncDirectory(root)
+        return snapshotRecord(sessionId, copy)
+      } catch (error) {
+        throw safeError(error)
+      } finally {
+        try {
+          if (temporaryPath) await unlink(temporaryPath).catch((error) => {
+            if (error.code !== 'ENOENT') throw storeError()
+          })
+        } finally {
+          if (lock) {
+            try {
+              await releaseLock(lockPath, lock)
+            } catch {
+              throw storeError()
+            }
+          }
+        }
+      }
+    },
+  }
+}
+
+/** Explicit in-memory adapter: CAS-compatible, but never survives process restart. */
+export function createMemorySessionTaskStore() {
+  const records = new Map()
+  return {
+    async load(sessionId) {
+      sessionKey(sessionId)
+      const record = records.get(sessionId)
+      return record ? snapshotRecord(sessionId, record) : null
+    },
+    async save(sessionId, record, expectedRevision) {
+      const copy = nextRecord(sessionId, record, expectedRevision)
+      assertRevision(records.get(sessionId), expectedRevision)
+      records.set(sessionId, copy)
+      return snapshotRecord(sessionId, copy)
+    },
+  }
+}

package/lib/session-task.js

@@ -0,0 +1,237 @@
+import { memberBinding } from './session-scope.js'
+import { metadataHash, scopeFingerprint } from './invocation-journal.js'
+
+const UUID = /^[a-f0-9]{8}-[a-f0-9]{4}-[1-5][a-f0-9]{3}-[89ab][a-f0-9]{3}-[a-f0-9]{12}$/i
+const HASH = /^[a-f0-9]{64}$/
+const SCHEMA = 'bailing.agent-session-task.v1'
+const TASK_STATES = new Set(['active', 'paused', 'blocked', 'cancelled'])
+const copy = value => structuredClone(value)
+
+export function taskError(code) {
+  return Object.assign(new Error('The original task binding cannot currently permit this operation.'), {
+    publicCode: code,
+    feedback: { schema: 'bailing.agent-feedback.v1', origin: 'dsh', operation: 'task_control', code,
+      category: code.startsWith('TASK_STORE_') ? 'storage_error' : code === 'TASK_UNSUPPORTED' ? 'unsupported' : 'task_control',
+      dispatch: 'not_dispatched', next_action: code.startsWith('TASK_STORE_') ? 'restore_task' : code === 'TASK_UNSUPPORTED' ? 'check_compatibility' : 'inspect_task' },
+  })
+}
+
+/** Host-only immutable association. It cannot create, control, or enlarge a task. */
+export class SessionTaskCoordinator {
+  constructor({ store, scopes, getTransport, conversationId }) {
+    if (store != null && (typeof store.load !== 'function' || typeof store.save !== 'function')) throw new TypeError('A task store with load/save is required')
+    Object.assign(this, { store, scopes, getTransport, conversationId })
+    this.entries = new Map()
+    this.queues = new Map()
+    this.supportedBindings = new Set()
+  }
+
+  entry(id) {
+    if (!this.entries.has(id)) this.entries.set(id, { record: null, pending: null, snapshot: null, failure: null })
+    return this.entries.get(id)
+  }
+
+  serial(id, operation) {
+    const result = (this.queues.get(id) ?? Promise.resolve()).then(operation)
+    this.queues.set(id, result.catch(() => {}))
+    return result
+  }
+
+  validate(raw, id) {
+    if (!raw || raw.schema !== SCHEMA || raw.sessionId !== id || raw.revision !== 1 ||
+      Object.keys(raw).sort().join(',') !== 'entries,revision,schema,sessionId' || !Array.isArray(raw.entries) || raw.entries.length !== 1) throw taskError('TASK_RECORD_INVALID')
+    const value = raw.entries[0]
+    if (!value || Object.keys(value).sort().join(',') !== 'members,scopeHash,taskBinding' || !HASH.test(value.scopeHash ?? '') ||
+      value.taskBinding?.schema_version !== 'bailing.agent-task-binding.v1' || !UUID.test(value.taskBinding.task_id ?? '') ||
+      !HASH.test(value.taskBinding.scope_hash ?? '') || Object.keys(value.taskBinding).sort().join(',') !== 'schema_version,scope_hash,task_id' ||
+      !Array.isArray(value.members) || !value.members.length || value.members.length > 64 ||
+      value.members.some(member => !member || Object.keys(member).sort().join(',') !== 'allowed_tools,client_app_id,client_conversation_id,connectionKey,session_id,workspace' ||
+        !/^conn_[a-f0-9]{32}$/.test(member.connectionKey ?? '') || !UUID.test(member.session_id ?? '') ||
+        typeof member.client_app_id !== 'string' || typeof member.workspace !== 'string' || member.client_conversation_id !== this.conversationId(id) ||
+        !Array.isArray(member.allowed_tools) || member.allowed_tools.some(tool => typeof tool !== 'string' || !/^[A-Za-z_][A-Za-z0-9_]{0,63}$/.test(tool)))) throw taskError('TASK_RECORD_INVALID')
+    return copy(raw)
+  }
+
+  async read(id) {
+    const entry = this.entry(id)
+    if (!this.store) return null
+    let raw
+    try { raw = await this.store.load(id) } catch (error) { throw taskError(error?.code === 'TASK_STORE_CONFLICT' ? error.code : 'TASK_STORE_UNAVAILABLE') }
+    const record = raw === null ? null : this.validate(raw, id)
+    if (entry.record && metadataHash(entry.record) !== metadataHash(record)) throw taskError('TASK_BINDING_CONFLICT')
+    if (record && entry.pending && metadataHash(record) !== metadataHash(entry.pending)) throw taskError('TASK_BINDING_CONFLICT')
+    entry.record = record
+    return record
+  }
+
+  async verify(id, taskId, selection) {
+    if (!selection) {
+      const scopeView = await this.scopes.get(id)
+      if (!taskId && ['chat', 'unselected'].includes(scopeView.mode)) return { supported: undefined, mode: 'optional', scope: this.scopes.snapshot(id) }
+      await this.scopes.assertUsable(id)
+    } else selection.assertCurrent()
+    const scope = selection?.record ?? this.scopes.snapshot(id)
+    const transport = await this.getTransport()
+    if (typeof transport.getTaskControlCapabilities !== 'function') {
+      if (taskId) throw taskError('TASK_UNSUPPORTED')
+      return { supported: false, mode: 'optional', scope }
+    }
+    const members = []
+    let snapshot
+    let required = false
+    let supported = true
+    for (const member of scope.authorizations) {
+      selection?.assertCurrent()
+      const expectedBinding = { ...memberBinding(scope, member), sessionId: member.sessionId }
+      const options = { connectionKey: member.connectionKey, workspace: member.workspace, expectedBinding,
+        clientConversationId: this.conversationId(id) }
+      // Only protocol support is stable for this exact original binding. The
+      // unbound/optional path must still read current enrollment on every call.
+      const protocolKey = metadataHash({ connectionKey: member.connectionKey, expectedBinding })
+      const supportedProtocol = Boolean(taskId && this.supportedBindings.has(protocolKey))
+      let caps
+      try { if (!supportedProtocol) caps = await transport.getTaskControlCapabilities(options) }
+      catch (error) {
+        if (!taskId && error.publicCode === 'TASK_UNSUPPORTED') caps = { supported: false, mode: 'optional' }
+        else throw error
+      }
+      if (!supportedProtocol) {
+        if (!caps || typeof caps.supported !== 'boolean' || !['optional', 'required'].includes(caps.mode)) throw taskError('TASK_UNAVAILABLE')
+        required ||= caps.mode === 'required'
+        supported &&= caps.supported
+      }
+      if (!taskId) continue
+      if ((!supportedProtocol && (!caps.supported || caps.inspect_invocation !== true)) || typeof transport.getTask !== 'function' ||
+        typeof transport.inspectInvocation !== 'function') throw taskError('TASK_UNSUPPORTED')
+      this.supportedBindings.add(protocolKey)
+      const task = await transport.getTask(taskId, options)
+      const own = task?.member
+      if (task?.schema_version !== 'bailing.agent-task.v1' || task.task_id !== taskId || !HASH.test(task.scope_hash ?? '') ||
+        task.member_count !== scope.authorizations.length || !TASK_STATES.has(task.state) || !Number.isSafeInteger(task.revision) ||
+        task.metering !== 'write_invocation' || task.snapshot_is_dispatch_permission !== false ||
+        !own || own.session_id !== member.sessionId || own.client_app_id !== expectedBinding.clientAppId ||
+        own.workspace !== member.workspace || own.client_conversation_id !== options.clientConversationId ||
+        !Array.isArray(own.allowed_tools) || new Set(own.allowed_tools).size !== own.allowed_tools.length) throw taskError('TASK_MEMBER_MISMATCH')
+      if (snapshot && (task.scope_hash !== snapshot.scope_hash || metadataHash(task.policy) !== metadataHash(snapshot.policy))) throw taskError('TASK_BINDING_CONFLICT')
+      members.push({ connectionKey: member.connectionKey, session_id: own.session_id, client_app_id: own.client_app_id,
+        workspace: own.workspace, client_conversation_id: own.client_conversation_id, allowed_tools: [...own.allowed_tools].sort() })
+      if (!snapshot || task.ledger_sequence >= snapshot.ledger_sequence) snapshot = task
+    }
+    if (selection) await selection.check()
+    else await this.scopes.assertUsable(id)
+    return { supported, mode: taskId ? undefined : required ? 'required' : 'optional', scope, snapshot, members: members.sort((a, b) => a.connectionKey.localeCompare(b.connectionKey)) }
+  }
+
+  coordinates(id) {
+    return this.serial(id, async () => {
+      const selection = await this.scopes.verifiedSelection(id)
+      const scope = selection.record
+      if (!scope?.authorizations.length) return { state: 'inactive', availability: 'not_checked',
+        reason: scope ? 'SESSION_SCOPE_CHAT_ONLY' : 'SESSION_SCOPE_UNSELECTED' }
+      if (new Set(scope.authorizations.map(member => member.sessionId.toLowerCase())).size !== scope.authorizations.length) throw taskError('TASK_MEMBER_MISMATCH')
+      const entry = this.entry(id)
+      if (entry.failure?.startsWith('TASK_STORE_')) throw taskError(entry.failure)
+      const record = await this.read(id)
+      if (entry.pending || (!record && entry.intendedId)) throw taskError(entry.failure ?? 'TASK_REQUIRED')
+      const verified = await this.verify(id, record?.entries[0].taskBinding.task_id, selection)
+      if (!verified.supported) throw taskError('TASK_UNSUPPORTED')
+      if (record) {
+        const expected = { scopeHash: scopeFingerprint(scope), members: verified.members,
+          taskBinding: { schema_version: 'bailing.agent-task-binding.v1', task_id: verified.snapshot.task_id, scope_hash: verified.snapshot.scope_hash } }
+        if (metadataHash(record.entries[0]) !== metadataHash(expected)) throw taskError('TASK_BINDING_CONFLICT')
+      }
+      // Catch a concurrent durable binding change; never write or repair sidecars here.
+      if (metadataHash(await this.read(id)) !== metadataHash(record)) throw taskError('TASK_BINDING_CONFLICT')
+      await selection.check()
+      return { state: 'ready', availability: 'supported', sessionId: id,
+        clientConversationId: this.conversationId(id), scopeRevision: scope.revision, scopeLocked: scope.locked,
+        members: scope.authorizations.map(member => ({ connectionKey: member.connectionKey,
+          agentSessionId: member.sessionId, clientAppId: memberBinding(scope, member).clientAppId, workspace: member.workspace })) }
+    })
+  }
+
+  async save(id, record) {
+    try {
+      const saved = await this.store.save(id, copy(record), null)
+      if (metadataHash(saved) !== metadataHash(record)) throw taskError('TASK_STORE_UNAVAILABLE')
+    } catch (error) { throw taskError(error?.code === 'TASK_STORE_CONFLICT' ? error.code : 'TASK_STORE_UNAVAILABLE') }
+    this.entry(id).record = copy(record)
+    this.entry(id).pending = null
+  }
+
+  set(id, request) {
+    return this.serial(id, async () => {
+      const entry = this.entry(id)
+      try {
+        if (!request || Object.keys(request).join(',') !== 'taskId' || !UUID.test(request.taskId ?? '')) throw taskError('TASK_RECORD_INVALID')
+        if (entry.intendedId && entry.intendedId !== request.taskId) throw taskError('TASK_BINDING_CONFLICT')
+        entry.intendedId = request.taskId
+        if (!this.store) throw taskError('TASK_STORE_UNAVAILABLE')
+        if (entry.failure?.startsWith('TASK_STORE_')) throw taskError(entry.failure)
+        await this.scopes.begin(id)
+        const current = await this.read(id)
+        if ((current ?? entry.pending)?.entries[0].taskBinding.task_id !== undefined &&
+          (current ?? entry.pending).entries[0].taskBinding.task_id !== request.taskId) throw taskError('TASK_BINDING_CONFLICT')
+        const verified = await this.verify(id, request.taskId)
+        const record = { schema: SCHEMA, sessionId: id, revision: 1, entries: [{ scopeHash: scopeFingerprint(verified.scope),
+          taskBinding: { schema_version: 'bailing.agent-task-binding.v1', task_id: request.taskId, scope_hash: verified.snapshot.scope_hash }, members: verified.members }] }
+        if (current && metadataHash(current) !== metadataHash(record)) throw taskError('TASK_BINDING_CONFLICT')
+        if (!current) { entry.pending = record; await this.save(id, record) }
+        entry.snapshot = verified.snapshot
+        entry.supported = true
+        entry.failure = null
+        return this.view(id)
+      } catch (error) { this.fail(id, error); throw error }
+    })
+  }
+
+  fail(id, error) {
+    const entry = this.entry(id)
+    // Persistence failure remains primary until explicit restore succeeds.
+    if (!entry.failure?.startsWith('TASK_STORE_')) entry.failure = error.publicCode ?? error.code ?? 'TASK_UNAVAILABLE'
+  }
+
+  refresh(id, restore = false) {
+    return this.serial(id, async () => {
+      const entry = this.entry(id)
+      try {
+        if (!restore && entry.failure?.startsWith('TASK_STORE_')) return this.view(id)
+        let record = await this.read(id)
+        let verified
+        if (restore && entry.pending && !record) { verified = await this.verify(id, entry.pending.entries[0].taskBinding.task_id); await this.save(id, entry.pending); record = entry.record }
+        if (!record && entry.intendedId) throw taskError(entry.failure ?? 'TASK_REQUIRED')
+        verified ??= await this.verify(id, record?.entries[0].taskBinding.task_id)
+        entry.supported = verified.supported
+        entry.mode = verified.mode
+        if (record) {
+          const expected = { scopeHash: scopeFingerprint(verified.scope), members: verified.members,
+            taskBinding: { schema_version: 'bailing.agent-task-binding.v1', task_id: verified.snapshot.task_id, scope_hash: verified.snapshot.scope_hash } }
+          if (metadataHash(record.entries[0]) !== metadataHash(expected)) throw taskError('TASK_BINDING_CONFLICT')
+          entry.snapshot = verified.snapshot
+          entry.pending = null
+        }
+        entry.failure = !record && verified.mode === 'required' ? 'TASK_REQUIRED' : null
+      } catch (error) { this.fail(id, error) }
+      return this.view(id)
+    })
+  }
+
+  view(id) {
+    const entry = this.entry(id)
+    const failure = entry.failure
+    const snapshot = entry.snapshot
+    return { state: failure ? failure.startsWith('TASK_STORE_') ? 'storage_error' : 'blocked' : snapshot?.state ?? 'inactive',
+      availability: failure === 'TASK_UNSUPPORTED' ? 'unsupported' : failure && ['TASK_UNAVAILABLE', 'agent_transport_unavailable', 'agent_request_timeout'].includes(failure) ? 'unavailable' : entry.supported === true ? 'supported' : entry.supported === false ? 'unsupported' : 'unavailable',
+      ...(failure ? { reason: failure } : {}), task_binding: copy(entry.record?.entries[0].taskBinding ?? null),
+      ...(snapshot ? { task_state: snapshot.state, revision: snapshot.revision, ledger_sequence: snapshot.ledger_sequence,
+        policy: copy(snapshot.policy), counters: copy(snapshot.counters), metering: 'write_invocation' } : {}),
+      snapshot_is_dispatch_permission: false, object_metering: 'unsupported', unsavedRecords: entry.pending ? 1 : 0 }
+  }
+
+  async binding(id, { dispatch = false } = {}) {
+    const view = await this.refresh(id)
+    if (view.reason) throw taskError(view.reason)
+    if (dispatch && view.task_binding && view.task_state !== 'active') throw taskError({ paused: 'TASK_PAUSED', cancelled: 'TASK_CANCELLED', blocked: 'TASK_SCOPE_BLOCKED' }[view.task_state])
+    return view.task_binding
+  }
+}