ethagent 1.1.2 → 2.0.1

package/src/identity/hub/operatorWallets.ts

@@ -0,0 +1,131 @@
+import { getAddress, isAddress, type Address } from 'viem'
+import type { WalletContinuityRestoreAccessKey } from '../continuity/envelope.js'
+
+export type ApprovedOperatorWalletRecord = {
+  address: Address
+  challenge?: string
+  verifiedAt?: string
+  restoreAccessKey?: WalletContinuityRestoreAccessKey
+}
+
+export type ApprovedOperatorWalletInput = string | ApprovedOperatorWalletRecord
+
+const ZERO_ADDRESS = '0x0000000000000000000000000000000000000000'
+
+function isZeroAddress(addr: string): boolean {
+  return addr.toLowerCase() === ZERO_ADDRESS
+}
+
+export function normalizeApprovedOperatorWallets(input: unknown): ApprovedOperatorWalletRecord[] {
+  if (!Array.isArray(input)) return []
+  const out: ApprovedOperatorWalletRecord[] = []
+  const seen = new Set<string>()
+  for (const item of input) {
+    const parsed = parseApprovedOperatorWalletRecord(item)
+    if (!parsed) continue
+    const key = parsed.address.toLowerCase()
+    if (seen.has(key)) continue
+    seen.add(key)
+    out.push(parsed)
+  }
+  return out
+}
+
+export function mergeApprovedOperatorWallets(
+  existing: unknown,
+  additions: unknown,
+  options?: { walletAddress?: string },
+): ApprovedOperatorWalletRecord[] {
+  let out = normalizeApprovedOperatorWallets(existing)
+  for (const record of normalizeApprovedOperatorWallets(additions)) {
+    out = upsertApprovedOperatorWallet(out, record, options)
+  }
+  return out
+}
+
+export function upsertApprovedOperatorWallet(
+  existing: unknown,
+  record: ApprovedOperatorWalletInput,
+  options?: { walletAddress?: string },
+): ApprovedOperatorWalletRecord[] {
+  const parsed = parseApprovedOperatorWalletRecord(record)
+  if (!parsed) throw new Error('Approved operator wallet must include a valid address')
+  if (options?.walletAddress && options.walletAddress.trim()) {
+    if (!isAddress(options.walletAddress, { strict: false })) throw new Error('Owner address is invalid')
+    if (parsed.address.toLowerCase() === options.walletAddress.toLowerCase()) {
+      throw new Error('Operator wallet must be different from the owner wallet')
+    }
+  }
+  const records = normalizeApprovedOperatorWallets(existing)
+  const key = parsed.address.toLowerCase()
+  const index = records.findIndex(item => item.address.toLowerCase() === key)
+  if (index === -1) return [...records, parsed]
+  const next = records.slice()
+  next[index] = { ...records[index], ...parsed, address: parsed.address }
+  return next
+}
+
+export function removeApprovedOperatorWallet(
+  existing: unknown,
+  address: string,
+  activeOperatorAddress?: string,
+): ApprovedOperatorWalletRecord[] {
+  if (!isAddress(address, { strict: false })) throw new Error('Operator wallet address is invalid')
+  const target = getAddress(address)
+  if (activeOperatorAddress && activeOperatorAddress.toLowerCase() === target.toLowerCase()) {
+    throw new Error('Set another active operator wallet before removing this wallet')
+  }
+  return normalizeApprovedOperatorWallets(existing).filter(item => item.address.toLowerCase() !== target.toLowerCase())
+}
+
+export function assertActiveOperatorIsApproved(
+  records: unknown,
+  activeOperatorAddress: string | undefined,
+): Address | undefined {
+  if (!activeOperatorAddress || !activeOperatorAddress.trim()) return undefined
+  if (!isAddress(activeOperatorAddress, { strict: false })) throw new Error('Active operator wallet address is invalid')
+  const active = getAddress(activeOperatorAddress)
+  const approved = normalizeApprovedOperatorWallets(records)
+  if (!approved.some(item => item.address.toLowerCase() === active.toLowerCase())) {
+    throw new Error('Active operator wallet must be one of the approved operator wallets')
+  }
+  return active
+}
+
+function parseApprovedOperatorWalletRecord(input: unknown): ApprovedOperatorWalletRecord | null {
+  if (typeof input === 'string') {
+    const trimmed = input.trim()
+    if (!isAddress(trimmed, { strict: false })) return null
+    if (isZeroAddress(trimmed)) return null
+    return { address: getAddress(trimmed) }
+  }
+  if (!input || typeof input !== 'object' || Array.isArray(input)) return null
+  const obj = input as Record<string, unknown>
+  const rawAddress = obj.address
+  if (typeof rawAddress !== 'string' || !isAddress(rawAddress, { strict: false })) return null
+  if (isZeroAddress(rawAddress)) return null
+  const challenge = typeof obj.challenge === 'string' && obj.challenge.trim() ? obj.challenge : undefined
+  const verifiedAt = typeof obj.verifiedAt === 'string' && obj.verifiedAt.trim() ? obj.verifiedAt : undefined
+  return {
+    address: getAddress(rawAddress),
+    ...(challenge ? { challenge } : {}),
+    ...(verifiedAt ? { verifiedAt } : {}),
+    ...(parseRestoreAccessKey(obj.restoreAccessKey) ? { restoreAccessKey: parseRestoreAccessKey(obj.restoreAccessKey)! } : {}),
+  }
+}
+
+function parseRestoreAccessKey(input: unknown): WalletContinuityRestoreAccessKey | undefined {
+  if (!input || typeof input !== 'object' || Array.isArray(input)) return undefined
+  const obj = input as Partial<WalletContinuityRestoreAccessKey>
+  if (typeof obj.address !== 'string' || !isAddress(obj.address, { strict: false })) return undefined
+  if (typeof obj.challenge !== 'string' || !obj.challenge.trim()) return undefined
+  if (typeof obj.salt !== 'string' || !obj.salt.trim()) return undefined
+  if (typeof obj.kemPublicKey !== 'string' || !obj.kemPublicKey.trim()) return undefined
+  return {
+    address: getAddress(obj.address),
+    challenge: obj.challenge,
+    salt: obj.salt,
+    kemPublicKey: obj.kemPublicKey,
+    ...(typeof obj.createdAt === 'string' && obj.createdAt.trim() ? { createdAt: obj.createdAt } : {}),
+  }
+}

