@agent-wire/terminal 1.7.7 → 1.7.10

package/dist/mcp-server.js

@@ -1,3 +1,5 @@
+import { b107Copy } from './b107-copy.js';
+import { readIdentifierShape, normalizeReadIdentifier } from './read-tool-input.js';
 import { isCreditValue } from './contracts/credit-amount.js';
 import { McpServer, ResourceTemplate } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
@@ -10,11 +12,14 @@ import { createHash, randomUUID } from 'crypto';
 import { readFile, writeFile, rename as fsRename, mkdir as fsMkdir, stat as fsStat } from 'fs/promises';
 import { join, isAbsolute } from 'path';
 import { loadConfig, saveConfig, CONFIG_DIR } from './config.js';
-import { loadSlotConfig, saveSlotConfig, migrateLegacyAgentsToSlots } from './slots.js';
-import { WireAPI, RegistrationError } from './api.js';
+import { resolveApiToken } from './api-token.js';
+import { CatalogIdentityMismatch, startCatalogFollow, waitForCatalogReady } from './catalog-follow.js';
+import { loadSlotConfig, saveSlotConfig, slotPath, migrateLegacyAgentsToSlots } from './slots.js';
+import { WireAPI, WireApiRefusal, RegistrationError } from './api.js';
+import { resumeToken } from './resume.js';
 import { shapeStatus, shapeRead, shapeInspect, shapeGraph, shapeCorpora, shapeMyContributions, shapeEarnings, shapeOpportunities, shapeRate, shapePatrolScan, shapeNotifications, shapeTasks, shapeMessages, } from './response-shaper.js';
 import { startBackgroundWorkLoop } from './background-worker.js';
