@agent-wire/terminal 1.7.9 → 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';
@@ -11,12 +13,13 @@ import { readFile, writeFile, rename as fsRename, mkdir as fsMkdir, stat as fsSt
 import { join, isAbsolute } from 'path';
 import { loadConfig, saveConfig, CONFIG_DIR } from './config.js';
 import { resolveApiToken } from './api-token.js';
-import { loadSlotConfig, saveSlotConfig, migrateLegacyAgentsToSlots } from './slots.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;
@@ -29,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, '');
@@ -74,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)
@@ -85,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)
@@ -108,49 +106,6 @@ 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.'
@@ -183,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;
@@ -210,12 +166,11 @@ export const __mcpSurfaceTestInternals = {
     normalizeApiRootPath,
     SURFACE_REFRESH_TTL_MS,
     fingerprintSubstrateSurfaces,
-    parseToolRefreshPollIntervalMs,
     buildResumeResponse,
     looksLikeDeviceAuthFailure,
 };
 export async function startMcpServer(options) {
-    const loadedConfig = loadConfig({ allowInvalidTokenFile: true });
+    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.
@@ -229,8 +184,7 @@ 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);
-    // Discovery may use a configured token before a pin. Startup resumes its
-    // identity through GET /me; failed validation leaves wire_identify to pin later.
+    // 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
@@ -246,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.
@@ -362,6 +317,12 @@ 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.
@@ -381,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})`);
             }
@@ -509,8 +472,8 @@ 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))
@@ -519,7 +482,7 @@ export async function startMcpServer(options) {
     }
     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]);
@@ -547,13 +510,22 @@ 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) => {
+            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 };
@@ -575,7 +547,9 @@ export async function startMcpServer(options) {
         });
         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 &&
@@ -596,7 +570,7 @@ export async function startMcpServer(options) {
         // 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(), refreshSubstrateSurfaces(processSlot ? api : discoveryApi),
+            fetchToolDefinitions(forceCatalogRefresh), refreshSubstrateSurfaces(api, forceCatalogRefresh),
         ]);
         void saveToolDefinitionsCache(toolDefinitions);
         surfaceCache = { fetchedAt: Date.now(), surfaces };
@@ -665,6 +639,42 @@ 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`);
@@ -672,10 +682,6 @@ export async function startMcpServer(options) {
         catch (err) {
             console.error(`[wire-mcp] Surface discovery failed (${source}): ${err.message}`);
         }
-        finally {
-            if (processSlot)
-                startToolRefreshPoller();
-        }
     }
     function notifyToolListChanged(reason) {
         if (!server.isConnected())
@@ -683,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,
@@ -846,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),
@@ -877,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) }],
@@ -955,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) }],
@@ -1098,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.`,
@@ -1149,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) }],
                         };
                     }
@@ -1217,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),
                         };
@@ -1295,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) }],
                     };
                 }
@@ -1353,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),
                     };
@@ -1445,7 +1415,7 @@ export async function startMcpServer(options) {
                 '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.',
             ],
@@ -1740,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();
@@ -1755,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,
             };
@@ -1779,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) }] };
@@ -2029,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,
@@ -2917,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)'),
@@ -3007,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) }] };
@@ -3362,17 +3345,10 @@ export async function startMcpServer(options) {
     }
     // ── Connect transport ────────────────────────────────────────────────
     // Discover before the first tools/list. Without credentials, retry at pin.
-    const configuredToken = loadedConfig.apiToken;
-    if (configuredToken) {
-        let resumed;
-        try {
-            resumed = await resumeToken(discoveryApi, configuredToken);
-        }
-        catch (error) {
-            console.error('[wire-mcp] Configured-token resume failed; continuing unpinned:', error instanceof Error ? error.message : String(error));
-        }
-        if (resumed)
-            establishPin(resumed.name, resumed.identity, 'configured-token');
+    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) {
@@ -3414,6 +3390,7 @@ export async function startMcpServer(options) {
     }
     // Graceful shutdown
     const cleanup = () => {
+        catalogFollower?.stop();
         if (worker)
             worker.stop();
         releaseLock();