package/src/identity/hub/reconciliation/agentReconciliation/hook.ts

@@ -0,0 +1,46 @@
+import { useEffect, useState } from 'react'
+import type { EthagentConfig } from '../../../../storage/config.js'
+import { emptyReconciliation, runReconciliation } from './run.js'
+import type { AgentReconciliation } from './types.js'
+
+export function useAgentReconciliation(
+  config: EthagentConfig | null,
+): { reconciliation: AgentReconciliation; refresh: () => void } {
+  const [reconciliation, setReconciliation] = useState<AgentReconciliation>(() => ({
+    token: 'no-agent',
+    custody: 'unknown',
+    agentUri: 'unknown',
+    ensRecords: 'unset',
+    vault: 'unset',
+    workingTree: 'unknown',
+    rpc: 'reachable',
+    driftCount: 0,
+    lastCheckedAt: new Date(0).toISOString(),
+  }))
+  const [refreshKey, setRefreshKey] = useState(0)
+
+  useEffect(() => {
+    if (!config?.identity || !config.identity.agentId || !config.identity.chainId || !config.identity.identityRegistryAddress) {
+      setReconciliation(emptyReconciliation())
+      return
+    }
+    const identity = config.identity
+    let cancelled = false
+    ;(async () => {
+      const result = await runReconciliation(identity, config)
+      if (cancelled) return
+      setReconciliation(result)
+    })()
+    return () => { cancelled = true }
+  }, [
+    config?.identity?.agentId,
+    config?.identity?.chainId,
+    config?.identity?.address,
+    config?.identity?.backup?.agentUri,
+    config?.identity?.state,
+    config?.erc8004?.operatorVaults,
+    refreshKey,
+  ])
+
+  return { reconciliation, refresh: () => setRefreshKey(k => k + 1) }
+}