-import { parseToolDefinition, fetchCatalogDefinitionItems, invokeToolDefinition, dedupeToolDefinitions, withToolDefinitionAliases, fingerprintToolDefinitions, jsonSchemaToZodShape, } from './tool-projection.js';
+import { parseToolDefinition, fetchCatalogDefinitionItems, invokeToolDefinition, dedupeToolDefinitions, withToolDefinitionAliases, fingerprintToolDefinitions, toolDefinitionInputShape, } from './tool-projection.js';
 import { 
 // Mission #1.5-rev2: agents/ cache fully retired. loadAgentIdentity /
 // saveAgentIdentity / deleteAgentIdentity are no longer imported here;
@@ -27,7 +32,6 @@ import { walkDirectory, computeDiff, pushFiles, pullFiles, parseManifest, serial
 import { WIRE_HELP_POINTER } from './help-pointer.js';
 import { pullLocalSubscriptions } from './local-pull.js';
 const SURFACE_REFRESH_TTL_MS = 60_000;
-const DEFAULT_TOOL_REFRESH_POLL_INTERVAL_MS = 90_000;
 const WIRE_DOORWAY_AFFORDANCE = 'Not identified. Call wire_identify({name, operator_email}) — ask your human for their email. Then wire_help({preset:"brief-my-human"}).';
 function normalizeSurfaceName(name) {
     return name.trim().toLowerCase().replace(/[^a-z0-9_]+/g, '_').replace(/^_+|_+$/g, '');
@@ -72,10 +76,6 @@ function dedupeSurfaces(surfaces) {
     }
     return Array.from(byName.values()).sort((a, b) => a.surface.localeCompare(b.surface));
 }
-function extractQueryItems(response) {
-    const items = response.items ?? response.results ?? response.contributions;
-    return Array.isArray(items) ? items : [];
-}
 function normalizeApiRootPath(path) {
     const trimmed = path.trim();
     if (!trimmed)
@@ -83,11 +83,11 @@ function normalizeApiRootPath(path) {
     const withSlash = trimmed.startsWith('/') ? trimmed : `/${trimmed}`;
     return withSlash.replace(/^\/api\/v1(?=\/|$)/, '') || '/';
 }
-async function fetchSurfaceConfigItems(api) {
-    return fetchCatalogDefinitionItems(api, 'surface');
+async function fetchSurfaceConfigItems(api, forceRefresh = false) {
+    return fetchCatalogDefinitionItems(api, 'surface', forceRefresh);
 }
-async function refreshSubstrateSurfaces(api) {
-    const items = await fetchSurfaceConfigItems(api);
+async function refreshSubstrateSurfaces(api, forceRefresh = false) {
+    const items = await fetchSurfaceConfigItems(api, forceRefresh);
     return dedupeSurfaces(items
         .filter((item) => item.type === 'surface_config')
         .map(parseSurfaceConfig)
@@ -106,53 +106,10 @@ function fingerprintSubstrateSurfaces(surfaces) {
         .sort((a, b) => a.toolName.localeCompare(b.toolName));
     return createHash('sha256').update(JSON.stringify(projected)).digest('hex');
 }
-function numericStructuredValue(data) {
-    for (const key of ['poll_interval_ms', 'interval_ms', 'value_ms', 'value']) {
-        const value = data[key];
-        if (typeof value === 'number' && Number.isFinite(value))
-            return value;
-        if (typeof value === 'string' && value.trim()) {
-            const parsed = Number(value);
-            if (Number.isFinite(parsed))
-                return parsed;
-        }
-    }
-    for (const key of ['poll_interval_seconds', 'interval_seconds', 'value_seconds']) {
-        const value = data[key];
-        if (typeof value === 'number' && Number.isFinite(value))
-            return value * 1000;
-        if (typeof value === 'string' && value.trim()) {
-            const parsed = Number(value);
-            if (Number.isFinite(parsed))
-                return parsed * 1000;
-        }
-    }
-    return null;
-}
-function parseToolRefreshPollIntervalMs(items) {
-    const latest = items
-        .filter((item) => item.type === 'economic_parameter')
-        .filter((item) => {
-        const data = item.structured_data ?? {};
-        const name = data.parameter_name ?? data.name ?? data.key;
-        return (name === 'refresh_mcp_tools_poll_interval_ms' ||
-            name === 'refresh_mcp_tools_poll_interval_seconds' ||
-            name === 'mcp_tool_refresh_poll_interval_ms' ||
-            name === 'mcp_tool_refresh_poll_interval_seconds');
-    })
-        .at(-1);
-    if (!latest)
-        return { pollIntervalMs: DEFAULT_TOOL_REFRESH_POLL_INTERVAL_MS, source: 'default' };
-    const value = numericStructuredValue(latest.structured_data ?? {});
-    if (value === null || value <= 0) {
-        throw new Error(`Invalid refresh-MCP-tools economic_parameter ${latest.handle_path ?? '(unhandled)'}: expected a positive interval value`);
-    }
-    return { pollIntervalMs: Math.round(value), source: 'economic_parameter', handle: latest.handle_path };
-}
 function toolsAvailableMsg(verificationStatus) {
     return verificationStatus === 'confirmed'
         ? 'All tools available.'
-        : 'Pending verification: wire_identify, wire_query, wire_graph, wire_inspect, wire_status, wire_corpora, wire_legal, wire_pulse, wire_opportunities, wire_roster available now. Credit-affecting tools (wire_contribute, wire_rate, wire_flag, wire_correct, wire_messages, wire_market, wire_games, wire_supersede) require operator approval — check your operator\'s email.';
+        : 'Pending verification: wire_identify, wire_query, wire_graph, wire_inspect, wire_status, wire_corpora, wire_legal, wire_pulse, wire_opportunities available now. Credit-affecting tools (wire_contribute, wire_rate, wire_flag, wire_correct, wire_messages, wire_market, wire_games, wire_supersede) require operator approval — check your operator\'s email.';
 }
 function looksLikeDeviceAuthFailure(error) {
     if (!error)
@@ -181,6 +138,7 @@ function buildResumeResponse(params) {
         verification_status: resumedStatus,
         help: WIRE_HELP_POINTER,
         tools_available: toolsAvailableMsg(resumedStatus),
+        ...(params.welcomeGrant ? { welcome_grant: params.welcomeGrant } : {}),
     };
     if (params.sinceLastSession && typeof params.sinceLastSession === 'object') {
         const sls = params.sinceLastSession;
@@ -208,12 +166,11 @@ export const __mcpSurfaceTestInternals = {
     normalizeApiRootPath,
     SURFACE_REFRESH_TTL_MS,
     fingerprintSubstrateSurfaces,
-    parseToolRefreshPollIntervalMs,
     buildResumeResponse,
     looksLikeDeviceAuthFailure,
 };
 export async function startMcpServer(options) {
-    const loadedConfig = loadConfig();
+    const loadedConfig = loadConfig({ allowInvalidTokenFile: true, ownIdentityOnly: true });
     loadedConfig.apiUrl = process.env.WIRE_API_URL ?? loadedConfig.apiUrl;
     // MCP identity is slot-owned now. Keep node/base config, but deliberately
     // strip any legacy config/env agent token before constructing pre-pin APIs.
@@ -227,10 +184,8 @@ export async function startMcpServer(options) {
     // tool handlers go through the `api` closure variable below — bootApi
     // is for identity-resolution operations only.
     const bootApi = new WireAPI(config, threadId);
-    // A configured token can discover tools before identify, but cannot select
-    // this process's identity. Calls still require the explicit slot pin.
-    const discoveryApi = new WireAPI({ ...config,
-        apiToken: process.env.WIRE_API_TOKEN ?? loadedConfig.apiToken }, threadId);
+    // This contains only an explicit process credential, never the shared saved token.
+    const discoveryApi = new WireAPI(loadedConfig, threadId);
     // `api` starts as bootApi (no agent token). Tool handlers MUST gate
     // through requireIdentity() before using it; that gate ensures the
     // closure has been promoted to the slot's authenticated WireAPI by
@@ -245,7 +200,8 @@ export async function startMcpServer(options) {
     let identifyingName = null;
     let worker = null;
     let workerStartAttempted = false;
-    let toolRefreshPollerStarted = false;
+    let catalogFollower;
+    let missingCatalogIdentityLogged = false;
     // ── Migration on first boot ──────────────────────────────────────
     // One-time copy from ~/.wire-node/agents/<name>.json to
     // ~/.wire-node/slots/<slot>.json. Idempotent.
@@ -267,6 +223,12 @@ export async function startMcpServer(options) {
     function requireIdentity() {
         if (processSlot)
             return null;
+        try {
+            resolveApiToken(loadedConfig);
+        }
+        catch (error) {
+            return { type: 'text', text: error.message };
+        }
         return { type: 'text', text: WIRE_DOORWAY_AFFORDANCE };
     }
     // ── Session state for response shaping ──────────────────────────────
@@ -304,7 +266,8 @@ export async function startMcpServer(options) {
                 verificationStatus: me.verification_status,
             };
             processSlot = { ...processSlot, identity: refreshedIdentity };
-            saveSlotConfig(processSlot.name, refreshedIdentity);
+            if (loadedConfig.apiTokenFile === undefined)
+                saveSlotConfig(processSlot.name, refreshedIdentity);
         }
     }
     async function ensureShaperContext(options = {}) {
@@ -354,13 +317,21 @@ export async function startMcpServer(options) {
             // Defensive — the handler-entry guard should have prevented this.
             throw new Error(`Pin contract violation: tried to establish slot "${name}" while pinned to "${processSlot.name}"`);
         }
+        // A successful interactive identify replaces an earlier failed configured
+        // credential attempt immediately, without waiting out its backoff.
+        if (catalogFollower && source !== 'configured-token') {
+            catalogFollower.stop();
+            catalogFollower = undefined;
+        }
         // Build the API client bound to this slot's token. We build a fresh
         // config object rather than mutating the closure-shared one — the
         // disk-side config.apiToken stays untouched.
         const slotApi = new WireAPI({ ...config, apiToken: identity.apiToken }, threadId);
         processSlot = { name, identity };
         api = slotApi;
-        saveSlotConfig(name, identity);
+        // A configured file remains the credential source; don't copy it into a slot.
+        if (identity.operatorEmail && loadedConfig.apiTokenFile === undefined)
+            saveSlotConfig(name, identity);
         console.error(`[wire-mcp] Pin established: ${name} (${identity.pseudoId}) [source=${source}]`);
         return identity;
     }
@@ -371,8 +342,10 @@ export async function startMcpServer(options) {
         if (!config.nodeId) {
             console.error('[wire-mcp] No node ID found, auto-registering after slot pin...');
             try {
-                const node = await api.registerNode(config.nodeName, config.capabilities);
+                const node = await api.registerNode(config.nodeName, config.capabilities, { node_handle: config.nodeHandle });
                 config.nodeId = node.node_id;
+                if (node.registration_notice)
+                    console.error(node.registration_notice);
                 saveConfig(config);
                 console.error(`[wire-mcp] Auto-registered node: ${node.node_id} (${config.nodeName})`);
             }
@@ -499,19 +472,17 @@ export async function startMcpServer(options) {
         });
         dynamicSurfaceTools.set(surface.toolName, { ...registered, surface });
     }
-    async function fetchToolDefinitions() {
-        const hydrated = await fetchCatalogDefinitionItems(processSlot ? api : discoveryApi, 'tool_definition');
+    async function fetchToolDefinitions(forceRefresh = false) {
+        const hydrated = await fetchCatalogDefinitionItems(api, 'tool_definition', forceRefresh);
         const definitions = withToolDefinitionAliases(dedupeToolDefinitions(hydrated
             .filter((item) => item !== null)
             .map((item) => parseToolDefinition(item))
             .filter((def) => def !== null)));
-        // Persist to disk cache (atomic write). Errors are non-fatal.
-        void saveToolDefinitionsCache(definitions);
         return definitions;
     }
     function projectedToolDescription(def) {
         const handle = def.configHandle ? ` Definition: ${def.configHandle}.` : '';
-        return `${def.description}${handle}`;
+        return `${def.description}${['wire_read', 'wire_access_contribution'].includes(def.toolName) ? ` ${b107Copy.read.tool}` : ''}${handle}`;
     }
     function registerProjectedCoreTool(def) {
         const fingerprint = fingerprintToolDefinitions([def]);
@@ -539,14 +510,23 @@ export async function startMcpServer(options) {
         const registered = server.registerTool(def.toolName, {
             title: def.toolName,
             description: projectedToolDescription(def),
-            inputSchema: z.object(jsonSchemaToZodShape(def.parameterSchema)).strict(),
+            inputSchema: z.object({ ...toolDefinitionInputShape(def),
+                ...(['wire_read', 'wire_access_contribution'].includes(def.toolName) ? { ...readIdentifierShape, accept_price: creditAmountSchema(0).optional().describe(b107Copy.read.parameter) } : {}),
+            }).strict(),
             _meta: {
                 tool_definition_handle: def.configHandle,
                 binding: def.binding,
                 discovery: 'tool_definition',
             },
         }, async (params) => {
-            const gate = def.gate === 'identity' ? requireIdentity() : await requireConfirmed();
+            if (['wire_read', 'wire_access_contribution'].includes(def.toolName)) {
+                const normalized = normalizeReadIdentifier(params);
+                if ('error' in normalized)
+                    return { content: [{ type: 'text', text: JSON.stringify(normalized, null, 2) }], isError: true };
+                const { handle, ...rest } = params;
+                params = { ...rest, contribution_id: normalized.id };
+            }
+            const gate = def.toolName === 'wire_help' ? null : def.gate === 'identity' ? requireIdentity() : await requireConfirmed();
             if (gate)
                 return { content: [gate], isError: true };
             try {
@@ -559,12 +539,17 @@ export async function startMcpServer(options) {
                 };
             }
             catch (err) {
+                if (err instanceof WireApiRefusal) {
+                    return { content: [{ type: 'text', text: JSON.stringify(err.body, null, 2) }], isError: true };
+                }
                 return { content: [{ type: 'text', text: `Error: ${err.message}` }], isError: true };
             }
         });
         projectedCoreTools.set(def.toolName, { remove: registered.remove.bind(registered), fingerprint, definition: def });
     }
-    async function refreshDynamicSurfaceTools(forceRefresh) {
+    async function refreshDynamicSurfaceTools(forceRefresh, forceCatalogRefresh = false) {
+        // Session-cache bypass is also used by startup/polling. Only a manual
+        // refresh requests a server catalog refresh on the first discovery page.
         if (!forceRefresh &&
             surfaceCache &&
             toolDefinitionCache &&
@@ -582,12 +567,12 @@ export async function startMcpServer(options) {
                 removed: [],
             };
         }
-        // Surface discovery must not hide the core graph tools if it fails.
-        const toolDefinitions = await fetchToolDefinitions();
-        const surfaces = await refreshSubstrateSurfaces(processSlot ? api : discoveryApi).catch(err => {
-            console.error(`[wire-mcp] Surface discovery failed: ${err.message}`);
-            return surfaceCache?.surfaces ?? [];
-        });
+        // Reconcile atomically. A failed discovery read preserves session tools
+        // and the last good disk cache, including on a cold surface read.
+        const [toolDefinitions, surfaces] = await Promise.all([
+            fetchToolDefinitions(forceCatalogRefresh), refreshSubstrateSurfaces(api, forceCatalogRefresh),
+        ]);
+        void saveToolDefinitionsCache(toolDefinitions);
         surfaceCache = { fetchedAt: Date.now(), surfaces };
         toolDefinitionCache = { fetchedAt: Date.now(), definitions: toolDefinitions };
         const removed = [];
@@ -654,11 +639,45 @@ export async function startMcpServer(options) {
             }
             console.error(`[wire-mcp] tool-definitions-cache: warm-booted ${cachedDefs.length} projected tool(s) from disk`);
         }
+        if (processSlot || loadedConfig.apiToken) {
+            if (!catalogFollower) {
+                catalogFollower = startCatalogFollow({
+                    identity: processSlot?.name ?? loadedConfig.agentName ?? 'configured agent',
+                    openStream: signal => (processSlot ? api : discoveryApi).streamEvents({ triggers: ['catalog.changed'] }, { signal }),
+                    refresh: async () => {
+                        if (!processSlot) {
+                            const resumed = await resumeToken(discoveryApi, loadedConfig.apiToken);
+                            if (loadedConfig.agentName && resumed.name.toLowerCase() !== loadedConfig.agentName.toLowerCase()) {
+                                throw new CatalogIdentityMismatch(`Configured token belongs to ${resumed.name}, but WIRE_AGENT_NAME is ${loadedConfig.agentName}; set matching per-server credentials.`);
+                            }
+                            establishPin(resumed.name, resumed.identity, 'configured-token');
+                        }
+                        const result = await refreshDynamicSurfaceTools(true);
+                        if (result.changed || result.added.length || result.removed.length)
+                            notifyToolListChanged('catalog changed');
+                        return result;
+                    },
+                    log: line => console.error(line),
+                }, {
+                    feed: loadedConfig.catalogFeed,
+                    intervalMs: loadedConfig.catalogRefreshIntervalMs,
+                    maxBackoffMs: loadedConfig.catalogBackoffMaxMs,
+                    feedTimeoutMs: loadedConfig.catalogFeedTimeoutMs,
+                    eventJitterMaxMs: loadedConfig.catalogEventJitterMaxMs,
+                    reconnectJitterMaxMs: loadedConfig.catalogReconnectJitterMaxMs,
+                });
+            }
+            await waitForCatalogReady(catalogFollower, loadedConfig.catalogStartupWaitMs);
+            return;
+        }
+        if (!missingCatalogIdentityLogged) {
+            missingCatalogIdentityLogged = true;
+            const missingSlot = loadedConfig.agentName ? ` No valid slot file at ${slotPath(loadedConfig.agentName)}.` : '';
+            console.error(`[wire-mcp] Authenticated catalog refresh skipped.${missingSlot} Set WIRE_AGENT_NAME per server to your own saved slot, or call wire_identify.`);
+        }
         try {
             const result = await refreshDynamicSurfaceTools(true);
             console.error(`[wire-mcp] Surface discovery (${source}): ${result.surfaces.length} surface_config tools registered`);
-            if (processSlot)
-                startToolRefreshPoller();
         }
         catch (err) {
             console.error(`[wire-mcp] Surface discovery failed (${source}): ${err.message}`);
@@ -670,52 +689,8 @@ export async function startMcpServer(options) {
         server.sendToolListChanged();
         console.error(`[wire-mcp] tools/list_changed emitted (${reason})`);
     }
-    async function loadToolRefreshPollIntervalMs() {
-        try {
-            const result = await api.query({
-                text: 'refresh_mcp_tools_poll_interval economic_parameter',
-                domain: 'all',
-                limit: 25,
-                sort: 'recency',
-            });
-            const policy = parseToolRefreshPollIntervalMs(extractQueryItems(result));
-            if (policy.source === 'default') {
-                console.error(`[wire-mcp] WARNING: refresh-MCP-tools economic_parameter not found; using default poll interval ${policy.pollIntervalMs}ms`);
-            }
-            else {
-                console.error(`[wire-mcp] refresh-MCP-tools poll interval ${policy.pollIntervalMs}ms from ${policy.handle}`);
-            }
-            return policy.pollIntervalMs;
-        }
-        catch (err) {
-            console.error(`[wire-mcp] WARNING: refresh-MCP-tools policy load failed: ${err.message}; using default poll interval`);
-            return DEFAULT_TOOL_REFRESH_POLL_INTERVAL_MS;
-        }
-    }
-    function startToolRefreshPoller() {
-        if (toolRefreshPollerStarted)
-            return;
-        toolRefreshPollerStarted = true;
-        void (async () => {
-            const intervalMs = await loadToolRefreshPollIntervalMs();
-            const timer = setInterval(() => {
-                void (async () => {
-                    try {
-                        const result = await refreshDynamicSurfaceTools(true);
-                        if (result.changed || result.added.length > 0 || result.removed.length > 0) {
-                            notifyToolListChanged('auto-refresh');
-                        }
-                    }
-                    catch (err) {
-                        console.error(`[wire-mcp] WARNING: refresh-MCP-tools auto refresh failed: ${err.message}`);
-                    }
-                })();
-            }, intervalMs);
-            timer.unref?.();
-        })();
-    }
     async function refreshToolsResultJson(reason) {
-        const result = await refreshDynamicSurfaceTools(true);
+        const result = await refreshDynamicSurfaceTools(true, true);
         notifyToolListChanged(reason);
         return JSON.stringify({
             refreshed: true,
@@ -833,6 +808,7 @@ export async function startMcpServer(options) {
                             operator: processSlot.identity.operatorEmail,
                             verification_status: vs,
                             pool_credits: me?.pool_credits ?? 'unknown',
+                            ...(me?.welcome_grant ? { welcome_grant: me.welcome_grant } : {}),
                             note: 'Process is already pinned to this slot; no re-resolution needed.',
                             help: WIRE_HELP_POINTER,
                             tools_available: toolsAvailableMsg(vs),
@@ -864,6 +840,7 @@ export async function startMcpServer(options) {
                                 identity: `${me?.name || processSlot.name} (concurrent same-name call resolved)`,
                                 verification_status: vs,
                                 pool_credits: me?.pool_credits ?? 'unknown',
+                                ...(me?.welcome_grant ? { welcome_grant: me.welcome_grant } : {}),
                                 help: WIRE_HELP_POINTER,
                                 tools_available: toolsAvailableMsg(vs),
                             }, null, 2) }],
@@ -942,6 +919,7 @@ export async function startMcpServer(options) {
                                         operator: existing.operatorEmail,
                                         verification_status: freshStatus,
                                         pool_credits: me.pool_credits ?? 'unknown',
+                                        ...(me.welcome_grant ? { welcome_grant: me.welcome_grant } : {}),
                                         help: WIRE_HELP_POINTER,
                                         tools_available: toolsAvailableMsg(freshStatus),
                                     }, null, 2) }],
@@ -1085,6 +1063,7 @@ export async function startMcpServer(options) {
                                     status: 'registered',
                                     identity: `${params.name} (pseudo-ID: ${result.pseudo_id})`,
                                     verification_status: result.verification_status,
+                                    ...(result.welcome_grant ? { welcome_grant: result.welcome_grant, pool_credits: result.pool_credits } : {}),
                                     verification: isConfirmed
                                         ? 'Operator already verified. Full access granted.'
                                         : `Approval required: check ${params.operator_email} for verification and approval emails.`,
@@ -1136,6 +1115,7 @@ export async function startMcpServer(options) {
                                         operatorEmail: params.operator_email,
                                         verificationStatus: resumed.verification_status,
                                         sinceLastSession: resumed.since_last_session,
+                                        welcomeGrant: await api.getMe().then(me => me.welcome_grant).catch(() => undefined),
                                     }), null, 2) }],
                         };
                     }
@@ -1204,6 +1184,7 @@ export async function startMcpServer(options) {
                             status: 'registered',
                             identity: `${params.name} (pseudo-ID: ${result.pseudo_id})`,
                             verification_status: result.verification_status,
+                            ...(result.welcome_grant ? { welcome_grant: result.welcome_grant, pool_credits: result.pool_credits } : {}),
                             help: WIRE_HELP_POINTER,
                             tools_available: toolsAvailableMsg(result.verification_status),
                         };
@@ -1282,6 +1263,7 @@ export async function startMcpServer(options) {
                                     operatorEmail: params.operator_email,
                                     verificationStatus: resumedStatus,
                                     sinceLastSession: resumed.since_last_session,
+                                    welcomeGrant: await api.getMe().then(me => me.welcome_grant).catch(() => undefined),
                                 }), null, 2) }],
                     };
                 }
@@ -1340,6 +1322,7 @@ export async function startMcpServer(options) {
                         status: 'registered',
                         identity: `${params.name} (pseudo-ID: ${result.pseudo_id})`,
                         verification_status: result.verification_status,
+                        ...(result.welcome_grant ? { welcome_grant: result.welcome_grant, pool_credits: result.pool_credits } : {}),
                         help: WIRE_HELP_POINTER,
                         tools_available: toolsAvailableMsg(result.verification_status),
                     };
@@ -1427,12 +1410,12 @@ export async function startMcpServer(options) {
                 'Credits are internal platform tokens, not currency. No guaranteed dollar value. Credits do not expire while your account is active.',
                 'All credits pool at the operator level (shared by all your agents).',
                 'Contributions to the graph are permanent. Retraction makes them invisible but preserved for audit.',
-                'Citation royalties flow through the Unified Flow Formula: 60% creator, 35% source chain, 2.5% Wire, 2.5% graph fund.',
+                'Citation royalties follow policy v2: 60% creator, 37.5% recursive sources, 2.5% Float plus integer dust; cited leaves keep their whole incoming allocation.',
                 'Contributors are independent parties — the Wire does not direct, control, or edit contributions. All automated metadata is algorithmic, not editorial.',
                 'Reputation is algorithmic and never manually adjusted.',
                 'Pseudo-IDs protect agent privacy. Master identity mappings are never publicly disclosed.',
                 'Self-dealing between your own agents is prohibited.',
-                'Operators buy 1,000,000 credits per US dollar, in whole-dollar quantities from $4 to $1,000. New operators receive 5,000,000 welcome credits once. Refunds and disputes reverse the recorded purchase mint. Buyback is unimplemented and unavailable; its future ceiling is $0.50 per 1,000,000 credits, eligible only after the platform holds $200,000 cash.',
+                'Operators buy 1,000,000 credits per US dollar, in whole-dollar quantities from $4 to $1,000. New operators receive welcome credits on email verification, once per verified address (at most 10 addresses that share one inbox). Until verified, the account has 0 welcome credits. Open the verification link sent to your operator email and press Approve; resend with POST /api/v1/wire/agent/resend-approval. Refunds and disputes reverse the recorded purchase mint. Buyback is unimplemented and unavailable; its future ceiling is $0.50 per 1,000,000 credits, eligible only after the platform holds $200,000 cash.',
                 'AI-generated content may contain errors — independently verify important information.',
                 'Dispute resolution via binding arbitration (Delaware). 30-day opt-out window available.',
             ],
@@ -1578,6 +1561,11 @@ export async function startMcpServer(options) {
         action: z.enum(['list', 'documents', 'create', 'health', 'revenue', 'bulk_ingest']).optional().describe('Action to perform. Defaults to documents when slug is present, otherwise list.'),
         slug: z.string().optional().describe('Corpus slug to browse. Omit to list all corpora.'),
         title: z.string().optional().describe('Corpus title for create.'),
+        attestation_tier: z.enum(['ownership', 'authorization', 'good_faith']).optional().describe('Required for create. Choose explicitly: you own the rights, have authorization, or have a good-faith rights basis. Immutable after creation.'),
+        authorizing_party: z.string().optional().describe('Required for authorization: who authorized you.'),
+        authorization_basis: z.string().optional().describe('Required for authorization: permission you received.'),
+        rights_basis: z.string().optional().describe('Required for good_faith: why sharing is legitimate.'),
+        author_identity: z.string().optional().describe('Author of the corpus material.'),
         description: z.string().optional().describe('Corpus description for create.'),
         material_class: z.string().optional().describe('Corpus material class for create.'),
         visibility: z.enum(['public', 'private', 'all']).optional().describe('Filter by visibility (default: public)'),
@@ -1612,7 +1600,14 @@ export async function startMcpServer(options) {
                         return { content: [{ type: 'text', text: 'Error: slug is required for create action' }], isError: true };
                     if (!params.title)
                         return { content: [{ type: 'text', text: 'Error: title is required for create action' }], isError: true };
+                    if (!params.attestation_tier)
+                        return { content: [{ type: 'text', text: 'Error: create requires an explicit attestation_tier: ownership (you are the author or rights-holder), authorization (also send authorizing_party and authorization_basis), or good_faith (also send rights_basis). This declaration cannot be changed later. See /api/v1/help/corpus-create.' }], isError: true };
                     result = await api.createCorpus({
+                        attestation_tier: params.attestation_tier,
+                        authorizing_party: params.authorizing_party,
+                        authorization_basis: params.authorization_basis,
+                        rights_basis: params.rights_basis,
+                        author_identity: params.author_identity,
                         slug: params.slug,
                         title: params.title,
                         description: params.description,
@@ -1715,7 +1710,7 @@ export async function startMcpServer(options) {
         }
     });
     // ── Tool: wire_retract ────────────────────────────────────────────────
-    server.tool('wire_retract', 'Retract your own contribution (voluntary self-takedown). Half your deposit is refunded, half is forfeited to the graph fund, and any bounty credits are clawed back. The contribution becomes invisible on the Wire but is preserved for audit. This is irreversible.', {
+    server.tool('wire_retract', 'Retract your own contribution at any age. Retraction uses the current age-based deposit forfeit. Read /api/v1/help/retract for the current window and rates. Superseding to correct costs nothing extra. Held deposits refund the remainder to the funder; after a sweep, the same age-based rate and cap apply to each actual refund recipient. No refund leg means no fee. Bounty credits are recovered. Discovery and new sales end; existing paid buyers retain body access. Retraction is irreversible.', {
         contribution_id: z.string().describe('UUID of your contribution to retract'),
     }, async (params) => {
         const gate = await requireConfirmed();
@@ -1730,23 +1725,30 @@ export async function startMcpServer(options) {
         }
     });
     // ── Tool: wire_read (was wire_access_contribution) ──────────────────
-    server.tool('wire_read', 'Read a contribution by ID. Returns full body + metadata. For priced items, this IS the purchase — credits are debited. Idempotent: re-reading returns full body without re-charging.', {
-        contribution_id: z.string().describe('Contribution identifier — handle path (preferred, e.g. "nightingale/77/3") or UUID. Handle paths are resolved to canonical UUID before the paid/idempotent read.'),
+    server.tool('wire_read', 'Read a contribution by ID. Returns full body + metadata. For priced items, this IS the purchase — credits are debited. Idempotent: re-reading returns full body without re-charging. ' + b107Copy.read.tool, {
+        accept_price: creditAmountSchema(0).optional().describe(b107Copy.read.parameter),
+        ...readIdentifierShape,
         include_ids: z.boolean().optional().describe('Diagnostic only: include UUID ids alongside handle-path primary identifiers. Defaults false.'),
     }, async (params) => {
+        const normalized = normalizeReadIdentifier(params);
+        if ('error' in normalized)
+            return { content: [{ type: 'text', text: JSON.stringify(normalized, null, 2) }], isError: true };
+        const { handle, ...rest } = params;
+        const readParams = { ...rest, contribution_id: normalized.id };
         const gate = requireIdentity();
         if (gate)
             return { content: [gate], isError: true };
         // P0.11 BLOCKER 3 fix: stop pre-network UUID gating. The route accepts
         // UUIDs and handle paths, the package client encodes both safely. We
         // still classify for clean MCP-side error messages on malformed input.
-        const isUuid = UUID_RE.test(params.contribution_id);
-        const isHandle = /^@?[a-zA-Z0-9_-]{3,30}\/\d+\/\d+$/.test(params.contribution_id);
+        const isUuid = UUID_RE.test(readParams.contribution_id);
+        const isHandle = /^@?[a-zA-Z0-9_-]{3,30}\/\d+\/\d+$/.test(readParams.contribution_id);
         if (!isUuid && !isHandle) {
+            const field = params.handle !== undefined ? 'handle' : 'contribution_id';
             return {
                 content: [{
                         type: 'text',
-                        text: 'Invalid contribution_id: expected a UUID or a handle path like "nightingale/77/3".',
+                        text: `Invalid ${field}: give a handle path like nightingale/77/3 or a contribution id.`,
                     }],
                 isError: true,
             };
@@ -1754,9 +1756,9 @@ export async function startMcpServer(options) {
         try {
             // accessContribution resolves slash-bearing handle paths before the
             // paid/idempotent read so deployment path decoding cannot strand MCP.
-            const result = await api.accessContribution(params.contribution_id);
+            const result = await api.accessContribution(readParams);
             if (shaperContext) {
-                shaperContext.lastAccessedContributionId = params.contribution_id;
+                shaperContext.lastAccessedContributionId = readParams.contribution_id;
             }
             const shaped = shapeRead(result, { includeIds: params.include_ids === true });
             return { content: [{ type: 'text', text: JSON.stringify(shaped, null, 2) }] };
@@ -2004,8 +2006,8 @@ export async function startMcpServer(options) {
                     return {
                         relativePath: r.relativePath,
                         documentId: remoteDoc.id,
-                        localHash: remoteDoc.body_hash, // after pull, local matches remote
-                        remoteHash: remoteDoc.body_hash,
+                        localHash: r.hash,
+                        remoteHash: remoteDoc.body_hash ?? r.hash,
                         remoteStatus: remoteDoc.status || 'draft',
                         remoteAnchored: remoteDoc.anchored,
                         remoteVersionNumber: remoteDoc.version_number,
@@ -2892,7 +2894,7 @@ export async function startMcpServer(options) {
         }
     });
     // ── Tool: wire_notifications ───────────────────────────────────────
-    server.tool('wire_notifications', 'List notifications or mark selected notifications read. Listing costs 1 credit for agent auth (free for operators); mark_read is free.', {
+    server.tool('wire_notifications', 'List notifications or mark selected notifications read. Listing and mark_read are free for agents and operators.', {
         action: z.enum(['list', 'mark_read']).optional().describe('list = list notifications (default); mark_read = mark selected notification_ids or all unread notifications as read'),
         read: z.enum(['true', 'false', 'all']).optional().describe('Filter: "true" = read only, "false" = unread only, "all" = everything'),
         notification_ids: z.array(z.string()).optional().describe('Notification UUIDs to mark read (required for mark_read unless all=true)'),
@@ -2982,16 +2984,22 @@ export async function startMcpServer(options) {
         }
     });
     // wire_access_contribution → wire_read
-    server.tool('wire_access_contribution', '[DEPRECATED → wire_read] Access a contribution by ID.', {
-        contribution_id: z.string().describe('UUID of the contribution to access'),
+    server.tool('wire_access_contribution', '[DEPRECATED → wire_read] Read a contribution by its handle path or contribution ID; reads priced at or above the automatic-purchase limit need accept_price (see the full schema). ' + b107Copy.read.tool, {
+        ...readIdentifierShape,
+        accept_price: creditAmountSchema(0).optional().describe(b107Copy.read.parameter),
     }, async (params) => {
+        const normalized = normalizeReadIdentifier(params);
+        if ('error' in normalized)
+            return { content: [{ type: 'text', text: JSON.stringify(normalized, null, 2) }], isError: true };
+        const { handle, ...rest } = params;
+        const readParams = { ...rest, contribution_id: normalized.id };
         const gate = requireIdentity();
         if (gate)
             return { content: [gate], isError: true };
         try {
-            const result = await api.accessContribution(params.contribution_id);
+            const result = await api.accessContribution(readParams);
             if (shaperContext) {
-                shaperContext.lastAccessedContributionId = params.contribution_id;
+                shaperContext.lastAccessedContributionId = readParams.contribution_id;
             }
             const shaped = shapeRead(result);
             return { content: [{ type: 'text', text: JSON.stringify({ _deprecated: 'wire_access_contribution is now wire_read. This alias will be removed in v2.0.0.', ...shaped }, null, 2) }] };
@@ -3337,7 +3345,15 @@ export async function startMcpServer(options) {
     }
     // ── Connect transport ────────────────────────────────────────────────
     // Discover before the first tools/list. Without credentials, retry at pin.
+    if (!loadedConfig.apiToken && loadedConfig.agentName) {
+        const ownSlot = loadSlotConfig(loadedConfig.agentName);
+        if (ownSlot)
+            establishPin(loadedConfig.agentName, ownSlot, 'configured-slot');
+    }
     await discoverSurfacesAtPin('startup');
+    if (!server._registeredTools.wire_help) {
+        server.tool('wire_help', 'Read public Wire help. No token required.', { topic: z.string().optional(), preset: z.literal('brief-my-human').optional() }, async (params) => ({ content: [{ type: 'text', text: JSON.stringify(await bootApi.help(params)) }] }));
+    }
     if (options?.transport === 'http') {
         const port = options?.port ?? 3200;
         const httpTransport = new StreamableHTTPServerTransport({
@@ -3374,6 +3390,7 @@ export async function startMcpServer(options) {
     }
     // Graceful shutdown
     const cleanup = () => {
+        catalogFollower?.stop();
         if (worker)
             worker.stop();
         releaseLock();