package/src/identity/hub/reconciliation/agentReconciliation/ownership.ts

@@ -0,0 +1,129 @@
+import { getAddress, type Address } from 'viem'
+import {
+  createErc8004PublicClient,
+  validateErc8004TokenOwner,
+  type Erc8004RegistryConfig,
+} from '../../../registry/erc8004.js'
+import type { EthagentIdentity } from '../../../../storage/config.js'
+
+export type OwnershipRole = 'token-holder' | 'vault-level-owner'
+
+export type OwnershipGuardResult =
+  | { ok: true; effectiveOwner: Address; heldByVault: boolean }
+  | { ok: false; reason: 'not-owned' | 'lookup-failed'; detail: string; onChainOwner?: Address }
+
+type OwnershipCacheEntry = {
+  expiresAt: number
+  result: OwnershipGuardResult
+}
+
+const OWNERSHIP_CACHE_TTL_MS = 30_000
+const ownershipCache = new Map<string, OwnershipCacheEntry>()
+
+function ownershipCacheKey(args: {
+  registry: Erc8004RegistryConfig
+  agentId: bigint
+  expectedSigner: Address
+  requiredRole: OwnershipRole
+}): string {
+  return [
+    args.registry.chainId,
+    args.registry.identityRegistryAddress.toLowerCase(),
+    args.agentId.toString(),
+    args.expectedSigner.toLowerCase(),
+    args.requiredRole,
+  ].join('|')
+}
+
+export function invalidateOwnershipCache(): void {
+  ownershipCache.clear()
+}
+
+export async function preflightTokenOwnership(args: {
+  identity: EthagentIdentity
+  registry: Erc8004RegistryConfig
+  operatorVaults?: Readonly<Record<string, string>>
+  requiredRole: OwnershipRole
+  expectedSigner?: Address
+}): Promise<OwnershipGuardResult> {
+  if (!args.identity.agentId) {
+    return { ok: false, reason: 'lookup-failed', detail: 'identity has no agentId' }
+  }
+  const expectedSigner = getAddress(args.expectedSigner ?? args.identity.ownerAddress ?? args.identity.address)
+  const agentId = BigInt(args.identity.agentId)
+  const key = ownershipCacheKey({ registry: args.registry, agentId, expectedSigner, requiredRole: args.requiredRole })
+  const cached = ownershipCache.get(key)
+  if (cached && cached.expiresAt > Date.now()) return cached.result
+  const result = await runOwnershipPreflight({ ...args, agentId, expectedSigner })
+  ownershipCache.set(key, { result, expiresAt: Date.now() + OWNERSHIP_CACHE_TTL_MS })
+  return result
+}
+
+async function runOwnershipPreflight(args: {
+  registry: Erc8004RegistryConfig
+  operatorVaults?: Readonly<Record<string, string>>
+  requiredRole: OwnershipRole
+  agentId: bigint
+  expectedSigner: Address
+}): Promise<OwnershipGuardResult> {
+  const validation = await validateErc8004TokenOwner({
+    ...args.registry,
+    agentId: args.agentId,
+    expectedOwner: args.expectedSigner,
+    operatorVaults: args.operatorVaults,
+  })
+  if (validation.ok) {
+    const directOwner = await readDirectOwner({
+      registry: args.registry,
+      agentId: args.agentId,
+    })
+    if (directOwner.kind === 'error') {
+      return { ok: false, reason: 'lookup-failed', detail: directOwner.detail }
+    }
+    const heldByVault = directOwner.owner.toLowerCase() !== args.expectedSigner.toLowerCase()
+    if (args.requiredRole === 'token-holder' && heldByVault) {
+      return {
+        ok: false,
+        reason: 'not-owned',
+        detail: `Token is held by the operator delegation vault (${directOwner.owner}). Withdraw it first.`,
+        onChainOwner: directOwner.owner,
+      }
+    }
+    return { ok: true, effectiveOwner: validation.ownerAddress, heldByVault }
+  }
+  if (validation.reason === 'token-owner-lookup-failed') {
+    return { ok: false, reason: 'lookup-failed', detail: validation.detail }
+  }
+  return {
+    ok: false,
+    reason: 'not-owned',
+    detail: validation.detail,
+    onChainOwner: validation.ownerAddress,
+  }
+}
+
+async function readDirectOwner(args: {
+  registry: Erc8004RegistryConfig
+  agentId: bigint
+}): Promise<{ kind: 'ok'; owner: Address } | { kind: 'error'; detail: string }> {
+  try {
+    const client = createErc8004PublicClient(args.registry)
+    const owner = await client.readContract({
+      address: args.registry.identityRegistryAddress,
+      abi: [
+        {
+          type: 'function',
+          name: 'ownerOf',
+          stateMutability: 'view',
+          inputs: [{ name: 'tokenId', type: 'uint256' }],
+          outputs: [{ name: '', type: 'address' }],
+        },
+      ] as const,
+      functionName: 'ownerOf',
+      args: [args.agentId],
+    })
+    return { kind: 'ok', owner: getAddress(owner as Address) }
+  } catch (err: unknown) {
+    return { kind: 'error', detail: err instanceof Error ? err.message : String(err) }
+  }
+}

package/src/identity/hub/reconciliation/agentReconciliation/run.ts

@@ -0,0 +1,302 @@
+import { getAddress, type Address, type PublicClient } from 'viem'
+import {
+  createErc8004PublicClient,
+  erc8004ConfigForSupportedChain,
+  validateErc8004TokenOwner,
+  type Erc8004RegistryConfig,
+} from '../../../registry/erc8004.js'
+import { isAgentInVault, resolveConfiguredOperatorVaultAddress } from '../../../registry/operatorVault.js'
+import type { EthagentConfig, EthagentIdentity } from '../../../../storage/config.js'
+import { readOperatorVaultAddressField } from '../../../identityCompat.js'
+import { reconcileWalletSetup, type RecordsFixPlan } from '../walletSetup.js'
+import { readCustodyMode } from '../../model/custody.js'
+import { continuityWorkingTreeStatus, type ContinuityWorkingTreeStatus } from '../../../continuity/storage.js'
+import type { AgentReconciliation } from './types.js'
+
+export function emptyReconciliation(): AgentReconciliation {
+  return {
+    token: 'no-agent',
+    custody: 'unknown',
+    agentUri: 'unknown',
+    ensRecords: 'unset',
+    vault: 'unset',
+    workingTree: 'unknown',
+    rpc: 'reachable',
+    driftCount: 0,
+    lastCheckedAt: new Date().toISOString(),
+  }
+}
+
+export async function runReconciliation(
+  identity: EthagentIdentity,
+  config: EthagentConfig,
+): Promise<AgentReconciliation> {
+  const fallback = (() => {
+    try { return erc8004ConfigForSupportedChain(identity.chainId!) }
+    catch { return null }
+  })()
+  const rpcUrl = identity.rpcUrl ?? config.erc8004?.rpcUrl ?? fallback?.rpcUrl ?? ''
+  const registry: Erc8004RegistryConfig = {
+    chainId: identity.chainId!,
+    rpcUrl,
+    identityRegistryAddress: identity.identityRegistryAddress! as `0x${string}`,
+  }
+  const expectedOwner = getAddress(identity.ownerAddress ?? identity.address) as Address
+  const agentId = BigInt(identity.agentId!)
+  const operatorVaults = config.erc8004?.operatorVaults
+  const vaultAddress = resolveReconciliationVaultAddress(identity, operatorVaults)
+
+  if (!rpcUrl) {
+    return {
+      token: 'unknown',
+      tokenDetail: `no rpcUrl configured for chain ${identity.chainId}`,
+      custody: 'unknown',
+      agentUri: 'unknown',
+      ensRecords: 'unknown',
+      vault: vaultAddress ? 'unknown' : 'unset',
+      workingTree: 'unknown',
+      rpc: 'failing',
+      driftCount: 0,
+      lastCheckedAt: new Date().toISOString(),
+    }
+  }
+
+  const client = createErc8004PublicClient(registry)
+
+  const [
+    tokenResult,
+    custodyResult,
+    agentUriResult,
+    ensReconcileResult,
+    vaultResult,
+    workingTreeResult,
+  ] = await Promise.allSettled([
+    probeToken({ registry, agentId, expectedOwner, operatorVaults }),
+    probeCustody({ client, registry, agentId, expectedOwner, vaultAddress, identity }),
+    probeAgentUri({ client, registry, agentId, identity }),
+    probeEnsRecords({ identity, registry, client }),
+    probeVault({ client, vaultAddress }),
+    probeWorkingTree(identity),
+  ])
+
+  const token = unwrap(tokenResult, fallbackToken)
+  const custody = unwrap(custodyResult, () => ({ kind: 'unknown' as const }))
+  const agentUri = unwrap(agentUriResult, () => ({ kind: 'unknown' as const }))
+  const ensRecords = unwrap(ensReconcileResult, () => ({ kind: 'unknown' as const }))
+  const vault = unwrap(vaultResult, () => ({ kind: vaultAddress ? 'unknown' as const : 'unset' as const }))
+  const workingTree = unwrap(workingTreeResult, () => ({ kind: 'unknown' as const }))
+
+  const allFailed = [tokenResult, custodyResult, agentUriResult, ensReconcileResult, vaultResult]
+    .every(r => r.status === 'rejected')
+  const rpc: 'reachable' | 'failing' = allFailed ? 'failing' : 'reachable'
+
+  const recon: AgentReconciliation = {
+    token: token.kind,
+    ...(token.kind === 'unlinked' && token.detail ? { tokenDetail: token.detail } : {}),
+    ...(token.kind === 'unlinked' ? { tokenAgentId: token.agentId } : {}),
+    ...(token.kind === 'linked' ? { onChainOwner: token.onChainOwner } : {}),
+    ...(token.kind === 'unlinked' && token.onChainOwner ? { onChainOwner: token.onChainOwner } : {}),
+    ...(token.kind === 'unknown' && token.detail ? { tokenDetail: token.detail } : {}),
+    custody: custody.kind,
+    agentUri: agentUri.kind,
+    ensRecords: ensRecords.kind,
+    ...(ensRecords.kind === 'drift' || ensRecords.kind === 'aligned' ? { ensRecordsPlan: ensRecords.plan } : {}),
+    vault: vault.kind,
+    workingTree: workingTree.kind,
+    rpc,
+    driftCount: 0,
+    lastCheckedAt: new Date().toISOString(),
+  }
+  recon.driftCount = computeDriftCount(recon)
+  return recon
+}
+
+function resolveReconciliationVaultAddress(
+  identity: EthagentIdentity,
+  operatorVaults?: Readonly<Record<string, string>>,
+): Address | undefined {
+  const identityVault = readOperatorVaultAddressField(identity.state as Record<string, unknown> | undefined)
+  if (identityVault) return getAddress(identityVault)
+  if (readCustodyMode(identity.state as Record<string, unknown> | undefined) !== 'advanced') return undefined
+  if (!identity.chainId) return undefined
+  return resolveConfiguredOperatorVaultAddress(operatorVaults, identity.chainId)
+}
+
+type TokenProbe =
+  | { kind: 'linked'; onChainOwner: string }
+  | { kind: 'unlinked'; detail: string; agentId: string; onChainOwner?: string }
+  | { kind: 'unknown'; detail: string }
+  | { kind: 'no-agent' }
+
+async function probeToken(args: {
+  registry: Erc8004RegistryConfig
+  agentId: bigint
+  expectedOwner: Address
+  operatorVaults?: Readonly<Record<string, string>>
+}): Promise<TokenProbe> {
+  const result = await validateErc8004TokenOwner({
+    ...args.registry,
+    agentId: args.agentId,
+    expectedOwner: args.expectedOwner,
+    operatorVaults: args.operatorVaults,
+  })
+  if (result.ok) return { kind: 'linked', onChainOwner: result.ownerAddress }
+  if (result.reason === 'token-owner-lookup-failed') return { kind: 'unknown', detail: result.detail }
+  return {
+    kind: 'unlinked',
+    detail: result.detail,
+    agentId: args.agentId.toString(),
+    ...(result.ownerAddress ? { onChainOwner: result.ownerAddress } : {}),
+  }
+}
+
+function fallbackToken(): TokenProbe {
+  return { kind: 'unknown', detail: 'token ownership probe failed' }
+}
+
+type CustodyProbe = { kind: 'simple' | 'advanced' | 'withdrawn' | 'mid-flow-uri-pending' | 'unknown' }
+
+async function probeCustody(args: {
+  client: PublicClient
+  registry: Erc8004RegistryConfig
+  agentId: bigint
+  expectedOwner: Address
+  vaultAddress?: Address
+  identity: EthagentIdentity
+}): Promise<CustodyProbe> {
+  if (!args.vaultAddress) return { kind: 'simple' }
+  try {
+    const status = await isAgentInVault({
+      client: args.client,
+      vaultAddress: args.vaultAddress,
+      registry: args.registry.identityRegistryAddress,
+      agentId: args.agentId,
+    })
+    if (!status.inVault) return { kind: 'withdrawn' }
+    const localUri = args.identity.agentUri ?? args.identity.backup?.agentUri
+    if (localUri) {
+      try {
+        const onChain = await args.client.readContract({
+          address: args.registry.identityRegistryAddress,
+          abi: ERC8004_AGENT_URI_ABI,
+          functionName: 'agentURI',
+          args: [args.agentId],
+        }) as string
+        if (onChain && onChain !== localUri) {
+          return { kind: 'mid-flow-uri-pending' }
+        }
+      } catch {
+      }
+    }
+    if (status.ownerAddress?.toLowerCase() === args.expectedOwner.toLowerCase()) {
+      return { kind: 'advanced' }
+    }
+    return { kind: 'advanced' }
+  } catch {
+    return { kind: 'unknown' }
+  }
+}
+
+type AgentUriProbe = { kind: 'in-sync' | 'chain-newer' | 'local-newer' | 'unknown' }
+
+const ERC8004_AGENT_URI_ABI = [
+  {
+    type: 'function',
+    name: 'agentURI',
+    stateMutability: 'view',
+    inputs: [{ name: 'agentId', type: 'uint256' }],
+    outputs: [{ name: '', type: 'string' }],
+  },
+] as const
+
+async function probeAgentUri(args: {
+  client: PublicClient
+  registry: Erc8004RegistryConfig
+  agentId: bigint
+  identity: EthagentIdentity
+}): Promise<AgentUriProbe> {
+  const localUri = args.identity.agentUri ?? args.identity.backup?.agentUri
+  if (!localUri) return { kind: 'unknown' }
+  try {
+    const onChain = await args.client.readContract({
+      address: args.registry.identityRegistryAddress,
+      abi: ERC8004_AGENT_URI_ABI,
+      functionName: 'agentURI',
+      args: [args.agentId],
+    }) as string
+    if (onChain === localUri) return { kind: 'in-sync' }
+    if (!onChain) return { kind: 'local-newer' }
+    return { kind: 'local-newer' }
+  } catch {
+    return { kind: 'unknown' }
+  }
+}
+
+type EnsRecordsProbe =
+  | { kind: 'aligned'; plan: RecordsFixPlan }
+  | { kind: 'drift'; plan: RecordsFixPlan }
+  | { kind: 'unset' }
+  | { kind: 'unknown' }
+
+async function probeEnsRecords(args: {
+  identity: EthagentIdentity
+  registry: Erc8004RegistryConfig
+  client: PublicClient
+}): Promise<EnsRecordsProbe> {
+  const baseState = (args.identity.state ?? {}) as Record<string, unknown>
+  const ensName = typeof baseState.ensName === 'string' ? baseState.ensName.trim() : ''
+  const custody = readCustodyMode(baseState)
+  if (!ensName || custody !== 'advanced') return { kind: 'unset' }
+  try {
+    const plan = await reconcileWalletSetup({ identity: args.identity, registry: args.registry })
+    if (plan.items.length === 0) return { kind: 'aligned', plan }
+    const actionable = plan.items.some(item => item.kind === 'missing-approval' || item.kind === 'stale-approval')
+    return actionable ? { kind: 'drift', plan } : { kind: 'aligned', plan }
+  } catch {
+    return { kind: 'unknown' }
+  }
+}
+
+type VaultProbe = { kind: 'confirmed' | 'missing' | 'unset' | 'unknown' }
+
+async function probeVault(args: {
+  client: PublicClient
+  vaultAddress?: Address
+}): Promise<VaultProbe> {
+  if (!args.vaultAddress) return { kind: 'unset' }
+  try {
+    const code = await args.client.getBytecode({ address: args.vaultAddress })
+    if (!code || code === '0x') return { kind: 'missing' }
+    return { kind: 'confirmed' }
+  } catch {
+    return { kind: 'unknown' }
+  }
+}
+
+type WorkingTreeProbe = { kind: 'clean' | 'dirty' | 'unknown' }
+
+async function probeWorkingTree(identity: EthagentIdentity): Promise<WorkingTreeProbe> {
+  try {
+    const status: ContinuityWorkingTreeStatus = await continuityWorkingTreeStatus(identity)
+    if (!status.ready) return { kind: 'unknown' }
+    return status.localChangedAfterBackup ? { kind: 'dirty' } : { kind: 'clean' }
+  } catch {
+    return { kind: 'unknown' }
+  }
+}
+
+function unwrap<T>(result: PromiseSettledResult<T>, fallback: () => T): T {
+  if (result.status === 'fulfilled') return result.value
+  return fallback()
+}
+
+function computeDriftCount(r: AgentReconciliation): number {
+  let n = 0
+  if (r.token === 'unlinked') n++
+  if (r.custody === 'mid-flow-uri-pending') n++
+  if (r.agentUri === 'local-newer' || r.agentUri === 'chain-newer') n++
+  if (r.ensRecords === 'drift') n++
+  if (r.vault === 'missing') n++
+  if (r.workingTree === 'dirty') n++
+  return n
+}

package/src/identity/hub/reconciliation/agentReconciliation/types.ts

@@ -0,0 +1,17 @@
+import type { RecordsFixPlan } from '../walletSetup.js'
+
+export type AgentReconciliation = {
+  token: 'linked' | 'unlinked' | 'unknown' | 'no-agent'
+  tokenDetail?: string
+  tokenAgentId?: string
+  onChainOwner?: string
+  custody: 'simple' | 'advanced' | 'withdrawn' | 'mid-flow-uri-pending' | 'unknown'
+  agentUri: 'in-sync' | 'chain-newer' | 'local-newer' | 'unknown'
+  ensRecords: 'aligned' | 'drift' | 'unset' | 'unknown'
+  ensRecordsPlan?: RecordsFixPlan
+  vault: 'confirmed' | 'missing' | 'unset' | 'unknown'
+  workingTree: 'clean' | 'dirty' | 'unknown'
+  rpc: 'reachable' | 'failing'
+  driftCount: number
+  lastCheckedAt: string
+}

package/src/identity/hub/reconciliation/index.ts

@@ -0,0 +1,21 @@
+export {
+  invalidateOwnershipCache,
+  preflightTokenOwnership,
+  useAgentReconciliation,
+} from './useAgentReconciliation.js'
+export type {
+  AgentReconciliation,
+} from './useAgentReconciliation.js'
+export {
+  computeApprovalDiff,
+  describeFixPlanItem,
+  encodeResolverApprovalChanges,
+  fixPlanRequiresOwnerWallet,
+  reconcileWalletSetup,
+  verifyResolverApprovalsLanded,
+} from './walletSetup.js'
+export type {
+  ApprovalDiff,
+  RecordsFixPlan,
+  RecordsFixPlanItem,
+} from './walletSetup.js'

package/src/identity/hub/reconciliation/useAgentReconciliation.ts

@@ -0,0 +1,10 @@
+export { useAgentReconciliation } from './agentReconciliation/hook.js'
+export type { AgentReconciliation } from './agentReconciliation/types.js'
+export {
+  invalidateOwnershipCache,
+  preflightTokenOwnership,
+} from './agentReconciliation/ownership.js'
+export type {
+  OwnershipGuardResult,
+  OwnershipRole,
+} from './agentReconciliation/ownership.js'