meguro-mcp 0.2.10 → 0.2.13

package/src/tools.mjs

@@ -3,7 +3,7 @@
 // Every control-plane call uses an account-scoped MEGURO_API_TOKEN (meg_sk_...).
 
 import { createHash } from 'node:crypto';
-import { documentationByTopic, documentationToolContract } from './docs.mjs';
+import { documentationToolContract, resolveDocumentationRead } from './docs.mjs';
 import {
   ADMIN_API_DEFAULT_VERSION,
   ADMIN_API_SUPPORTED_VERSION_LABEL,
@@ -15,6 +15,8 @@ const SECRET_VALUE = /\bmeg_(?:pw|sk)_[a-z0-9_-]+\b|\b(?:Bearer|Basic)\s+[A-Za-z
 const SECRET_HEADER = /\b(?:authorization|cookie|set-cookie|x-shopify-access-token|signed-snapshot-token)\s*[:=]\s*[^\s,;]+/giu;
 const SECRET_KEY = /(?:authorization|cookie|password|secret|token|api[_-]?key|signedsnapshot)/iu;
 const PRIVATE_RESPONSE_KEY = /^(?:raw|rawBody|rawBodyPreview|responsePayload|requestHeaders|responseHeaders|headers|cookies)$/iu;
+const MCP_TRUNCATION_SCHEMA_VERSION = 'meguro.mcp-truncation.v1';
+const MCP_TRUNCATION_KEY = 'mcpTruncation';
 const RESERVED_WORLD_IDS = new Set(['api', 'api-dev', 'www', 'dev', 'hooks', 'control']);
 const PRACTICE_ATTEMPT_ID = /^pa-[a-z0-9][a-z0-9-]{0,124}$/u;
 export const OPERATION_COMMIT_BOUNDARY_META_KEY = 'meguro/operationCommitBoundary';
@@ -25,15 +27,15 @@ const AUTH_TEACHING = Object.freeze({
 const DOCUMENTATION_TOOL_CONTRACT = documentationToolContract();
 const DOCUMENTATION_TOPICS = new Set(DOCUMENTATION_TOOL_CONTRACT.topics);
 const FLEET_TOOL_NAMES = new Set([
-  'templates_list', 'stores_list', 'store_create', 'store_delete', 'store_passport',
+  'templates_list', 'template_get', 'stores_list', 'store_create', 'store_delete', 'store_passport',
   'practice_runs_list',
   'workspaces_list', 'workspace_create', 'workspace_archive', 'workspace_unarchive',
-  'share_create', 'shares_list', 'share_status', 'share_publish', 'share_revoke',
   'catalog_slice_read', 'catalog_slice_snapshot', 'catalog_slices_saved',
   'store_claim_by_code', 'store_claim',
 ]);
 const TOOL_PRESENTATION = Object.freeze({
   templates_list: { title: 'List practice-store templates', readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+  template_get: { title: 'Read one practice-store template', readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
   stores_list: { title: 'List practice stores', readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
   store_create: { title: 'Create a practice store', readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
   store_delete: { title: 'Delete a practice store', readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: false },
@@ -42,11 +44,6 @@ const TOOL_PRESENTATION = Object.freeze({
   workspace_create: { title: 'Create a workspace', readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
   workspace_archive: { title: 'Archive a workspace', readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: false },
   workspace_unarchive: { title: 'Restore a workspace', readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false },
-  share_create: { title: 'Create or update a private share draft', readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
-  shares_list: { title: 'List evidence shares', readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
-  share_status: { title: 'Read an evidence share', readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
-  share_publish: { title: 'Publish evidence to client viewers', readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true },
-  share_revoke: { title: 'Revoke client-viewer evidence access', readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: true },
   catalog_slice_read: { title: 'Read a live Shopify catalog slice', readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
   catalog_slice_snapshot: { title: 'Mint a catalog slice snapshot', readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true },
   catalog_slices_saved: { title: 'Manage saved catalog slices', readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: true },
@@ -58,9 +55,9 @@ const TOOL_PRESENTATION = Object.freeze({
   run_report: { title: 'Read run receipt', readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
   run_resume: { title: 'Resume a Shopify dev-store run', readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true },
   runs_diff: { title: 'Compare history-run receipts', readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
-  gate_configure: { title: 'Configure the Receipt Gate', readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false },
-  gate_evaluate: { title: 'Evaluate the Receipt Gate', readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
-  gate_verdict: { title: 'Read a Gate verdict', readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+  gate_configure: { title: 'Configure Configured Receipt Gate', readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+  gate_evaluate: { title: 'Evaluate Configured Receipt Gate', readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
+  gate_verdict: { title: 'Read Configured Receipt Gate verdict', readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
   runs_list: { title: 'List history runs', readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
   usage_read: { title: 'Read usage headroom', readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
   twin_diff: { title: 'Read a twin impact receipt', readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
@@ -80,12 +77,23 @@ const TOOL_PRESENTATION = Object.freeze({
   get_connection_details: { title: 'Get practice-store connection details', readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
   admin_probe: { title: 'Run an Admin API probe', readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
   admin_schema: { title: 'Look up the Admin API schema', readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+  admin_recipes_list: { title: 'List Admin API recipes', readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+  plan_validate: { title: 'Check an intended Admin operation plan against Meguro', readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
 });
 
 function textResult(value) {
   return { content: [{ type: 'text', text: typeof value === 'string' ? value : JSON.stringify(value, null, 2) }] };
 }
 
+function configuredReceiptGateResult(value, action) {
+  const result = textResult(value);
+  result.content.push({
+    type: 'text',
+    text: `Configured Receipt Gate ${action}. This optional configured policy is separate from the receipt's automatic recorded API behavior; the receipt's recorded API behavior remains available.`,
+  });
+  return result;
+}
+
 function errorResult(message) {
   return { content: [{ type: 'text', text: scrubString(message) }], isError: true };
 }
@@ -108,19 +116,60 @@ export function redactSecrets(value) {
   return scrubString(value);
 }
 
-function secretSafe(value, depth = 0) {
+function secretSafePath(parent, key, arrayIndex = false) {
+  if (arrayIndex) return `${parent}[${key}]`;
+  return /^[A-Za-z_$][A-Za-z0-9_$]*$/u.test(key)
+    ? `${parent}.${key}`
+    : `${parent}[${JSON.stringify(key)}]`;
+}
+
+function secretSafeValue(value, depth, path, truncations) {
   if (depth > 12) return '[TRUNCATED]';
-  if (typeof value === 'string') return scrubString(value).slice(0, 10_000);
-  if (Array.isArray(value)) return value.slice(0, 100).map((child) => secretSafe(child, depth + 1));
+  if (typeof value === 'string') {
+    const scrubbed = scrubString(value);
+    const returned = scrubbed.slice(0, 10_000);
+    if (returned.length < scrubbed.length) {
+      truncations.push({ path, kind: 'string', originalSize: scrubbed.length, returnedSize: returned.length });
+    }
+    return returned;
+  }
+  if (Array.isArray(value)) {
+    const returned = value.slice(0, 100);
+    if (returned.length < value.length) {
+      truncations.push({ path, kind: 'array', originalSize: value.length, returnedSize: returned.length });
+    }
+    return returned.map((child, index) => secretSafeValue(
+      child,
+      depth + 1,
+      secretSafePath(path, index, true),
+      truncations,
+    ));
+  }
   if (value && typeof value === 'object') {
-    return Object.fromEntries(Object.entries(value)
-      .filter(([key]) => !SECRET_KEY.test(key) && !PRIVATE_RESPONSE_KEY.test(key))
-      .slice(0, 100)
-      .map(([key, child]) => [key, secretSafe(child, depth + 1)]));
+    const visibleEntries = Object.entries(value)
+      .filter(([key]) => !SECRET_KEY.test(key) && !PRIVATE_RESPONSE_KEY.test(key));
+    const returned = visibleEntries.slice(0, 100);
+    if (returned.length < visibleEntries.length) {
+      truncations.push({ path, kind: 'object', originalSize: visibleEntries.length, returnedSize: returned.length });
+    }
+    return Object.fromEntries(returned.map(([key, child]) => [
+      key,
+      secretSafeValue(child, depth + 1, secretSafePath(path, key), truncations),
+    ]));
   }
   return value;
 }
 
+function secretSafe(value, depth = 0) {
+  const truncations = [];
+  const safe = secretSafeValue(value, depth, '$', truncations);
+  if (truncations.length === 0) return safe;
+  const evidence = { schemaVersion: MCP_TRUNCATION_SCHEMA_VERSION, entries: truncations };
+  return safe && typeof safe === 'object' && !Array.isArray(safe)
+    ? { ...safe, [MCP_TRUNCATION_KEY]: evidence }
+    : { value: safe, [MCP_TRUNCATION_KEY]: evidence };
+}
+
 function authenticationErrorResult(status, value) {
   if (status !== 401 && status !== 403) return null;
   const body = value && typeof value === 'object' ? value : {};
@@ -176,8 +225,55 @@ function catalogSnapshotProjection(value) {
     : safe;
 }
 
+function enforcementProjection(body) {
+  if (!body || typeof body !== 'object') return {};
+  const hasStructuredEnforcement = typeof body.blockedCapability === 'string'
+    || typeof body.tier === 'string'
+    || Number.isFinite(body.allowance)
+    || Number.isFinite(body.currentUsage)
+    || Number.isFinite(body.requestedAmount)
+    || (body.sameTierAction && typeof body.sameTierAction === 'object')
+    || typeof body.targetTier === 'string'
+    || typeof body.upgradePath === 'string';
+  if (!hasStructuredEnforcement) return {};
+  return {
+    ...(typeof body.code === 'string' ? { code: body.code } : {}),
+    ...(typeof body.blockedCapability === 'string' ? { blockedCapability: body.blockedCapability } : {}),
+    ...(typeof body.tier === 'string' ? { tier: body.tier } : {}),
+    ...(Number.isFinite(body.allowance) ? { allowance: body.allowance } : {}),
+    ...(Number.isFinite(body.currentUsage) ? { currentUsage: body.currentUsage } : {}),
+    ...(Number.isFinite(body.requestedAmount) ? { requestedAmount: body.requestedAmount } : {}),
+    ...(body.sameTierAction && typeof body.sameTierAction === 'object'
+      ? { sameTierAction: secretSafe(body.sameTierAction) }
+      : {}),
+    ...(typeof body.targetTier === 'string' ? { targetTier: body.targetTier } : {}),
+    ...(typeof body.upgradePath === 'string' ? { upgradePath: body.upgradePath } : {}),
+  };
+}
+
+/**
+ * MEG-1058: the compact list tier. `templates_list` carries only what a cold agent needs to CHOOSE;
+ * everything it needs to USE a template is one `template_get` hop away. Both are projected from the
+ * same compiled catalog, so there is no second template contract.
+ */
+const STORE_TEMPLATE_LIST_FIELDS = Object.freeze([
+  'key',
+  'label',
+  'category',
+  'recommended',
+  'bestFor',
+  'recommendedRunDays',
+]);
+
+/**
+ * MEG-1058: the detail tier's allowlist — the complete public-safe record `template_get` returns.
+ * `revision` and `evaluationContext` join it here: both are ordinary template declarations the
+ * detail hop is meant to answer with, and a record missing them is not the complete one.
+ */
 const STORE_TEMPLATE_FIELDS = Object.freeze([
   'key',
+  'revision',
+  'evaluationContext',
   'label',
   'category',
   'recommended',
@@ -192,47 +288,204 @@ const STORE_TEMPLATE_FIELDS = Object.freeze([
   'extendedRunDays',
   'whatAgentGets',
   'supportedReads',
+  'modeledEvidence',
   'liveRun',
   'goodFirstAgents',
   'supportedWrites',
+  'operationContracts',
   'knownUnsupported',
+  'unsupportedContracts',
+  'capabilityBoundaries',
+  'modeledPhysics',
   'goodAgentShould',
   'avoid',
   'reportGrades',
 ]);
 
+/**
+ * MEG-1058: the detail tier's projection. Same allowlist the list used to carry, applied to the one
+ * record the server selected — the catalog is never fetched or returned as this tool's result.
+ */
+function storeTemplateDetailProjection(value) {
+  const storeTemplate = value?.storeTemplate;
+  if (!storeTemplate || typeof storeTemplate !== 'object' || Array.isArray(storeTemplate) || typeof storeTemplate.key !== 'string') {
+    throw new Error('Meguro template detail response did not contain a storeTemplate');
+  }
+  return {
+    storeTemplate: Object.fromEntries(STORE_TEMPLATE_FIELDS
+      .filter((field) => Object.hasOwn(storeTemplate, field))
+      .map((field) => [field, secretSafe(storeTemplate[field], 1)])),
+  };
+}
+
 function storeTemplatesProjection(value) {
   if (!Array.isArray(value?.storeTemplates)) {
     throw new Error('Meguro template catalog response did not contain storeTemplates');
   }
-  const starterTemplateKeys = value.storeTemplates
-    .filter((template) => template?.recommended === true && typeof template?.key === 'string')
-    .map((template) => template.key);
+  const storeTemplates = value.storeTemplates.map((template) => {
+    if (!template || typeof template !== 'object' || Array.isArray(template) || typeof template.key !== 'string') {
+      throw new Error('Meguro template catalog contained an invalid template entry');
+    }
+    return Object.fromEntries(STORE_TEMPLATE_LIST_FIELDS
+      .filter((field) => Object.hasOwn(template, field))
+      .map((field) => [field, secretSafe(template[field], 1)]));
+  });
+  const catalogTemplateKeys = storeTemplates.map((template) => template.key);
+  const declaredTemplateKeys = value?.starterRecommendation?.templateKeys;
+  const starterTemplateKeys = Array.isArray(declaredTemplateKeys)
+    && declaredTemplateKeys.every((key) => typeof key === 'string' && catalogTemplateKeys.includes(key))
+    ? [...declaredTemplateKeys]
+    : [];
+  let invalidRecommendation = starterTemplateKeys.length !== (declaredTemplateKeys?.length ?? -1);
   const declaredStarterBasis = typeof value?.starterRecommendation?.basis === 'string'
     && /^[a-z0-9-]{1,64}$/u.test(value.starterRecommendation.basis)
     ? value.starterRecommendation.basis
     : 'starter-for-first-simulation';
+  const projectStarterPlan = (starterPlan) => {
+    const positiveInteger = (candidate) => Number.isSafeInteger(candidate) && candidate > 0;
+    const nonNegativeInteger = (candidate) => Number.isSafeInteger(candidate) && candidate >= 0;
+    const valid = starterPlan
+      && typeof starterPlan === 'object'
+      && !Array.isArray(starterPlan)
+      && starterPlan.schemaVersion === 'meguro.practice-run-starter-plan.v1'
+      && ['developer', 'solo', 'builder'].includes(starterPlan.tier)
+      && typeof starterPlan.templateKey === 'string'
+      && catalogTemplateKeys.includes(starterPlan.templateKey)
+      && positiveInteger(starterPlan.idealRunDays)
+      && positiveInteger(starterPlan.scenarioArcDays)
+      && positiveInteger(starterPlan.firstSegmentDays)
+      && starterPlan.practiceRunStart
+      && typeof starterPlan.practiceRunStart === 'object'
+      && starterPlan.practiceRunStart.clock
+      && typeof starterPlan.practiceRunStart.clock === 'object'
+      && positiveInteger(starterPlan.practiceRunStart.clock.simulationDays)
+      && starterPlan.continuation
+      && typeof starterPlan.continuation === 'object'
+      && typeof starterPlan.continuation.available === 'boolean'
+      && nonNegativeInteger(starterPlan.continuation.remainingArcDaysAfterFirstSegment)
+      && (starterPlan.continuation.remainingAuthorizedDaysAfterFirstSegment === undefined
+        || nonNegativeInteger(starterPlan.continuation.remainingAuthorizedDaysAfterFirstSegment))
+      && positiveInteger(starterPlan.continuation.maxCanvasWorldDays)
+      && (starterPlan.authorization === undefined || (
+        starterPlan.authorization
+        && ['account-onboarding-grant', 'ordinary-tier'].includes(starterPlan.authorization.source)
+        && positiveInteger(starterPlan.authorization.idealHorizonDays)
+      ))
+      && starterPlan.usage
+      && typeof starterPlan.usage === 'object'
+      && typeof starterPlan.usage.runStartAllowed === 'boolean'
+      && ((starterPlan.usage.runStartAllowedMeaning === undefined && starterPlan.usage.runStartAllowance === undefined) || (
+        starterPlan.usage.runStartAllowedMeaning === 'metering-allowance-only'
+        && starterPlan.usage.runStartAllowance
+        && typeof starterPlan.usage.runStartAllowance === 'object'
+        && starterPlan.usage.runStartAllowance.schemaVersion === 'meguro.run-start-allowance.v1'
+        && starterPlan.usage.runStartAllowance.permitsChargedRun === starterPlan.usage.runStartAllowed
+        && ['metering-allowance-available', 'metering-allowance-exhausted'].includes(starterPlan.usage.runStartAllowance.reasonCode)
+        && starterPlan.usage.runStartAllowance.meaning === 'metering-allowance-only'
+        && starterPlan.usage.runStartAllowance.detail === 'Whether current tier metering allowance permits one charged simulation run; this is not overall store/root lifecycle eligibility.'
+      ))
+      && nonNegativeInteger(starterPlan.usage.remainingSimulationRuns);
+    if (!valid) throw new Error('Meguro template catalog contained an invalid starterPlan');
+    return {
+      schemaVersion: starterPlan.schemaVersion,
+      tier: starterPlan.tier,
+      templateKey: starterPlan.templateKey,
+      idealRunDays: starterPlan.idealRunDays,
+      scenarioArcDays: starterPlan.scenarioArcDays,
+      firstSegmentDays: starterPlan.firstSegmentDays,
+      ...(starterPlan.authorization ? { authorization: {
+        source: starterPlan.authorization.source,
+        idealHorizonDays: starterPlan.authorization.idealHorizonDays,
+      } } : {}),
+      practiceRunStart: { clock: { simulationDays: starterPlan.practiceRunStart.clock.simulationDays } },
+      continuation: {
+        available: starterPlan.continuation.available,
+        remainingArcDaysAfterFirstSegment: starterPlan.continuation.remainingArcDaysAfterFirstSegment,
+        ...(starterPlan.continuation.remainingAuthorizedDaysAfterFirstSegment !== undefined
+          ? { remainingAuthorizedDaysAfterFirstSegment: starterPlan.continuation.remainingAuthorizedDaysAfterFirstSegment }
+          : {}),
+        maxCanvasWorldDays: starterPlan.continuation.maxCanvasWorldDays,
+      },
+      usage: {
+        runStartAllowed: starterPlan.usage.runStartAllowed,
+        ...(starterPlan.usage.runStartAllowedMeaning ? {
+          runStartAllowedMeaning: starterPlan.usage.runStartAllowedMeaning,
+          runStartAllowance: {
+            schemaVersion: starterPlan.usage.runStartAllowance.schemaVersion,
+            permitsChargedRun: starterPlan.usage.runStartAllowance.permitsChargedRun,
+            reasonCode: starterPlan.usage.runStartAllowance.reasonCode,
+            meaning: starterPlan.usage.runStartAllowance.meaning,
+            detail: starterPlan.usage.runStartAllowance.detail,
+          },
+        } : {}),
+        remainingSimulationRuns: starterPlan.usage.remainingSimulationRuns,
+      },
+    };
+  };
+  const starterPlan = value?.starterRecommendation?.starterPlan;
+  const starterPlans = value?.starterRecommendation?.starterPlans;
+  let projectedStarterPlan;
+  let projectedStarterPlans;
+  try {
+    projectedStarterPlans = starterPlans === undefined
+      ? undefined
+      : Array.isArray(starterPlans) ? starterPlans.map(projectStarterPlan) : (() => { throw new Error('invalid starterPlans'); })();
+    if (projectedStarterPlans) {
+      const planKeys = projectedStarterPlans.map((plan) => plan.templateKey);
+      if (new Set(planKeys).size !== planKeys.length
+        || planKeys.some((key) => !catalogTemplateKeys.includes(key))) {
+        throw new Error('invalid starterPlans');
+      }
+    }
+    projectedStarterPlan = starterPlan === undefined ? undefined : projectStarterPlan(starterPlan);
+    if (projectedStarterPlan && !starterTemplateKeys.includes(projectedStarterPlan.templateKey)) {
+      throw new Error('invalid selected starterPlan');
+    }
+  } catch {
+    projectedStarterPlan = undefined;
+    projectedStarterPlans = undefined;
+    invalidRecommendation = true;
+  }
+  const serverUnavailable = value?.starterRecommendation?.recommendationUnavailable;
+  const projectedUnavailable = serverUnavailable
+    && typeof serverUnavailable === 'object'
+    && serverUnavailable.schemaVersion === 'meguro.practice-starter-recommendation-unavailable.v1'
+    && ['run-start-unavailable', 'usage-unavailable'].includes(serverUnavailable.code)
+    ? {
+      schemaVersion: serverUnavailable.schemaVersion,
+      code: serverUnavailable.code,
+    }
+    : undefined;
+  const recommendationUnavailable = invalidRecommendation
+    ? {
+      schemaVersion: 'meguro.practice-starter-recommendation-unavailable.v1',
+      code: 'invalid-server-recommendation',
+    }
+    : projectedUnavailable;
   return {
     starterRecommendation: {
       basis: declaredStarterBasis,
       templateKeys: starterTemplateKeys,
+      ...(projectedStarterPlan ? { starterPlan: projectedStarterPlan } : {}),
+      ...(projectedStarterPlans ? { starterPlans: projectedStarterPlans } : {}),
+      ...(recommendationUnavailable ? { recommendationUnavailable } : {}),
     },
-    storeTemplates: value.storeTemplates.map((template) => {
-      if (!template || typeof template !== 'object' || Array.isArray(template)) {
-        throw new Error('Meguro template catalog contained an invalid template entry');
-      }
-      return Object.fromEntries(STORE_TEMPLATE_FIELDS
-        .filter((field) => Object.hasOwn(template, field))
-        .map((field) => [field, secretSafe(template[field], 1)]));
-    }),
+    storeTemplates,
   };
 }
 
-function practiceErrorResult(status, value, retryAfterSeconds, teaching) {
+function practiceErrorResult(status, value, retryAfterSeconds, teaching, declaredBoundary) {
   const authenticationError = authenticationErrorResult(status, value);
   if (authenticationError) return authenticationError;
   const body = value && typeof value === 'object' ? value : {};
-  const stable = { httpStatus: status };
+  const stable = { httpStatus: status, ...enforcementProjection(body) };
+  if (body.code === 'terminal-advance-confirmation-required') {
+    stable.code = body.code;
+    stable.terminalAdvance = secretSafe(body.terminalAdvance);
+  }
+  if (body.advanceCursor && typeof body.advanceCursor === 'object') {
+    stable.advanceCursor = secretSafe(body.advanceCursor);
+  }
   if (['requested-exceeds-cap', 'continuation-unavailable', 'limit-reached'].includes(body.reason)) {
     stable.reason = body.reason;
   }
@@ -253,7 +506,16 @@ function practiceErrorResult(status, value, retryAfterSeconds, teaching) {
   else if (Number.isFinite(bodyRetryAfter) && bodyRetryAfter >= 0) stable.retryAfterSeconds = bodyRetryAfter;
   if (typeof body.retryable === 'boolean') stable.retryable = body.retryable;
   if (teaching) stable.teaching = secretSafe(teaching);
-  return { content: [{ type: 'text', text: JSON.stringify(stable, null, 2) }], isError: true };
+  const result = { content: [{ type: 'text', text: JSON.stringify(stable, null, 2) }], isError: true };
+  // MEG-1057: an attempt-identity 404 is pre-commit by construction — nothing can have applied
+  // against an attempt that does not exist. Without this the mutating routes fell through to the
+  // caller-facing default of `unknown`, which asks the agent to go read state before retrying an
+  // operation that never had a target.
+  if (isPracticeRunUnavailable(status, body)) return withOperationCommitBoundary(result, 'pre-commit');
+  if (declaredBoundary) return withOperationCommitBoundary(result, declaredBoundary);
+  return ['pre-commit', 'committed', 'unknown'].includes(body.operationCommitBoundary)
+    ? withOperationCommitBoundary(result, body.operationCommitBoundary)
+    : result;
 }
 
 function practiceRunUnavailableTeaching(toolName, attemptId) {
@@ -266,22 +528,30 @@ function practiceRunUnavailableTeaching(toolName, attemptId) {
 
 function gateReceiptUnavailableTeaching(toolName, receiptId) {
   return {
-    meaning: `No completed practice simulation receipt is available for receiptId ${receiptId}. Receipt Gate uses the pa-* practice-run attempt identity, not a public receipt digest or a history-run id.`,
+    meaning: `No completed practice simulation receipt is available for receiptId ${receiptId}. Configured Receipt Gate uses the pa-* practice-run attempt identity, not a public receipt digest or a history-run id.`,
     nextStep: `Call stores_list({}), choose an exact storeId, call practice_run_start({ storeId: "<exact storeId>" }), complete the simulation, call practice_run_finish({ attemptId: "<returned attemptId>" }), then call practice_run_report({ attemptId: "<returned attemptId>" }). Use that same returned attemptId as receiptId and call ${toolName}({ receiptId: "<returned attemptId>" }).`,
-    stopCondition: 'If practice_run_report does not return a completed receipt for that attemptId, stop. Do not retry Receipt Gate with an unavailable receiptId.',
+    stopCondition: 'If practice_run_report does not return a completed receipt for that attemptId, stop. Do not retry Configured Receipt Gate with an unavailable receiptId.',
+  };
+}
+
+function practiceStoreUnavailableTeaching(storeId) {
+  return {
+    meaning: `No practice store with storeId ${storeId} is available to this account, so no practice run was started.`,
+    nextStep: 'Call stores_list({}), choose an exact current storeId, then call practice_run_start({ storeId: "<exact storeId>" }).',
+    stopCondition: `If stores_list({}) does not return ${storeId}, stop. Do not retry practice_run_start with the unavailable storeId.`,
   };
 }
 
 function isPracticeRunUnavailable(status, value) {
-  return status === 404 && value?.practiceRunError?.code === 'practice-run-unavailable';
+  return status === 404;
 }
 
 function isGateReceiptUnavailable(status, value) {
-  if (status !== 404) return false;
-  const messages = Array.isArray(value?.errors)
-    ? value.errors.map((error) => String(error?.message ?? ''))
-    : [String(value?.error?.message ?? value?.error ?? '')];
-  return messages.some((message) => /receipt not found/iu.test(message));
+  return status === 404;
+}
+
+function isPracticeStoreUnavailable(status, value) {
+  return status === 404;
 }
 
 function requiredString(args, key) {
@@ -311,11 +581,11 @@ function requiredWorkspaceId(args) {
   return workspaceId;
 }
 
-function requiredShareId(args) {
-  const shareId = requiredString(args, 'shareId');
-  if (!/^[0-9a-f]{32}$/u.test(shareId)) throw new Error('shareId must be the exact 32-character lowercase hex id returned by shares_list');
-  return shareId;
-}
+const OPTIONAL_WORKSPACE_SELECTOR_INPUT_SCHEMA = Object.freeze({
+  type: 'string',
+  minLength: 1,
+  description: 'Optional account-owned workspace selector. Omit for Default.',
+});
 
 function optionalStringList(args, key, options = {}) {
   const value = args?.[key];
@@ -351,6 +621,115 @@ function requiredSavedSliceId(args) {
   return sliceId;
 }
 
+const CATALOG_SNAPSHOT_INPUT_PROPERTIES = Object.freeze({
+  workspaceId: { type: 'string', minLength: 1, description: 'Optional account-owned workspace selector. Omit for Default.' },
+  shopDomain: { type: 'string', pattern: '^[a-z0-9][a-z0-9-]*\\.myshopify\\.com$', description: 'Live snapshot source. Mutually exclusive with sliceId.' },
+  variantIds: { type: 'array', minItems: 1, maxItems: 25, items: { type: 'string', minLength: 1 }, description: 'Exact Shopify variant ids returned by catalog_slice_read. Required with shopDomain.' },
+  sliceId: { type: 'string', pattern: '^csl_saved_[A-Za-z0-9_-]{8,128}$', description: 'Saved snapshot source. Mutually exclusive with shopDomain/variantIds.' },
+});
+
+const CATALOG_SAVED_SLICES_INPUT_PROPERTIES = Object.freeze({
+  workspaceId: { type: 'string', minLength: 1, description: 'Optional account-owned workspace selector. Omit for Default.' },
+  action: { type: 'string', enum: ['list', 'get', 'save', 'delete', 'refresh', 'changes'] },
+  shopDomain: { type: 'string', pattern: '^[a-z0-9][a-z0-9-]*\\.myshopify\\.com$', description: 'Required for save.' },
+  label: { type: 'string', minLength: 1, maxLength: 80, description: 'Required for save.' },
+  variantIds: { type: 'array', minItems: 1, maxItems: 25, items: { type: 'string', minLength: 1 }, description: 'Required for save.' },
+  sliceId: { type: 'string', pattern: '^csl_saved_[A-Za-z0-9_-]{8,128}$', description: 'Required for get/delete/refresh/changes.' },
+});
+
+function catalogConditionalBranch({ id, action, mutates, required, forbidden, example }) {
+  return Object.freeze({
+    id,
+    action,
+    mutates,
+    required: Object.freeze([...required]),
+    example: Object.freeze(example),
+    schema: Object.freeze({
+      type: 'object',
+      ...(action ? { properties: { action: { const: action } } } : {}),
+      required: [...required],
+      ...(forbidden.length > 0
+        ? { not: { anyOf: forbidden.map((key) => ({ required: [key] })) } }
+        : {}),
+    }),
+  });
+}
+
+function conditionalToolInputSchema(properties, branches) {
+  return Object.freeze({
+    type: 'object',
+    additionalProperties: false,
+    properties,
+    required: [],
+    oneOf: branches.map((branch) => branch.schema),
+  });
+}
+
+// Each branch owns the published shape, dispatch selection, and its teaching example. Keeping
+// these together prevents the schema from admitting a selector combination that the handler will
+// later refuse or silently ignore.
+const CATALOG_SNAPSHOT_BRANCHES = Object.freeze([
+  catalogConditionalBranch({
+    id: 'saved',
+    mutates: true,
+    required: ['sliceId'],
+    forbidden: ['shopDomain', 'variantIds'],
+    example: { sliceId: 'csl_saved_01234567' },
+  }),
+  catalogConditionalBranch({
+    id: 'live',
+    mutates: false,
+    required: ['shopDomain', 'variantIds'],
+    forbidden: ['sliceId'],
+    example: { shopDomain: 'merchant.myshopify.com', variantIds: ['gid://shopify/ProductVariant/1'] },
+  }),
+]);
+
+const CATALOG_SAVED_SLICES_BRANCHES = Object.freeze([
+  catalogConditionalBranch({
+    id: 'list',
+    action: 'list',
+    mutates: false,
+    required: ['action'],
+    forbidden: ['shopDomain', 'label', 'variantIds', 'sliceId'],
+    example: { action: 'list' },
+  }),
+  catalogConditionalBranch({
+    id: 'save',
+    action: 'save',
+    mutates: true,
+    required: ['action', 'shopDomain', 'label', 'variantIds'],
+    forbidden: ['sliceId'],
+    example: {
+      action: 'save',
+      shopDomain: 'merchant.myshopify.com',
+      label: 'Agent watchlist',
+      variantIds: ['gid://shopify/ProductVariant/1'],
+    },
+  }),
+  ...['get', 'delete', 'refresh', 'changes'].map((action) => catalogConditionalBranch({
+    id: action,
+    action,
+    mutates: action === 'delete' || action === 'refresh',
+    required: ['action', 'sliceId'],
+    forbidden: ['shopDomain', 'label', 'variantIds'],
+    example: { action, sliceId: 'csl_saved_01234567' },
+  })),
+]);
+
+const CATALOG_SNAPSHOT_INPUT_SCHEMA = conditionalToolInputSchema(
+  CATALOG_SNAPSHOT_INPUT_PROPERTIES,
+  CATALOG_SNAPSHOT_BRANCHES,
+);
+const CATALOG_SAVED_SLICES_INPUT_SCHEMA = conditionalToolInputSchema(
+  CATALOG_SAVED_SLICES_INPUT_PROPERTIES,
+  CATALOG_SAVED_SLICES_BRANCHES,
+);
+const CONDITIONAL_TOOL_BRANCHES = new Map([
+  ['catalog_slice_snapshot', CATALOG_SNAPSHOT_BRANCHES],
+  ['catalog_slices_saved', CATALOG_SAVED_SLICES_BRANCHES],
+]);
+
 const PUBLIC_RECEIPT_REFERENCE_INPUT_SCHEMA = Object.freeze({
   type: 'object',
   additionalProperties: false,
@@ -366,26 +745,6 @@ const PUBLIC_RECEIPT_REFERENCE_INPUT_SCHEMA = Object.freeze({
   required: ['schemaVersion', 'publicReceiptId', 'kind', 'revision', 'issuedAt', 'sha256', 'canonicalPath'],
 });
 
-const SHARE_ARTIFACT_REF_INPUT_SCHEMA = Object.freeze({
-  oneOf: [
-    PUBLIC_RECEIPT_REFERENCE_INPUT_SCHEMA,
-    { type: 'object', additionalProperties: false, properties: { attemptId: { type: 'string', minLength: 1 } }, required: ['attemptId'] },
-    { type: 'object', additionalProperties: false, properties: { runId: { type: 'string', minLength: 1 } }, required: ['runId'] },
-    { type: 'object', additionalProperties: false, properties: { examId: { type: 'string', pattern: '^pex-[0-9a-f]{24}$' } }, required: ['examId'] },
-    {
-      type: 'object',
-      additionalProperties: false,
-      properties: {
-        probeSetRunId: { type: 'string', minLength: 1 },
-        evaluationId: { type: 'string', minLength: 1 },
-        visibility: { type: 'string', const: 'public' },
-      },
-      required: ['probeSetRunId', 'evaluationId', 'visibility'],
-    },
-  ],
-  description: 'Use the complete publicReceipt or impactPublicReceipt object returned by practice_run_report, publicReceipt from practice_run_impact, or one exact legacy reference: {attemptId}, {runId}, {examId}, or Gate {probeSetRunId,evaluationId,visibility:"public"}.',
-});
-
 const PRACTICE_STORE_ID_INPUT_SCHEMA = Object.freeze({
   type: 'string',
   minLength: 1,
@@ -455,8 +814,7 @@ const PRACTICE_RUN_EXTERNAL_AGENT_INPUT_SCHEMA = Object.freeze({
     name: { type: 'string', maxLength: 80 },
     source: { type: 'string', maxLength: 80 },
     version: { type: 'string', maxLength: 80 },
-    commitSha: { type: 'string', maxLength: 80, description: 'Declared source revision. Prefer this field over the legacy commit alias.' },
-    commit: { type: 'string', maxLength: 80, description: 'Legacy alias for commitSha.' },
+    commitSha: { type: 'string', maxLength: 80, description: 'Declared source revision.' },
     testCommand: { type: 'string', maxLength: 300 },
     ciStatus: { type: 'string', enum: ['unknown', 'passed', 'failed'] },
     examRole: { type: 'string', enum: ['candidate', 'negative-control'] },
@@ -493,6 +851,7 @@ const PRACTICE_RUN_UNTIL_INPUT_SCHEMA = Object.freeze({
         }, ['sku', 'threshold']),
         practiceRunUntilConditionInputSchema('order-recorded'),
         practiceRunUntilConditionInputSchema('return-recorded'),
+        practiceRunUntilConditionInputSchema('return-request-pending'),
         practiceRunUntilConditionInputSchema('incoming-inventory-landed', {
           sku: { type: 'string', minLength: 1, maxLength: 100 },
         }, ['sku']),
@@ -502,10 +861,27 @@ const PRACTICE_RUN_UNTIL_INPUT_SCHEMA = Object.freeze({
   required: ['schemaVersion', 'maxDays', 'condition'],
 });
 
+const PRACTICE_RUN_ADVANCE_CURSOR_INPUT_SCHEMA = Object.freeze({
+  type: 'object',
+  additionalProperties: false,
+  description: 'Copy this object unchanged from practiceRun.advanceCursor in the latest server response.',
+  properties: {
+    expectedDay: { type: 'integer', minimum: 0 },
+    expectedCallSeq: { type: 'integer', minimum: -1 },
+  },
+  required: ['expectedDay', 'expectedCallSeq'],
+});
+
 const SCHEMA_VALIDATED_TOOL_NAMES = new Set([
+  // MEG-1164: admin_schema publishes two exclusive modes, so the oneOf has to be enforced locally —
+  // otherwise an ambiguous call reaches the route instead of being corrected before transport.
+  'admin_schema',
+  'plan_validate',
   'get_connection_details',
+  'workspace_create',
   'practice_run_start',
   'practice_run_advance',
+  ...CONDITIONAL_TOOL_BRANCHES.keys(),
 ]);
 
 function schemaValidationError(schema, value, path = 'arguments') {
@@ -570,18 +946,32 @@ function schemaValidationError(schema, value, path = 'arguments') {
   return null;
 }
 
-const SHARE_CREATE_ARTIFACT_REF_NEXT_STEP = 'For a practice simulation receipt, call practice_run_report and pass its complete publicReceipt or impactPublicReceipt object unchanged; practice_run_impact returns its impact reference as publicReceipt. Other accepted artifactRef forms are receipt {attemptId}, history receipt {runId}, Shopify Exam {examId}, or Gate {probeSetRunId,evaluationId,visibility:"public"}. Correct the reference and retry share_create; no existing shareId is required.';
+function conditionalToolBranch(name, args) {
+  const branches = CONDITIONAL_TOOL_BRANCHES.get(name);
+  if (!branches) return null;
+  const matches = branches.filter((branch) => schemaValidationError(branch.schema, args) === null);
+  return matches.length === 1 ? matches[0] : null;
+}
 
-function requiredShareArtifact(args) {
-  const artifactType = requiredString(args, 'artifactType');
-  if (!['receipt', 'gate-evidence-export'].includes(artifactType)) {
-    throw new Error('artifactType must be receipt or gate-evidence-export');
-  }
-  const artifactRef = args?.artifactRef;
-  if (!artifactRef || typeof artifactRef !== 'object' || Array.isArray(artifactRef)) {
-    throw new Error(SHARE_CREATE_ARTIFACT_REF_NEXT_STEP);
-  }
-  return { artifactType, artifactRef };
+function conditionalToolFallbackBranch(name, args) {
+  const branches = CONDITIONAL_TOOL_BRANCHES.get(name);
+  if (!branches) return null;
+  const action = typeof args?.action === 'string' ? args.action : undefined;
+  return branches.find((candidate) => candidate.action === action)
+    ?? branches.find((candidate) => candidate.required.some((key) => args?.[key] !== undefined))
+    ?? branches[0];
+}
+
+export function toolInvocationMutates(name, args) {
+  if (!CONDITIONAL_TOOL_BRANCHES.has(name)) return TOOL_PRESENTATION[name]?.readOnlyHint === false;
+  const branch = conditionalToolBranch(name, args) ?? conditionalToolFallbackBranch(name, args);
+  return branch?.mutates === true;
+}
+
+function conditionalToolCorrection(name, args) {
+  const branch = conditionalToolFallbackBranch(name, args);
+  if (!branch) return null;
+  return `${name}(${JSON.stringify(branch.example)})`;
 }
 
 function queryPath(path, values) {
@@ -597,17 +987,8 @@ function requiredWorldId(args) {
   return validatedStoreId(requiredString(args, 'worldId'), 'worldId');
 }
 
-// MEG-256: `storeId` is the one canonical public practice-store identifier across the assistant
-// workflow (connection discovery → run start → receipt). `worldId` names the same identifier and
-// stays accepted as a bounded legacy alias so existing callers keep working.
 function requiredPracticeStoreId(args) {
-  const provided = ['storeId', 'worldId'].filter((key) => args?.[key] !== undefined && args?.[key] !== null);
-  if (provided.length === 0) throw new Error('storeId is required (worldId is accepted as a legacy alias for the same practice-store id)');
-  const canonical = requiredString(args, provided[0]);
-  if (provided.length === 2 && requiredString(args, provided[1]) !== canonical) {
-    throw new Error('storeId and worldId name the same practice store; they were both provided with different values');
-  }
-  return validatedStoreId(canonical, provided[0]);
+  return validatedStoreId(requiredString(args, 'storeId'), 'storeId');
 }
 
 function requiredPracticeAttemptId(args, key = 'attemptId') {
@@ -730,49 +1111,17 @@ function receiptProjection(value) {
   const practiceRun = attempt.practiceRun ?? value?.practiceRun ?? null;
   const calls = Array.isArray(value?.events?.calls) ? value.events.calls : [];
   const actions = Array.isArray(value?.events?.actions) ? value.events.actions : [];
-  const capabilityMatrix = value?.receiptEvidence?.assertionCapabilities;
-  const webhookCapability = capabilityMatrix?.schemaVersion === 'meguro.receipt-assertion-capabilities.v1'
-    && capabilityMatrix?.families?.webhook
-    && typeof capabilityMatrix.families.webhook === 'object'
-    ? capabilityMatrix.families.webhook
-    : null;
-  const assertions = Array.isArray(value?.receiptEvidence?.assertions)
-    ? value.receiptEvidence.assertions.slice(0, 50).map((assertion) => {
-      if (assertion?.category !== 'webhook') {
-        return { id: assertion.id, status: assertion.status, label: assertion.label };
-      }
-      if (webhookCapability?.availability === 'available') {
-        return { id: assertion.id, status: assertion.status, label: assertion.label, detail: assertion.detail };
-      }
-      if (webhookCapability?.availability === 'unavailable'
-        && webhookCapability.statusLabel === 'not available in this run mode'
-        && typeof webhookCapability.detail === 'string'
-        && webhookCapability.detail.trim()) {
-        return {
-          id: assertion.id,
-          status: webhookCapability.statusLabel,
-          label: assertion.label,
-          detail: webhookCapability.detail,
-        };
-      }
-      if (webhookCapability?.availability === 'unknown'
-        && webhookCapability.statusLabel === 'availability unknown'
-        && typeof webhookCapability.detail === 'string'
-        && webhookCapability.detail.trim()) {
-        return {
-          id: assertion.id,
-          status: webhookCapability.statusLabel,
-          label: assertion.label,
-          detail: webhookCapability.detail,
-        };
-      }
-      return {
-        id: assertion.id,
-        status: 'availability unknown',
-        label: assertion.label,
-        detail: 'Webhook assertion availability is unknown because this receipt has no capability metadata.',
-      };
-    })
+  const assertions = Array.isArray(value?.receiptEvidence?.effectiveAssertions)
+    ? value.receiptEvidence.effectiveAssertions.slice(0, 50).map((assertion) => ({
+      id: assertion.id,
+      status: assertion.statusLabel,
+      observedStatus: assertion.observedStatus,
+      evaluationSubject: assertion.evaluationSubject,
+      rejectionResponsibleLayers: assertion.rejectionResponsibleLayers ?? [],
+      ownershipStatement: assertion.ownershipStatement ?? null,
+      label: assertion.label,
+      detail: assertion.detail,
+    }))
     : [];
   const verdict = value?.report?.verdict && typeof value.report.verdict === 'object'
     ? Object.fromEntries(['status', 'outcome', 'grade', 'score', 'headline', 'horizonDays']
@@ -816,6 +1165,12 @@ function receiptProjection(value) {
   // disagree with the headline sitting beside it.
   const footprint = m?.footprint ?? null;
   const defaultVerdict = value?.defaultVerdict ?? value?.report?.defaultVerdict ?? value?.attempt?.defaultVerdict;
+  const resultSemantics = value?.resultSemantics ?? value?.report?.resultSemantics;
+  const gate = value?.gate ?? value?.report?.gate;
+  const rejectionAttribution = value?.rejectionAttribution ?? value?.report?.rejectionAttribution;
+  const reportBack = value?.reportBack ?? value?.report?.reportBack;
+  const takeHome = value?.takeHome ?? value?.report?.takeHome;
+  const eventResolution = value?.eventResolution ?? value?.report?.eventResolution;
   return secretSafe({
     schemaVersion: value?.schemaVersion,
     storeIdentity: value.storeIdentity,
@@ -835,8 +1190,16 @@ function receiptProjection(value) {
     receipt: {
       summary: value?.receiptEvidence?.summary,
       assertions,
+      ...(value?.receiptEvidence?.expectedRefusals ? { expectedRefusals: value.receiptEvidence.expectedRefusals } : {}),
     },
+    changes: Array.isArray(value?.changes) ? value.changes : [],
     ...(defaultVerdict && typeof defaultVerdict === 'object' ? { defaultVerdict } : {}),
+    ...(resultSemantics && typeof resultSemantics === 'object' ? { resultSemantics } : {}),
+    ...(gate && typeof gate === 'object' ? { gate } : {}),
+    ...(rejectionAttribution && typeof rejectionAttribution === 'object' ? { rejectionAttribution } : {}),
+    ...(reportBack?.schemaVersion === 'meguro.receipt-report-back.v1' ? { reportBack } : {}),
+    ...(takeHome?.schemaVersion === 'meguro.receipt-take-home.v1' ? { takeHome } : {}),
+    ...(eventResolution?.schemaVersion === 'meguro.template-event-resolution.v1' ? { eventResolution } : {}),
     ...(verdict ? { verdict } : {}),
     ...(measurement ? { measurement } : {}),
     ...(value?.publicReceipts?.run ? {
@@ -849,12 +1212,15 @@ function receiptProjection(value) {
 
 function runsListProjection(value, lifecycle) {
   const runs = Array.isArray(value?.runs) ? value.runs : [];
-  const visible = lifecycle ? runs.filter((run) => run?.status === lifecycle) : runs;
+  if (!Number.isSafeInteger(value?.total) || value.total < 0) {
+    throw new Error('Meguro runs response did not contain a valid total');
+  }
   return secretSafe({
     runFamily: 'Shopify dev-store history runs created by run_start.',
     excludes: 'Practice simulation attempts (pa-*) returned by practice_run_start are a separate family and are not included.',
     lifecycleFilter: lifecycle ?? 'all',
-    runs: visible.map((run) => {
+    total: value.total,
+    runs: runs.map((run) => {
       const {
         startedAt,
         updatedAt,
@@ -873,7 +1239,7 @@ function runsListProjection(value, lifecycle) {
         },
       };
     }),
-    ...(visible.length === 0 ? {
+    ...(runs.length === 0 ? {
       emptyState: {
         message: `No ${lifecycle ?? 'matching'} Shopify dev-store history runs were found. This says nothing about practice simulation attempts.`,
         practiceAttemptRecovery: 'Call practice_runs_list to discover practice simulation attempts, then pass one exact attemptId to practice_run_report or practice_run_impact.',
@@ -940,17 +1306,20 @@ function practiceRunReceiptStoreMismatch(receiptId, receiptStoreId, requestedSto
   };
 }
 
-function practiceRunsProjection(value, storeId, storeSelection) {
+function practiceRunsProjection(value, storeId, storeSelection, workspaceId) {
   const attempts = Array.isArray(value?.playbacks) ? value.playbacks : [];
+  if (!Number.isSafeInteger(value?.total) || value.total < 0) {
+    throw new Error('Meguro practice runs response did not contain a valid total');
+  }
   return secretSafe({
     schemaVersion: 'meguro.practice-run-list.v1',
     storeId,
     storeSelection,
+    total: value.total,
     attempts: attempts
-      .filter((attempt) => attempt?.storeId === storeId || attempt?.worldId === storeId)
       .map((attempt) => ({
         attemptId: attempt.attemptId,
-        state: attempt.status,
+        state: typeof attempt.practiceRun?.state === 'string' ? attempt.practiceRun.state : null,
         clock: {
           mode: attempt.clock?.mode ?? null,
           baselineDay: attempt.baselineDay ?? null,
@@ -959,7 +1328,10 @@ function practiceRunsProjection(value, storeId, storeSelection) {
           elapsedSimulationDays: attempt.elapsedSimulationDays ?? null,
           remainingSimulationDays: attempt.remainingSimulationDays ?? null,
         },
-        receiptRef: { attemptId: attempt.attemptId },
+        receiptRef: {
+          attemptId: attempt.attemptId,
+          ...(workspaceId ? { workspaceId } : {}),
+        },
       })),
   });
 }
@@ -975,8 +1347,10 @@ function practiceAttemptComparisonGuidanceFor(toolName, a, b) {
       type: 'text',
       text: JSON.stringify({
         code: 'practice-attempt-comparator-unavailable',
-        message: `${toolName} compares Shopify dev-store history runs created by run_start. A pa-* id names a practice simulation attempt, and Meguro has no cross-attempt comparator today.`,
+        message: `${toolName} compares history-run identities that are not exposed by hosted MCP. A pa-* id names a practice simulation attempt, and Meguro has no cross-attempt comparator today.`,
         attemptIds,
+        nextAction: calls.join('; '),
+        stopCondition: `Use the listed practice receipt reads instead. Do not retry ${toolName} with pa-* practice attempt ids.`,
         workingMethod: {
           calls,
           receiptFacts: 'Read both immutable run receipts and impact receipts. Align like-named impact effectLines by key, preserve each receipt moneyBasis, and subtract the recorded values only after checking the comparison basis below.',
@@ -1040,14 +1414,32 @@ function practiceRunsStoreNotFoundGuidance(storeId) {
   };
 }
 
+function workspaceLifecycleIdentityGuidance(toolName, workspaceId, message) {
+  const refusedId = typeof workspaceId === 'string' && workspaceId.trim()
+    ? JSON.stringify(workspaceId.trim())
+    : 'the missing workspaceId';
+  return withOperationCommitBoundary({
+    content: [{
+      type: 'text',
+      text: JSON.stringify({
+        code: 'workspace-id-invalid',
+        message: scrubString(message),
+        nextAction: `Call workspaces_list({}) and use an exact current workspaceId with ${toolName}.`,
+        stopCondition: `Do not retry ${toolName} with ${refusedId}; no workspace request was sent.`,
+      }, null, 2),
+    }],
+    isError: true,
+  }, 'pre-commit');
+}
+
 function legacyGateArtifactNotFoundGuidance(runId) {
   return {
     content: [{
       type: 'text',
       text: JSON.stringify({
         code: 'legacy-gate-artifact-not-found',
-        message: `No retained legacy Gate artifact exists for ${runId}. It is not a history-run id or pa-* practice simulation attempt id.`,
-        nextAction: 'Call gate_verdict({}) to read the latest Receipt Gate verdict.',
+        message: `No retained legacy Configured Receipt Gate artifact exists for ${runId}. It is not a history-run id or pa-* practice simulation attempt id.`,
+        nextAction: 'Call gate_verdict({}) to read the latest Configured Receipt Gate verdict.',
         stopCondition: `Do not retry ${JSON.stringify(runId)}. The legacy artifact cannot be created from a customer surface; stop after gate_verdict({}).`,
       }, null, 2),
     }],
@@ -1055,7 +1447,7 @@ function legacyGateArtifactNotFoundGuidance(runId) {
   };
 }
 
-function usageProjection(value) {
+function usageProjection(value, evaluatedRunStartEligibility) {
   const totalRuns = Number(value?.totalRuns ?? 0);
   const nonBillableRuns = Number(value?.nonBillableRuns ?? 0);
   const activityBillableRuns = Math.max(0, totalRuns - nonBillableRuns);
@@ -1066,6 +1458,17 @@ function usageProjection(value) {
   const activeStoreLimit = Number(meter.activeStoreLimit ?? 0);
   const activeWorkspaces = Number(meter.activeWorkspaces ?? 0);
   const activeWorkspaceLimit = Number(meter.activeWorkspaceLimit ?? 0);
+  const allowance = value?.runStartAllowance;
+  const hasDeclaredRunStartAllowance = allowance !== undefined;
+  if (hasDeclaredRunStartAllowance && (
+    !allowance
+    || typeof allowance !== 'object'
+    || allowance.schemaVersion !== 'meguro.run-start-allowance.v1'
+    || allowance.permitsChargedRun !== meter.runStartAllowed
+    || !['metering-allowance-available', 'metering-allowance-exhausted'].includes(allowance.reasonCode)
+    || allowance.meaning !== 'metering-allowance-only'
+    || allowance.detail !== 'Whether current tier metering allowance permits one charged simulation run; this is not overall store/root lifecycle eligibility.'
+  )) throw new Error('Meguro usage response carried inconsistent run-start allowance semantics');
   const activityCoverageComplete = value?.coverage?.complete === true;
   const activityMatchesMeter = activityCoverageComplete && activityBillableRuns === consumedSimulationRuns;
   const reconciliationStatus = !activityCoverageComplete
@@ -1107,17 +1510,23 @@ function usageProjection(value) {
       activeWorkspaces,
       activeWorkspaceLimit,
       runStartAllowed: meter.runStartAllowed,
+      runStartAllowedMeaning: allowance?.meaning ?? null,
+      runStartAllowance: allowance ?? null,
       enforcement: meter.enforcement,
     },
+    runStartEligibility: evaluatedRunStartEligibility ?? value?.runStartEligibility ?? null,
     coverage: value?.coverage ?? null,
+    trial: value?.trial ?? null,
   });
 }
 
 function twinDiffProjection(value) {
   if (!value || typeof value !== 'object') return secretSafe(value);
-  const { generatedAt, markdown: _markdown, ...impactReceipt } = value;
+  const { generatedAt, markdown: _markdown, pair, sources, ...impactReceipt } = value;
   return secretSafe({
     schemaVersion: 'meguro.mcp-twin-diff.v1',
+    pair,
+    sources,
     runClock: {
       generatedAtWallClock: generatedAt ?? null,
       note: 'This is when the impact receipt was generated; it is not Store-time.',
@@ -1129,6 +1538,34 @@ function twinDiffProjection(value) {
   });
 }
 
+function historyReadErrorResult(response) {
+  const body = response?.json && typeof response.json === 'object' ? response.json : {};
+  const unavailable = response?.status === 404;
+  const meaning = typeof body.message === 'string'
+    ? body.message
+    : unavailable
+      ? 'The requested history run is missing, expired, or not owned by this workspace.'
+      : 'The history read did not complete.';
+  const nextStep = typeof body.nextStep === 'string'
+    ? body.nextStep
+    : 'Call runs_list({ lifecycle: "completed" }) and use an exact available server-returned run ID.';
+  const stopCondition = typeof body.stopCondition === 'string'
+    ? body.stopCondition
+    : 'Stop if runs_list does not return the requested run or both roles of one available twinPair.';
+  const stable = {
+    httpStatus: response?.status,
+    code: typeof body.code === 'string'
+      ? body.code
+      : unavailable ? 'history-run-unavailable' : 'history-read-failed',
+    meaning,
+    nextStep,
+    stopCondition,
+    teaching: { meaning, nextStep, stopCondition },
+    ...(body.retention ? { retention: body.retention } : {}),
+  };
+  return { content: [{ type: 'text', text: JSON.stringify(secretSafe(stable), null, 2) }], isError: true };
+}
+
 const SHOPIFY_EXAM_ID = /^pex-[0-9a-f]{24}$/u;
 const SHOPIFY_DEV_DOMAIN = /^[a-z0-9][a-z0-9-]*\.myshopify\.com$/u;
 const SHOPIFY_EXAM_ACTIVE_STATUSES = new Set(['confirmed', 'materializing', 'replaying', 'comparing']);
@@ -1143,6 +1580,7 @@ const SHOPIFY_EXAM_ELIGIBILITY_GUIDANCE = Object.freeze({
   'temporal-clock-context-mismatch': 'Use the target practice store clock and rerun the bounded Exam source.',
   'temporal-clock-revision-mismatch': 'Capture one bounded burst at one Store-time coordinate; after advancing time, start a new practice run.',
   'interleaved-simulation-state-change': 'Rerun one bounded agent burst without stepping the store between captured calls.',
+  'target-preflight-unavailable': 'Use an exact connected Shopify development-store domain available to this workspace.',
 });
 
 function requiredExamId(args) {
@@ -1163,10 +1601,15 @@ function requiredShopifyDevDomain(args) {
 
 function examNextAction(exam, receipt) {
   const status = String(exam?.status ?? '');
-  if (SHOPIFY_EXAM_TERMINAL_STATUSES.has(status)) {
-    return status === 'completed'
-      ? { tool: 'exam_report', args: { examId: exam.examId }, reason: 'exam-complete' }
-      : { tool: 'exam_report', args: { examId: exam.examId }, reason: `exam-${status}` };
+  if (status === 'cleaned' || status === 'failed') {
+    return { tool: 'exam_report', args: { examId: exam.examId }, reason: `exam-${status}` };
+  }
+  if (status === 'completed') {
+    return {
+      tool: 'exam_start',
+      args: { attemptId: exam.attemptId, shopDomain: exam.shopDomain },
+      reason: 'cleanup-required',
+    };
   }
   if (status === 'blocked') {
     if (receipt?.privateAvailable === true && receipt?.publicAvailable === true) {
@@ -1175,7 +1618,11 @@ function examNextAction(exam, receipt) {
     return { tool: 'exam_preflight', args: { attemptId: exam.attemptId, shopDomain: exam.shopDomain }, reason: 'preview-blocked' };
   }
   if (status === 'cleaning') {
-    return { tool: 'exam_status', args: { examId: exam.examId }, reason: 'cleanup-in-progress' };
+    return {
+      tool: 'exam_start',
+      args: { attemptId: exam.attemptId, shopDomain: exam.shopDomain },
+      reason: 'cleanup-checkpoint-complete',
+    };
   }
   return {
     tool: 'exam_start',
@@ -1247,6 +1694,7 @@ export function createTools(config) {
     const headers = { accept: 'application/json' };
     const needsControlCredential = Boolean(options.auth || method !== 'GET');
     if (needsControlCredential) Object.assign(headers, controlAuthHeaders());
+    if (options.workspaceId) headers['x-meguro-workspace'] = options.workspaceId;
     if (method !== 'GET') {
       headers['content-type'] = 'application/json';
     }
@@ -1264,7 +1712,11 @@ export function createTools(config) {
       const authenticationError = authenticationErrorResult(response.status, json);
       if (authenticationError) throw new ToolResultError(authenticationError);
       const message = json.errors?.[0]?.message ?? json.error ?? text.slice(0, 300);
-      throw new Error(`${response.status} ${path}: ${message}`);
+      const failure = new Error(`${response.status} ${path}: ${message}`);
+      // MEG-1054: the control plane is the authority on what a failed mutation did to committed
+      // state. Carry the classification it declared instead of re-deriving one at this boundary.
+      if (typeof json.operationCommitBoundary === 'string') failure.operationCommitBoundary = json.operationCommitBoundary;
+      throw failure;
     }
     return json;
   }
@@ -1275,7 +1727,10 @@ export function createTools(config) {
     const headers = { accept: 'application/json', ...controlAuthHeaders() };
     if (options.workspaceId) headers['x-meguro-workspace'] = options.workspaceId;
     if (method !== 'GET') headers['content-type'] = 'application/json';
-    const response = await fetchImpl(`${apiBaseUrl}${path}`, {
+    const bust = method === 'GET' && options.cacheBustRead === true
+      ? `${path.includes('?') ? '&' : '?'}_=${Date.now()}`
+      : '';
+    const response = await fetchImpl(`${apiBaseUrl}${path}${bust}`, {
       method,
       headers,
       ...(body ? { body: JSON.stringify(body) } : {}),
@@ -1326,12 +1781,47 @@ export function createTools(config) {
     return { schemaVersion: 'meguro.support-code.v1', buildSha, requestIds: [safeRequestId], occurredAt, route: path, line };
   }
 
-  async function fleetErrorResult(toolName, path, status, value, requestId) {
+  function supportRouteForFleetFailure(toolName, path) {
+    if (toolName === 'catalog_slice_read') return '/stores/{shopDomain}/catalog-slice';
+    if (toolName === 'catalog_slice_snapshot' && /^\/stores\/[^/]+\/catalog-slice\/snapshot(?:\?|$)/u.test(path)) {
+      return '/stores/{shopDomain}/catalog-slice/snapshot';
+    }
+    if (toolName === 'catalog_slices_saved' && /^\/stores\/[^/]+\/catalog-slices(?:\?|$)/u.test(path)) {
+      return '/stores/{shopDomain}/catalog-slices';
+    }
+    return path;
+  }
+
+  function catalogConnectionTeaching(toolName, path, allowedShopDomains, hasAllowedShopDomainAuthority) {
+    if (!hasAllowedShopDomainAuthority) return null;
+    const liveCatalogStoreAction = toolName === 'catalog_slice_read'
+      || (toolName === 'catalog_slice_snapshot' && /^\/stores\/[^/]+\/catalog-slice\/snapshot(?:\?|$)/u.test(path))
+      || (toolName === 'catalog_slices_saved' && /^\/stores\/[^/]+\/catalog-slices(?:\?|$)/u.test(path));
+    if (!liveCatalogStoreAction) return null;
+    if (!allowedShopDomains.length) {
+      return {
+        meaning: 'No catalog-readable Shopify development-store domain is connected for this workspace, so the requested operation was not applied.',
+        nextStep: `The allowedShopDomains field below is empty. Stop: no catalog-readable Shopify development-store domain is connected; connect one in Console before trying ${toolName} again.`,
+      };
+    }
+    return {
+      meaning: 'The requested Shopify development-store domain is not connected or allowed for this workspace, so the requested operation was not applied.',
+      nextStep: toolName === 'catalog_slice_read'
+        ? `The allowedShopDomains field below is the authoritative connected-domain discovery result. Call catalog_slice_read({ shopDomain: ${JSON.stringify(allowedShopDomains[0])} }) with one exact value from that field. Do not retry the refused domain.`
+        : `The allowedShopDomains field below is the authoritative connected-domain discovery result. Call ${toolName} again with shopDomain: ${JSON.stringify(allowedShopDomains[0])} and the same valid non-domain arguments. Do not retry the refused domain.`,
+    };
+  }
+
+  async function fleetErrorResult(toolName, path, status, value, requestId, invocationMutates) {
     const body = value && typeof value === 'object' ? value : {};
+    const declaredBoundary = ['pre-commit', 'committed', 'unknown'].includes(body.operationCommitBoundary)
+      ? body.operationCommitBoundary
+      : null;
     const sourceErrors = Array.isArray(body.errors) ? body.errors.slice(0, 5) : [];
     const allowedShopDomains = Array.isArray(body.allowed)
       ? [...new Set(body.allowed.map((domain) => String(domain).trim().toLowerCase()).filter((domain) => SHOPIFY_DEV_DOMAIN.test(domain)))]
       : [];
+    const catalogConnection = catalogConnectionTeaching(toolName, path, allowedShopDomains, Array.isArray(body.allowed));
     const workspaceLimit = body.code === 'active_workspace_limit_reached';
     const rawError = typeof body.error === 'string' ? body.error : '';
     const routeCode = typeof body.code === 'string'
@@ -1343,31 +1833,80 @@ export function createTools(config) {
     const claimCodeError = toolName === 'store_claim_by_code'
       && ['invalid-claim-code', 'claim-code-unavailable', 'claim-code-busy'].includes(routeCode);
     const sourceErrorText = sourceErrors.map((error) => String(error?.message ?? '')).join(' ');
-    const resourceTeaching = (toolName === 'workspace_archive' || toolName === 'workspace_unarchive') && status === 404
+    const settledFleetMutation = new Set([
+      'store_create',
+      'store_delete',
+      'workspace_create',
+      'workspace_archive',
+      'workspace_unarchive',
+      'store_claim_by_code',
+    ]);
+    const settledPreCommitRefusal = status >= 400 && status < 500
+      && settledFleetMutation.has(toolName);
+    // These route/code pairs are authority-bearing pre-write refusals: template resolution,
+    // target lookup, and claim-code resolution all finish before their write-capable phase. A
+    // transport failure or any unrecognized response remains undeclared and reaches the hosted
+    // resource's single `unknown` fallback.
+    const authoritativeBoundary = declaredBoundary ?? (settledPreCommitRefusal ? 'pre-commit' : null);
+    const effectiveBoundary = authoritativeBoundary ?? (invocationMutates ? 'unknown' : null);
+    const hasInvocationBoundaryAuthority = invocationMutates !== undefined || authoritativeBoundary !== null;
+    const operationMeaning = effectiveBoundary === 'pre-commit'
+      ? 'The requested fleet operation was not applied.'
+      : effectiveBoundary === 'committed'
+        ? 'The requested fleet operation applied to committed state, but the response did not complete.'
+        : effectiveBoundary === 'unknown'
+          ? 'The requested fleet operation did not complete with a confirmed commit outcome.'
+          : invocationMutates === false
+            ? 'The requested fleet read did not complete.'
+            : 'The requested fleet operation was not applied.';
+    const workspaceLifecycleTool = toolName === 'workspace_archive' || toolName === 'workspace_unarchive';
+    const resourceTeaching = toolName === 'workspace_archive' && status === 400 && routeCode === 'default-workspace'
+      ? {
+          meaning: 'The default workspace cannot be archived. The requested lifecycle operation was not applied.',
+          nextStep: 'Call workspaces_list({}), select an active workspace with isDefault: false, then call workspace_archive({ workspaceId: "<exact active non-default workspaceId>" }). If no active non-default workspace exists, stop and do not retry the default workspaceId.',
+        }
+      : workspaceLifecycleTool && status === 409 && routeCode === 'workspace-deleting'
+        ? {
+            meaning: 'The workspace lifecycle transition is already underway. Do not retry the mutation.',
+            nextStep: `Wait for the lifecycle transition to finish, then call workspaces_list({}) to read the terminal workspace state. Stop and do not retry ${toolName} while the workspace is deleting.`,
+          }
+      : workspaceLifecycleTool && status === 404
       ? {
           meaning: 'The requested workspace is not available in this account. Workspace lifecycle tools require a workspaceId; a storeId names a different resource and is never a substitute.',
           nextStep: `Call workspaces_list({}), choose an exact workspaceId from the returned account workspaces, then retry ${toolName}({ workspaceId: "<exact workspaceId>" }). If the intended workspace is absent, stop and do not retry.`,
         }
+      : toolName === 'template_get' && status === 404
+        ? {
+            // MEG-1058: templates_list is the complete catalog, so an unknown key is settled, not
+            // transient. Teach the discovery step and stop rather than inviting a retry.
+            meaning: 'The requested templateKey is not in the authoritative practice-store template catalog.',
+            nextStep: 'Call templates_list({}), choose an exact key from the returned storeTemplates, then call template_get({ templateKey: "<exact key>" }). If the intended template is absent, stop and do not retry the same key.',
+          }
       : toolName === 'store_create' && status === 400 && /template/iu.test(`${rawError} ${routeMessage ?? ''} ${sourceErrorText}`)
         ? {
             meaning: 'The requested templateKey is not in the authoritative practice-store template catalog.',
             nextStep: 'Call templates_list({}), choose an exact key from the returned storeTemplates, then call store_create({ templateKey: "<exact key>" }). If the catalog is empty or the intended template is absent, stop and do not retry.',
           }
-        : null;
+      : toolName === 'catalog_slice_snapshot' && status === 404
+          && /^\/catalog-slices\/[^/]+\/snapshot(?:\?|$)/u.test(path)
+        ? {
+            meaning: 'The requested saved catalog slice is not in the current workspace.',
+            nextStep: 'Call catalog_slices_saved({ action: "list" }), choose an exact sliceId from that result, and retry only the failed action. If the intended slice is absent, stop and do not retry the unavailable sliceId.',
+          }
+      : toolName === 'catalog_slices_saved' && status === 404
+        ? {
+            meaning: 'The requested saved catalog slice is not in the current workspace.',
+            nextStep: 'Call catalog_slices_saved({ action: "list" }), choose an exact sliceId from that result, and retry only the failed action. If the intended slice is absent, stop and do not retry the unavailable sliceId.',
+          }
+      : null;
     const defaultNextStep = resourceTeaching
       ? resourceTeaching.nextStep
       : claimCodeError
       ? routeCode === 'claim-code-busy'
         ? 'Wait for the current connection update to finish, then reopen Meguro in Shopify Admin before retrying once.'
         : 'Reopen Meguro in Shopify Admin and use the current one-time claim code shown for the intended development store.'
-      : toolName === 'share_create'
-        ? SHARE_CREATE_ARTIFACT_REF_NEXT_STEP
-        : toolName.startsWith('share_') || toolName === 'shares_list'
-        ? 'Call shares_list or share_status, inspect the current private/outward lifecycle state, and retry only the permitted transition.'
-        : toolName === 'catalog_slice_read'
-          ? allowedShopDomains.length
-            ? `The allowedShopDomains field below is the authoritative connected-domain discovery result. Call catalog_slice_read({ shopDomain: ${JSON.stringify(allowedShopDomains[0])} }) with one exact value from that field. Do not retry the refused domain.`
-            : 'The allowedShopDomains field below is empty. Stop: no catalog-readable Shopify development-store domain is connected; connect one in Console before trying catalog_slice_read again.'
+      : toolName === 'catalog_slice_read'
+          ? catalogConnection?.nextStep ?? 'Read the current catalog slice or saved-slice state, correct the exact store, slice, or variant ids, and retry only the failed action.'
           : toolName.startsWith('catalog_')
             ? 'Read the current catalog slice or saved-slice state, correct the exact store, slice, or variant ids, and retry only the failed action.'
           : toolName === 'store_claim'
@@ -1375,47 +1914,51 @@ export function createTools(config) {
             : 'Call stores_list, inspect the current fleet, and retry with a current store id.';
     const errors = sourceErrors.length ? sourceErrors.map((error) => ({
       message: scrubString(error?.message ?? 'Meguro fleet request failed.'),
-      meaning: scrubString(resourceTeaching?.meaning ?? error?.meaning ?? 'The requested fleet operation was not applied.'),
-      nextStep: scrubString(resourceTeaching?.nextStep ?? error?.nextStep ?? defaultNextStep),
+      meaning: scrubString(resourceTeaching?.meaning
+        ?? catalogConnection?.meaning
+        ?? (hasInvocationBoundaryAuthority ? operationMeaning : error?.meaning ?? operationMeaning)),
+      nextStep: scrubString(resourceTeaching?.nextStep ?? catalogConnection?.nextStep ?? error?.nextStep ?? defaultNextStep),
     })) : [{
       message: scrubString(routeMessage ?? (typeof value === 'string' ? value : 'Meguro fleet request failed.')),
       meaning: resourceTeaching
         ? resourceTeaching.meaning
+        : catalogConnection
+          ? catalogConnection.meaning
         : workspaceLimit
         ? 'The account is at its active-workspace limit, so the requested workspace operation was not applied.'
         : claimCodeError
           ? 'The one-time Shopify development-store claim was not applied.'
-        : 'The requested fleet operation was not applied.',
+        : operationMeaning,
       nextStep: resourceTeaching
         ? resourceTeaching.nextStep
+        : catalogConnection
+          ? catalogConnection.nextStep
         : workspaceLimit
-        ? 'Archive an active workspace or open Plans & Billing at #upgrade.'
+        ? String(body.sameTierAction?.label ?? routeMessage ?? defaultNextStep)
         : defaultNextStep,
     }];
     const stable = secretSafe({
       tool: toolName,
       httpStatus: status,
       ...(routeCode ? { code: routeCode } : {}),
-      ...(typeof body.blockedCapability === 'string' ? { blockedCapability: body.blockedCapability } : {}),
-      ...(typeof body.tier === 'string' ? { tier: body.tier } : {}),
+      ...enforcementProjection(body),
       ...(Number.isFinite(body.activeStores) ? { activeStores: body.activeStores } : {}),
       ...(Number.isFinite(body.activeStoreLimit) ? { activeStoreLimit: body.activeStoreLimit } : {}),
       ...(Number.isFinite(body.activeWorkspaces) ? { activeWorkspaces: body.activeWorkspaces } : {}),
       ...(Number.isFinite(body.activeWorkspaceLimit) ? { activeWorkspaceLimit: body.activeWorkspaceLimit } : {}),
-      ...(typeof body.upgradePath === 'string' ? { upgradePath: body.upgradePath } : {}),
       errors,
-      ...(toolName === 'catalog_slice_read' ? { allowedShopDomains } : {}),
+      ...(catalogConnection ? { allowedShopDomains } : {}),
       ...(Array.isArray(body.fleet) ? { fleet: body.fleet } : {}),
-      supportCode: await fleetSupportCode(path, requestId),
+      supportCode: await fleetSupportCode(supportRouteForFleetFailure(toolName, path), requestId),
     });
-    return { content: [{ type: 'text', text: JSON.stringify(stable, null, 2) }], isError: true };
+    const result = { content: [{ type: 'text', text: JSON.stringify(stable, null, 2) }], isError: true };
+    return authoritativeBoundary ? withOperationCommitBoundary(result, authoritativeBoundary) : result;
   }
 
   async function historyRunTeachingErrorResult(toolName, path, response, requestedId) {
     const body = response.json && typeof response.json === 'object' ? response.json : {};
     const rawMessage = String(body.errors?.[0]?.message ?? body.error ?? body.message ?? 'Meguro history-run request failed.');
     if (toolName === 'run_start' && response.status === 400 && /not allowed|not connected/iu.test(rawMessage)) {
-      const requestedDomain = String(body.requestedShopDomain ?? requestedId ?? '').trim().toLowerCase();
       const allowedShopDomains = Array.isArray(body.allowed)
         ? [...new Set(body.allowed.map((domain) => String(domain).trim().toLowerCase()).filter((domain) => SHOPIFY_DEV_DOMAIN.test(domain)))]
         : [];
@@ -1428,10 +1971,10 @@ export function createTools(config) {
         error: { message: rawMessage },
         allowedShopDomains,
         teaching: {
-          meaning: `${requestedDomain || 'The requested shop domain'} is not connected or allowed for this account, so no Shopify dev-store history run was started.`,
+          meaning: 'The requested shop domain is not connected or allowed for this account, so no Shopify dev-store history run was started.',
           nextStep,
           stopCondition: allowedShopDomains.length
-            ? `Do not retry ${requestedDomain || 'the refused domain'}; use only an exact value from allowedShopDomains.`
+            ? 'Do not retry the refused domain; use only an exact value from allowedShopDomains.'
             : 'Stop until Console exposes a connected Shopify development-store domain.',
         },
         supportCode: await fleetSupportCode(path, response.requestId),
@@ -1459,14 +2002,22 @@ export function createTools(config) {
     const response = await apiRaw(method, path, body, options);
     if (!response.ok) {
       const authenticationError = authenticationErrorResult(response.status, response.json);
-      return { error: authenticationError ?? await fleetErrorResult(toolName, path, response.status, response.json, response.requestId) };
+      return { error: authenticationError ?? await fleetErrorResult(
+        toolName,
+        path,
+        response.status,
+        response.json,
+        response.requestId,
+        options.invocationMutates,
+      ) };
     }
     return { value: response.json };
   }
 
-  async function practiceApi(method, path, body) {
+  async function practiceApi(method, path, body, options = {}) {
     if (!practiceApiToken) throw new Error('MEGURO_API_TOKEN is required for practice-run tools');
     const headers = { accept: 'application/json', authorization: `Bearer ${practiceApiToken}` };
+    if (options.workspaceId) headers['x-meguro-workspace'] = options.workspaceId;
     if (method !== 'GET') headers['content-type'] = 'application/json';
     let response;
     try {
@@ -1486,23 +2037,20 @@ export function createTools(config) {
     return { ok: response.ok, status: response.status, json, retryAfterSeconds };
   }
 
-  async function examEligibility(attemptId) {
-    const response = await practiceApi('GET', `/practice/playbacks/${encodeURIComponent(attemptId)}/report`);
-    const attempt = response.json?.attempt ?? response.json?.report?.attempt;
-    const eligibility = response.ok
-      ? attempt?.practiceExamEligibility
-      : null;
-    if (!response.ok || !eligibility || typeof eligibility !== 'object') {
+  function examEligibility(source) {
+    if (source.code !== 'exam-ineligible') return null;
+    const codes = Array.isArray(source.blockerCodes)
+      ? source.blockerCodes.map(String)
+      : typeof source.blockerCode === 'string' ? [source.blockerCode] : [];
+    if (source.retryable === true && codes.length === 0) {
       return {
         state: 'undetermined',
-        codes: [],
+        codes,
         retryable: true,
         nextStep: 'Eligibility evidence is undetermined, not negative. Retry preflight; if the evidence read remains unavailable, use the support code.',
       };
     }
-    const codes = Array.isArray(eligibility.codes) ? eligibility.codes.map(String) : [];
     const steps = [...new Set(codes.map((code) => SHOPIFY_EXAM_ELIGIBILITY_GUIDANCE[code]).filter(Boolean))];
-    const storeId = String(attempt?.storeId ?? attempt?.worldId ?? '').trim();
     const mustRecapture = codes.some((code) => [
       'tape-missing',
       'tape-total-over-limit',
@@ -1514,11 +2062,9 @@ export function createTools(config) {
       'temporal-clock-revision-mismatch',
       'interleaved-simulation-state-change',
     ].includes(code));
-    const recaptureStep = `This immutable attempt is ineligible and cannot be repaired. Do not retry this immutable attempt. Call practice_run_start({ storeId: ${JSON.stringify(storeId || '<same practice-store id>')} }) to create a new simulation attempt; run one bounded capture through the current Connect or package-free CI path using Shopify Admin API 2026-04 at one Store-time coordinate without advancing the store between captured calls; finish it; then call exam_preflight with the new attemptId and exact connected development-store domain.`;
+    const recaptureStep = 'This immutable attempt is ineligible and cannot be repaired. Do not retry this immutable attempt. Call practice_run_start for the same practice store to create a new simulation attempt; run one bounded capture through the current Connect or package-free CI path using Shopify Admin API 2026-04 at one Store-time coordinate without advancing the store between captured calls; finish it; then call exam_preflight with the new attemptId and exact connected development-store domain.';
     return {
-      state: eligibility.eligible === true && codes.length === 0 ? 'eligible' : 'blocked',
-      schemaVersion: eligibility.schemaVersion,
-      replayDisposition: eligibility.replayDisposition,
+      state: 'blocked',
       codes,
       retryable: false,
       nextStep: mustRecapture
@@ -1533,20 +2079,23 @@ export function createTools(config) {
     const source = response.json?.examError && typeof response.json.examError === 'object'
       ? response.json.examError
       : { code: 'exam-request-failed', message: 'The Shopify Exam request failed safely.', retryable: response.status >= 500 };
-    const eligibility = source.code === 'exam-ineligible' && attemptId
-      ? await examEligibility(attemptId)
-      : null;
-    const retryable = eligibility?.state === 'undetermined'
-      ? true
-      : source.retryable === true;
+    const eligibility = examEligibility(source);
+    const retryable = source.retryable === true;
     const startPairNotFound = toolName === 'exam_start' && source.code === 'not_found';
-    const nextStep = startPairNotFound
+    const preflightPairNotFound = toolName === 'exam_preflight' && source.code === 'not_found';
+    const examIdentityNotFound = (toolName === 'exam_status' || toolName === 'exam_report')
+      && source.code === 'not_found';
+    const nextStep = startPairNotFound || preflightPairNotFound
       ? 'Use a completed attemptId returned by practice_run_start and the exact connected .myshopify.com domain shown in Console. Call exam_preflight({ attemptId: "<completed attemptId>", shopDomain: "<exact connected .myshopify.com domain>" }); only when it reports eligible, call exam_start({ attemptId: "<same completed attemptId>", shopDomain: "<same exact connected .myshopify.com domain>" }).'
+      : examIdentityNotFound
+        ? 'Call practice_runs_list({}), choose a completed attemptId, call exam_preflight with that attemptId and an exact connected .myshopify.com domain, then call exam_start. Use only the examId returned by exam_start with this tool.'
       : eligibility?.nextStep
       ?? (retryable
-        ? 'Read exam_status before retrying so an ambiguous delivery is never replayed blindly.'
+        ? toolName === 'exam_preflight'
+          ? 'Retry exam_preflight with the same attemptId and shopDomain after the transient condition clears. Preflight creates no Exam identity; do not call exam_status unless exam_start later returns an examId.'
+          : 'Read exam_status before retrying so an ambiguous delivery is never replayed blindly.'
         : 'Correct the stated Exam requirement, then retry only the failed bounded step.');
-    return {
+    const result = {
       content: [{
         type: 'text',
         text: JSON.stringify(secretSafe({
@@ -1560,19 +2109,28 @@ export function createTools(config) {
             codes: eligibility.codes,
           } } : {}),
           teaching: {
-            meaning: startPairNotFound
+            meaning: startPairNotFound || preflightPairNotFound
               ? 'This tenant-safe not-found refusal means the requested practice attempt and connected development-store domain pair is unavailable to this account; Meguro does not reveal which member of the pair was absent.'
+              : examIdentityNotFound
+                ? 'No Shopify Exam with this examId is available to this account. Exam identities are created only by exam_start.'
               : source.code === 'exam-ineligible'
               ? 'Shopify Exam accepts only a completed, graded, immutable captured attempt whose replay evidence is current and supported.'
               : 'The requested bounded Shopify Exam step was not assumed complete.',
             nextStep,
-            ...(startPairNotFound ? { stopCondition: 'If a completed attemptId or exact connected domain is unavailable, stop. Do not retry exam_start with the refused pair.' } : {}),
+            ...(startPairNotFound || preflightPairNotFound
+              ? { stopCondition: `If a completed attemptId or exact connected domain is unavailable, stop. Do not retry ${toolName} with the refused pair.` }
+              : examIdentityNotFound
+                ? { stopCondition: `If exam_start did not return this examId, stop. Do not retry ${toolName} with the unavailable examId.` }
+                : {}),
           },
           supportCode: await fleetSupportCode(path, response.requestId),
         }), null, 2),
       }],
       isError: true,
     };
+    return startPairNotFound || preflightPairNotFound
+      ? withOperationCommitBoundary(result, 'pre-commit')
+      : result;
   }
 
   async function examRequest(toolName, method, path, body, attemptId) {
@@ -1655,8 +2213,13 @@ export function createTools(config) {
             description: DOCUMENTATION_TOOL_CONTRACT.topicDescription,
           },
           version: {
-            type: 'integer',
-            enum: DOCUMENTATION_TOOL_CONTRACT.versions,
+            // MEG-1059: an exact published integer, or the "latest" sentinel. The historical enum is
+            // withdrawn — it grew with every mint and told a caller nothing about which topic
+            // publishes which version.
+            anyOf: [
+              { type: 'integer', minimum: 1 },
+              { type: 'string', enum: ['latest'] },
+            ],
             description: DOCUMENTATION_TOOL_CONTRACT.versionDescription,
           },
         },
@@ -1665,7 +2228,7 @@ export function createTools(config) {
     },
     {
       name: 'templates_list',
-      description: 'List the full ordered, public-safe practice-store template catalog available to store_create; it is not filtered by stores already in the fleet. starterRecommendation names the template keys recommended for a first simulation and declares that basis as starter-for-first-simulation; the matching recommended boolean marks those templates. recommendedRunDays is each template\'s recommended simulation length. The response is derived only from the bounded storeTemplates projection: it excludes customer profiles, scenario presets, credentials, and private route payload. An OAuth grant may select an owned non-default workspace; an API key remains bound to its own workspace.',
+      description: 'List the complete ordered, public-safe practice-store template catalog available to store_create; it is not filtered by stores already in the fleet. Each row carries only what a cold agent needs to choose — key, label, category, recommended, bestFor and recommendedRunDays. Call template_get({ templateKey }) for one template\'s complete record: supported reads and writes, operation contracts, unsupported contracts, capability boundaries, modeled evidence and physics, and rubric fields. starterRecommendation names every server-recommended template and provides a server-owned starterPlans entry for every selectable template. Each plan states the authenticated account tier, ideal horizon, exact first practice_run_start clock, run-start availability, and continuation. While the one account onboarding grant is available, every template is recommendable and its plan carries that authorization; afterward the same plans apply ordinary tier policy. If no executable recommendation is available, the catalog remains complete and starterRecommendation.recommendationUnavailable explains why. The matching recommended boolean follows the server declaration, and recommendedRunDays remains each template\'s ideal simulation length. The response excludes customer profiles, scenario presets, credentials, and private route payload. An OAuth grant may select an owned non-default workspace; an API key remains bound to its own workspace.',
       inputSchema: {
         type: 'object',
         additionalProperties: false,
@@ -1675,6 +2238,19 @@ export function createTools(config) {
         required: [],
       },
     },
+    {
+      name: 'template_get',
+      description: 'Read the complete public-safe record for exactly one practice-store template: the compact catalog fields plus what the agent sees, timing, supported reads and writes, modeled evidence and physics, operation contracts, unsupported contracts, capability boundaries, and rubric fields. templates_list is the discovery step and carries only the fields needed to choose; this is the detail step and carries everything needed to use the chosen template. Both are projected from the same compiled catalog authority. An unknown templateKey returns a typed not-found response naming templates_list; it creates nothing and is never worth retrying with the same key. The response excludes customer profiles, scenario presets, credentials, and private route payload. An OAuth grant may select an owned non-default workspace; an API key remains bound to its own workspace.',
+      inputSchema: {
+        type: 'object',
+        additionalProperties: false,
+        properties: {
+          templateKey: { type: 'string', minLength: 1, description: 'Exact template key from templates_list storeTemplates[].key.' },
+          workspaceId: { type: 'string', minLength: 1, description: 'Optional OAuth selector for an account-owned non-default workspace. A workspace API key may omit it or repeat only its own binding.' },
+        },
+        required: ['templateKey'],
+      },
+    },
     {
       name: 'stores_list',
       description: 'List one workspace\'s practice-store fleet with ids, names, templates, generated-history span, readiness, active-run state, and deletion context. An OAuth grant is account-bound: omit workspaceId for the default workspace or provide an owned non-default workspace id. An API key remains bound to its own workspace.',
@@ -1688,7 +2264,7 @@ export function createTools(config) {
     },
     {
       name: 'store_create',
-      description: 'Create a populated practice store from any templateKey returned by templates_list, including a template already represented in the fleet, in the selected workspace. An OAuth grant is account-bound: omit workspaceId for the default workspace or provide an owned non-default workspace id. An API key remains bound to its own workspace. At the active-store limit, the server teaching error includes the current fleet.',
+      description: 'Create a populated practice store from any templateKey returned by templates_list, including a template already represented in the fleet, in the selected workspace. The server gives ordinary stores 120 days of queryable history by default. An OAuth grant is account-bound: omit workspaceId for the default workspace or provide an owned non-default workspace id. An API key remains bound to its own workspace. At the active-store limit, the server teaching error includes the current fleet.',
       inputSchema: {
         type: 'object', additionalProperties: false,
         properties: {
@@ -1762,70 +2338,6 @@ export function createTools(config) {
         required: ['workspaceId'],
       },
     },
-    {
-      name: 'share_create',
-      description: 'Create a private evidence-share draft, or update its title/client-viewer audience while it remains draft or changes-requested. For a practice simulation receipt, pass the complete publicReceipt or impactPublicReceipt object from practice_run_report unchanged as artifactRef; practice_run_impact returns its impact reference as publicReceipt. The schema also names every legacy receipt, Shopify Exam, and Gate reference form. This owner-only OAuth tool does not expose evidence by itself: call share_publish for the outward-facing transition. Omit shareId to create with title, artifactType, artifactRef, and audienceUserIds; provide shareId to update only title and/or audienceUserIds. OAuth may select an owned workspace.',
-      inputSchema: {
-        type: 'object', additionalProperties: false,
-        properties: {
-          workspaceId: { type: 'string', minLength: 1, description: 'Optional account-owned workspace selector. Omit for Default.' },
-          shareId: { type: 'string', pattern: '^[0-9a-f]{32}$', description: 'Existing draft/changes-requested share to update. Omit to create.' },
-          title: { type: 'string', minLength: 1, maxLength: 120 },
-          artifactType: { type: 'string', enum: ['receipt', 'gate-evidence-export'], description: 'Required only when creating.' },
-          artifactRef: SHARE_ARTIFACT_REF_INPUT_SCHEMA,
-          audienceUserIds: { type: 'array', maxItems: 40, items: { type: 'string', minLength: 1 }, description: 'Active client-viewer user ids assigned to this exact workspace.' },
-        },
-        required: [],
-      },
-    },
-    {
-      name: 'shares_list',
-      description: 'List private and outward evidence-share lifecycle rows in the selected workspace. This owner-only OAuth read does not expose evidence or mint viewer access. Use share_status for the exact artifact reference and audience ids.',
-      inputSchema: {
-        type: 'object', additionalProperties: false,
-        properties: {
-          workspaceId: { type: 'string', minLength: 1, description: 'Optional account-owned workspace selector. Omit for Default.' },
-        },
-        required: [],
-      },
-    },
-    {
-      name: 'share_status',
-      description: 'Read one exact evidence share, including its immutable public artifact reference, selected client-viewer ids, state, and revocation status. This owner-only OAuth read has no outward effect.',
-      inputSchema: {
-        type: 'object', additionalProperties: false,
-        properties: {
-          workspaceId: { type: 'string', minLength: 1, description: 'Optional account-owned workspace selector. Omit for Default.' },
-          shareId: { type: 'string', pattern: '^[0-9a-f]{32}$', description: 'Exact share id from shares_list.' },
-        },
-        required: ['shareId'],
-      },
-    },
-    {
-      name: 'share_publish',
-      description: 'Outward-facing action: publish exposes the share artifact to its selected client viewers; re-share refreshes that exposure after a viewer requested changes. This is not a private action. Use action=publish only for a draft, or action=re-share only after share_status reports changes-requested.',
-      inputSchema: {
-        type: 'object', additionalProperties: false,
-        properties: {
-          workspaceId: { type: 'string', minLength: 1, description: 'Optional account-owned workspace selector. Omit for Default.' },
-          shareId: { type: 'string', pattern: '^[0-9a-f]{32}$', description: 'Exact share id from share_status.' },
-          action: { type: 'string', enum: ['publish', 're-share'], description: 'Exact server lifecycle transition. Defaults to publish.' },
-        },
-        required: ['shareId'],
-      },
-    },
-    {
-      name: 'share_revoke',
-      description: 'Revoke an evidence share and withdraw client-viewer access. This outward-facing destructive permission change is idempotent and retains the owner-visible share lifecycle record.',
-      inputSchema: {
-        type: 'object', additionalProperties: false,
-        properties: {
-          workspaceId: { type: 'string', minLength: 1, description: 'Optional account-owned workspace selector. Omit for Default.' },
-          shareId: { type: 'string', pattern: '^[0-9a-f]{32}$', description: 'Exact share id from shares_list.' },
-        },
-        required: ['shareId'],
-      },
-    },
     {
       name: 'catalog_slice_read',
       description: 'Read up to 25 variants from one connected Shopify development store through the existing live catalog-slice route. This is an external Shopify read with no Shopify or Meguro mutation. OAuth may select an owned workspace.',
@@ -1843,32 +2355,12 @@ export function createTools(config) {
     {
       name: 'catalog_slice_snapshot',
       description: 'Mint a short-lived signed catalog snapshot capability from either a live Shopify selection or one saved catalog slice. For a live external read provide shopDomain plus 1–25 variantIds; for a saved slice provide only sliceId. The capability remains bound to the selected workspace and store.',
-      inputSchema: {
-        type: 'object', additionalProperties: false,
-        properties: {
-          workspaceId: { type: 'string', minLength: 1, description: 'Optional account-owned workspace selector. Omit for Default.' },
-          shopDomain: { type: 'string', pattern: '^[a-z0-9][a-z0-9-]*\\.myshopify\\.com$', description: 'Live snapshot source. Mutually exclusive with sliceId.' },
-          variantIds: { type: 'array', minItems: 1, maxItems: 25, items: { type: 'string', minLength: 1 }, description: 'Exact Shopify variant ids returned by catalog_slice_read. Required with shopDomain.' },
-          sliceId: { type: 'string', pattern: '^csl_saved_[A-Za-z0-9_-]{8,128}$', description: 'Saved snapshot source. Mutually exclusive with shopDomain/variantIds.' },
-        },
-        required: [],
-      },
+      inputSchema: CATALOG_SNAPSHOT_INPUT_SCHEMA,
     },
     {
       name: 'catalog_slices_saved',
       description: 'Manage the existing saved-catalog-slice lifecycle with action=list, get, save, delete, refresh, or changes. save/refresh read the connected Shopify store; delete removes only the exact saved slice; list/get/changes are Meguro reads. The worst-case annotation is intentionally destructive and outward because this grouped tool includes delete and external refresh.',
-      inputSchema: {
-        type: 'object', additionalProperties: false,
-        properties: {
-          workspaceId: { type: 'string', minLength: 1, description: 'Optional account-owned workspace selector. Omit for Default.' },
-          action: { type: 'string', enum: ['list', 'get', 'save', 'delete', 'refresh', 'changes'] },
-          shopDomain: { type: 'string', pattern: '^[a-z0-9][a-z0-9-]*\\.myshopify\\.com$', description: 'Required for save.' },
-          label: { type: 'string', minLength: 1, maxLength: 80, description: 'Required for save.' },
-          variantIds: { type: 'array', minItems: 1, maxItems: 25, items: { type: 'string', minLength: 1 }, description: 'Required for save.' },
-          sliceId: { type: 'string', pattern: '^csl_saved_[A-Za-z0-9_-]{8,128}$', description: 'Required for get/delete/refresh/changes.' },
-        },
-        required: ['action'],
-      },
+      inputSchema: CATALOG_SAVED_SLICES_INPUT_SCHEMA,
     },
     {
       name: 'store_claim_by_code',
@@ -1927,7 +2419,7 @@ export function createTools(config) {
     },
     {
       name: 'run_status',
-      description: 'Live progress of a run: orders written / total, sim-date watermark, status, lastError. Account-key-gated, read-only, cache-busted. Use this instead of guessing.',
+      description: 'Read one exact owned history run returned by runs_list. Returns lifecycle, progress, and its server-owned twinPair relation when present. Missing, expired, and foreign-workspace identities fail closed with runs_list recovery teaching.',
       inputSchema: {
         type: 'object',
         additionalProperties: false,
@@ -1950,7 +2442,7 @@ export function createTools(config) {
     },
     {
       name: 'run_report',
-      description: 'Generate and fetch the run\'s receipt (verdict, summary, S3 keys). The receipt never claims more than the ledger can prove. Receipts remain fetchable for 7 days on Free, 90 days on Solo, and 365 days on Builder; an expired response teaches the applicable upgrade or a fresh run.',
+      description: 'Read the retained receipt for one exact owned history run returned by runs_list. The receipt never claims more than the ledger can prove. Missing, expired, and foreign-workspace identities fail closed with runs_list recovery teaching.',
       inputSchema: {
         type: 'object',
         additionalProperties: false,
@@ -1974,7 +2466,7 @@ export function createTools(config) {
     },
     {
       name: 'runs_diff',
-      description: 'Legacy receipt comparison for two Shopify dev-store history runs created by run_start. It does not compare practice simulation attempts returned by practice_run_start; a pa-* id receives a teaching error with the terminating receipt-fact method. For history runs it verifies the shared prefix, finds the fork, and returns impact receipt deltas. Prefer twin_diff for the named history-run impact receipt vocabulary. "Not comparable" is an honest answer, not an error in your usage. Receipts remain fetchable for 7 days on Free, 90 days on Solo, and 365 days on Builder; an expired response teaches the applicable upgrade or a fresh run.',
+      description: 'Legacy receipt comparison for two Shopify dev-store history runs created by run_start. It does not compare practice simulation attempts returned by practice_run_start; a pa-* id receives a teaching error with the terminating receipt-fact method. For history runs it verifies the shared prefix, finds the fork, and returns impact receipt deltas. Prefer twin_diff for the named history-run impact receipt vocabulary. "Not comparable" is an honest answer, not an error in your usage. Receipt availability and expiry guidance are server-owned and returned by the receipt response.',
       inputSchema: {
         type: 'object',
         additionalProperties: false,
@@ -1987,26 +2479,26 @@ export function createTools(config) {
     },
     {
       name: 'gate_configure',
-      description: 'Configure the same Receipt rule V1 that Console offers under Set a Gate. Choose one finished practice simulation receipt, enable or update the Gate, or set enabled to false to disable it. Saving an enabled receipt also performs the same immediate server evaluation as Console; no other policy choice is exposed here because Console offers none.',
+      description: "Configure the optional Configured Receipt Gate policy over selected receipt facts. The receipt's automatic recorded API behavior remains available separately whether or not this configured policy exists. Choose one finished practice simulation receipt, enable or update the policy, or set enabled to false to disable it. Saving an enabled receipt also performs the same immediate server evaluation as Console.",
       inputSchema: {
         type: 'object',
         additionalProperties: false,
         properties: {
-          receiptId: { type: 'string', minLength: 1, description: 'Finished pa-* practice simulation receipt to use as the Receipt Gate bar.' },
+          receiptId: { type: 'string', minLength: 1, description: 'Finished pa-* practice simulation receipt to evaluate with the Configured Receipt Gate.' },
           storeId: { type: 'string', minLength: 1, description: 'Optional practice-store identity carried by the selected Console receipt.' },
-          enabled: { type: 'boolean', description: 'Enable or update the Gate when true or omitted; disable the configured Gate when false.' },
+          enabled: { type: 'boolean', description: 'Enable or update the Configured Receipt Gate when true or omitted; disable it when false.' },
         },
         required: ['receiptId'],
       },
     },
     {
       name: 'gate_evaluate',
-      description: 'Evaluate the configured Receipt rule V1 exactly as Console Evaluate now does. Omit receiptId to evaluate the configured receipt, or supply one finished pa-* receipt explicitly. This records a new server-owned Gate evaluation; it does not derive a local verdict.',
+      description: "Evaluate the Configured Receipt Gate exactly as Console does. It is an optional configured policy over selected receipt facts, separate from the receipt's automatic recorded API behavior. Omit receiptId to evaluate the configured receipt, or supply one finished pa-* receipt explicitly. This records a new server-owned evaluation; it does not derive a local verdict.",
       inputSchema: {
         type: 'object',
         additionalProperties: false,
         properties: {
-          receiptId: { type: 'string', minLength: 1, description: 'Optional finished pa-* practice simulation receipt. Omit it to evaluate the configured Gate receipt.' },
+          receiptId: { type: 'string', minLength: 1, description: 'Optional finished pa-* practice simulation receipt. Omit it to evaluate the Configured Receipt Gate receipt.' },
           storeId: { type: 'string', minLength: 1, description: 'Optional exact practice-store identity. Omit when receiptId identifies the owner or the workspace has exactly one store.' },
         },
         required: [],
@@ -2014,20 +2506,20 @@ export function createTools(config) {
     },
     {
       name: 'gate_verdict',
-      description: 'Read the latest server-computed Receipt Gate verdict. A previously issued legacy Gate artifact remains readable by its exact runId, but no customer surface creates one. Returns the exact meguro.gate-verdict.v1 object with go/waiting/no-go status, named fact-citing checks, per-check outcomes, flip condition, and named policy version. Facts are the product: this is a named, reproducible, replaceable policy over facts the customer fully holds; check it yourself.',
+      description: "Read the latest server-computed Configured Receipt Gate verdict. This optional configured policy is separate from the receipt's automatic recorded API behavior, which remains available. A previously issued legacy artifact remains readable by its exact runId, but no customer surface creates one. Returns the exact meguro.gate-verdict.v1 object with go/waiting/no-go status, named fact-citing checks, per-check outcomes, flip condition, and named policy version. Facts are the product: this remains a named, reproducible, replaceable policy over facts the customer fully holds; check it yourself.",
       inputSchema: {
         type: 'object',
         additionalProperties: false,
         properties: {
-          runId: { type: 'string', minLength: 1, description: 'Exact id of a previously issued legacy Gate artifact. Omit to read the latest Receipt Gate verdict.' },
-          storeId: { type: 'string', minLength: 1, description: 'Optional exact practice-store identity for the current per-store Gate lane.' },
+          runId: { type: 'string', minLength: 1, description: 'Exact id of a previously issued legacy Gate artifact. Omit to read the latest Configured Receipt Gate verdict.' },
+          storeId: { type: 'string', minLength: 1, description: 'Optional exact practice-store identity for the current per-store Configured Receipt Gate lane.' },
         },
         required: [],
       },
     },
     {
       name: 'runs_list',
-      description: 'List Shopify dev-store history runs created by run_start so an agent can re-find that family of prior work. It does not list practice simulation attempts returned by practice_run_start; call practice_runs_list for those pa-* ids, then use practice_run_report or practice_run_impact. Optional history-run lifecycle filtering supports running, paused, completed, failed, or cleaning. An empty result explicitly says it is only about history runs. The payload names run-clock lifecycle timestamps separately from world-clock scenario coordinates and returns no filter counts.',
+      description: 'Discover the owned Shopify dev-store history runs readable through hosted OAuth. A completed server-owned twin relation is projected as twinPair with pairId, baseline/treated role, and exact counterpartRunId; pass those returned identities to run_status, run_report, and twin_diff. It does not list practice simulation attempts returned by practice_run_start. Optional lifecycle filtering supports running, paused, completed, failed, or cleaning.',
       inputSchema: {
         type: 'object',
         additionalProperties: false,
@@ -2039,12 +2531,22 @@ export function createTools(config) {
     },
     {
       name: 'usage_read',
-      description: 'Read authoritative tier-meter simulation runs, practice-store, and workspace headroom before starting work. When retained activity reconciles, simulationRunAccounting gives the exact counted + excluded non-billable sample = visible completed equation and the stable exclusion-policy identity. Incomplete coverage or a source mismatch is disclosed without projecting a competing consumption number.',
-      inputSchema: { type: 'object', additionalProperties: false, properties: {}, required: [] },
+      description: 'Read authoritative tier-meter simulation runs, practice-store, and workspace headroom. The compatibility field limits.runStartAllowed means only that metering allowance permits one charged run; it is not overall run-start eligibility. Omit storeId to receive runStartEligibility as explicitly not evaluated. Supply an exact storeId, and optionally the intended continueFromAttemptId, to receive the separate server-owned store/root lifecycle eligibility and exact next call. When retained activity reconciles, simulationRunAccounting gives the exact counted + excluded non-billable = visible completed equation and one exclusion entry per durable classification that caused the exclusion. Incomplete coverage or a source mismatch is disclosed without projecting a competing consumption number.',
+      inputSchema: {
+        type: 'object',
+        additionalProperties: false,
+        properties: {
+          workspaceId: OPTIONAL_WORKSPACE_SELECTOR_INPUT_SCHEMA,
+          storeId: { ...PRACTICE_STORE_ID_INPUT_SCHEMA, description: 'Optional exact practice-store id whose run-start lifecycle should be evaluated. Omission never implies global eligibility.' },
+          continueFromAttemptId: { type: 'string', minLength: 4, maxLength: 128, pattern: '^pa-[a-z0-9][a-z0-9-]{0,124}$', description: 'Optional intended continuation root. Requires storeId and is evaluated against that exact store.' },
+        },
+        required: [],
+        dependentRequired: { continueFromAttemptId: ['storeId'] },
+      },
     },
     {
       name: 'twin_diff',
-      description: 'Read the impact receipt comparing a treated run with its doing-nothing twin: shared-prefix integrity, world-clock day deltas, fidelity, and the measured impact over the named world-clock horizon. Facts remain available even when the integrity verdict refuses a causal claim. Receipts remain fetchable for 7 days on Free, 90 days on Solo, and 365 days on Builder; an expired response teaches the applicable upgrade or a fresh run.',
+      description: 'Read the impact receipt for the baseline and treated members of one server-recorded twinPair, in that order. The result carries pair identity, both exact source run IDs, their run_status and run_report calls, and current receipt retention. Missing, expired, foreign, reversed, or nonpaired sources fail closed; unrelated runs are never compared.',
       inputSchema: {
         type: 'object',
         additionalProperties: false,
@@ -2069,7 +2571,7 @@ export function createTools(config) {
     },
     {
       name: 'exam_start',
-      description: 'Start or safely continue a Shopify Exam from one immutable practice attempt on the exact typed development-store domain. The tool performs idempotent create/preview/typed-confirm setup, then advances at most one bounded executor checkpoint. Call exam_status after every invocation; while nextAction names exam_start, repeat the same arguments. GET polling never advances the Exam and ambiguous delivery is never retried blindly.',
+      description: 'Start or safely continue a Shopify Exam from one immutable practice attempt on the exact typed development-store domain. The tool performs idempotent create/preview/typed-confirm setup, then advances at most one bounded execution or cleanup checkpoint. Call exam_status after every invocation; while nextAction names exam_start, repeat the same arguments. GET polling never advances or cleans the Exam and ambiguous delivery is never retried blindly.',
       inputSchema: {
         type: 'object', additionalProperties: false,
         properties: {
@@ -2081,7 +2583,7 @@ export function createTools(config) {
     },
     {
       name: 'exam_status',
-      description: 'GET-only server-authoritative Shopify Exam lifecycle status: current revision and phase cursors, verdict/comparison summary when present, cleanup/residue state, immutable receipt availability, Gate projection, and the exact next tool. Reading status never advances or cleans the Exam.',
+      description: 'GET-only server-authoritative Shopify Exam lifecycle status: current revision and phase cursors, verdict/comparison summary when present, cleanup/residue state, immutable receipt availability, Configured Receipt Gate projection, and the exact next tool. Reading status never advances or cleans the Exam; pending cleanup names exam_start as the continuation.',
       inputSchema: {
         type: 'object', additionalProperties: false,
         properties: { examId: { type: 'string', pattern: '^pex-[0-9a-f]{24}$', description: 'Exam id returned by exam_start.' } },
@@ -2090,7 +2592,7 @@ export function createTools(config) {
     },
     {
       name: 'exam_report',
-      description: 'Read the completed Shopify Exam result and verify the exact stored bytes of both private and public immutable receipts against their artifact digests. Returns bounded receipt identities, digests, byte counts, verdict, comparison totals, cleanup/residue facts, and Gate evidence — never raw private receipt payloads or credentials. Receipts remain fetchable for 7 days on Free, 90 days on Solo, and 365 days on Builder; an expired response teaches the applicable upgrade or a fresh run.',
+      description: 'Read a cleaned or safely blocked Shopify Exam result and verify the exact stored bytes of both private and public immutable receipts against their artifact digests. A completed comparison with pending cleanup must be continued through exam_start before this tool returns a final report. Returns bounded receipt identities, digests, byte counts, verdict, comparison totals, cleanup/residue facts, and Configured Receipt Gate evidence — never raw private receipt payloads or credentials. Receipt availability and expiry guidance are server-owned and returned by the receipt response.',
       inputSchema: {
         type: 'object', additionalProperties: false,
         properties: { examId: { type: 'string', pattern: '^pex-[0-9a-f]{24}$', description: 'Completed Exam id returned by exam_start.' } },
@@ -2099,18 +2601,18 @@ export function createTools(config) {
     },
     {
       name: 'practice_run_start',
-      description: 'Start an external-agent practice simulation run on an existing Meguro practice store, or continue one completed Builder segment on the same aging store. A fresh start replays the practice store\'s original scenario baseline as segment 1 by default; chaining is explicit through continueFromAttemptId. When clock.simulationDays is omitted, Meguro automatically plans the tier-legal segment from the remaining scenario arc and returns a machine-readable segmentPlan with the exact Store-day range and continuation narration. The returned machine-readable simulationRunClock announces every exit: 1 hour for an agent that never executes, 48 hours with neither agent contact nor Store-time advance, and a 7-day run age (2 days on Free). Takes the canonical practice-store id (`storeId`) exactly as returned by get_connection_details, and returns the run identity (`attemptId`) every later practice_run_* tool uses — the store id and the run id are different identifiers. Meguro Console is quick proof, while the agency agent still runs in the caller\'s own environment. Returns the same server-authoritative practice-run contract without connection credentials.',
+      description: 'Start an external-agent practice simulation run on an existing Meguro practice store, or continue one completed segment on the same aging store when server authorization allows it. The returned lifecycleContract explains that accepted writes are disposable attempt-local state, actions remain in receipt and Impact evidence, the store returns to baseline after completion, terminal reads remain available while writes are refused, and ordinary completed runs meter once. A fresh account\'s first accepted start may bind its one account-owned onboarding evaluation grant to the chosen store/template/root and pinned ideal horizon; every authorized segment is unmetered, while every run after that horizon follows ordinary tier policy. A fresh start replays the practice store\'s original scenario baseline as segment 1 by default; chaining is explicit through continueFromAttemptId. An optional immutable assertionPlan may predeclare exact expected negative-control refusals before call sequence zero; only exact server-matched reason, layer, target or request, and cardinality can prevent that rejection from becoming an unhandled Configured Receipt Gate failure. When clock.simulationDays is omitted, Meguro derives the full remaining scenario arc. Without active onboarding authorization, Builder plans a capped legal segment while Free or Solo refuses an above-cap arc. For an executable onboarding call, choose the matching starterRecommendation.starterPlans entry returned by templates_list and use its exact practiceRunStart.clock; otherwise use the returned ordinary starterPlan. Every accepted start returns a machine-readable segmentPlan with the exact Store-day range, authorization, and continuation narration. An advance target that reaches or crosses the planned end requires explicit terminal confirmation before the run ends; state-changing Admin calls require a running run, so use return-request-pending to stop on an actionable return before the planned end. The returned machine-readable simulationRunClock announces every exit: 1 hour for an agent that never executes, 48 hours with neither agent contact nor Store-time advance, and a 7-day run age (2 days on Free). Takes the canonical practice-store id (`storeId`) exactly as returned by get_connection_details, and returns the run identity (`attemptId`) every later practice_run_* tool uses — the store id and the run id are different identifiers. Meguro Console is quick proof, while the agency agent still runs in the caller\'s own environment. Returns the same server-authoritative practice-run contract without connection credentials.',
       inputSchema: {
         type: 'object',
         additionalProperties: false,
         properties: {
+          workspaceId: OPTIONAL_WORKSPACE_SELECTOR_INPUT_SCHEMA,
           storeId: { ...PRACTICE_STORE_ID_INPUT_SCHEMA, description: 'Canonical Meguro practice-store id (tenant-owned), as returned by get_connection_details.' },
-          worldId: { ...PRACTICE_STORE_ID_INPUT_SCHEMA, description: 'Legacy alias for storeId — the same practice-store id under its old name. Prefer storeId.' },
-          continueFromAttemptId: { type: 'string', minLength: 4, maxLength: 128, pattern: '^pa-[a-z0-9][a-z0-9-]{0,124}$', description: 'Completed prior segment to continue on the same aging practice store. Available only when the server tier policy allows continuation. Omit clock.simulationDays to let Meguro plan the next legal segment automatically.' },
+          continueFromAttemptId: { type: 'string', minLength: 4, maxLength: 128, pattern: '^pa-[a-z0-9][a-z0-9-]{0,124}$', description: 'Completed prior segment to continue on the same aging practice store. Available only when the server tier policy allows continuation. On Builder, omit clock.simulationDays to let Meguro plan the next legal segment automatically.' },
           clock: {
             type: 'object',
             additionalProperties: false,
-            description: 'Optional hosted practice-run clock. Omit simulationDays for automatic tier-legal segment planning; set it only when explicitly requesting a shorter bounded segment.',
+            description: 'Optional hosted practice-run clock. Omission derives the full remaining scenario arc and may refuse on Free or Solo; use templates_list starterPlan.practiceRunStart.clock for the current tier\'s executable first segment, or set a shorter bounded segment explicitly.',
             properties: {
               mode: { type: 'string', enum: ['manual', 'harness', 'scheduled'] },
               simulationDays: { type: 'integer', minimum: 0, description: 'Explicit segment length. Requests above the tier segment or remaining canvas cap are refused with an executable maximum.' },
@@ -2132,10 +2634,37 @@ export function createTools(config) {
             required: ['name', 'version', 'ref'],
           },
           observationPlan: { ...PRACTICE_RUN_OBSERVATION_PLAN_INPUT_SCHEMA, description: 'Optional trusted read-only checkpoint observation plan. Use one closed observations envelope; each row is either an inline read request or one saved read probe.' },
+          assertionPlan: {
+            type: 'object',
+            additionalProperties: false,
+            description: 'Optional immutable run-start expected-refusal declarations. Generic expected flags, wildcards, HTTP classes, and Meguro compatibility failures are refused.',
+            properties: {
+              schemaVersion: { type: 'string', const: 'meguro.run-assertion-plan.v1' },
+              expectedRefusals: {
+                type: 'array', minItems: 1, maxItems: 10,
+                items: {
+                  type: 'object', additionalProperties: false,
+                  properties: {
+                    assertionId: { type: 'string', pattern: '^[a-z][a-z0-9_.-]{2,95}$' },
+                    operationFamily: { type: 'string', const: 'shopify-admin-graphql-mutation' },
+                    operationName: { type: 'string', pattern: '^[A-Za-z_][A-Za-z0-9_]{0,95}$' },
+                    targetGid: { type: 'string', pattern: '^gid://shopify/[A-Za-z][A-Za-z0-9]*/[A-Za-z0-9._:-]{1,160}$' },
+                    requestFingerprint: { type: 'string', pattern: '^[0-9a-f]{64}$' },
+                    expectedResult: { type: 'string', const: 'rejected' },
+                    rejectionReasonCodes: { type: 'array', minItems: 1, maxItems: 8, uniqueItems: true, items: { type: 'string', enum: ['shopify_idempotency_required', 'agent_request_verified_invalid', 'modeled_business_rule_rejected', 'external_platform_rejected'] } },
+                    responsibleLayer: { type: 'string', enum: ['agent_request', 'modeled_business_rule', 'external_platform'] },
+                    cardinality: { type: 'object', additionalProperties: false, properties: { minAttempts: { type: 'integer', minimum: 1, maximum: 10 }, maxAttempts: { type: 'integer', minimum: 1, maximum: 10 } }, required: ['minAttempts', 'maxAttempts'] },
+                    correctionExpectation: { type: 'object', additionalProperties: false, properties: { result: { type: 'string', const: 'accepted-same-operation-target' }, withinFollowingCalls: { type: 'integer', minimum: 1, maximum: 50 } }, required: ['result', 'withinFollowingCalls'] },
+                  },
+                  required: ['assertionId', 'operationFamily', 'operationName', 'expectedResult', 'rejectionReasonCodes', 'responsibleLayer', 'cardinality'],
+                },
+              },
+            },
+            required: ['schemaVersion', 'expectedRefusals'],
+          },
           graphqlThrottleMode: { type: 'string', enum: ['off', 'standard-1000', 'plus-2000'], description: 'Optional Meguro compatibility GraphQL throttle mode.' },
         },
-        required: [],
-        anyOf: [{ required: ['storeId'] }, { required: ['worldId'] }],
+        required: ['storeId'],
       },
     },
     {
@@ -2154,10 +2683,13 @@ export function createTools(config) {
     },
     {
       name: 'practice_run_status',
-      description: 'Read the server-authoritative state of an external-agent practice simulation run, including its announced simulation-run deadlines and immutable simulation run receipt after any exit. Use Console for quick proof; the tested agent remains in the caller\'s environment.',
+      description: 'Read the server-authoritative state of an external-agent practice simulation run, including its announced simulation-run deadlines, immutable simulation run receipt after any exit, and lifecycleContract. That contract explains that accepted writes are disposable attempt-local state, actions remain in receipt and Impact evidence, the store returns to baseline after completion, terminal reads remain available while writes are refused, and an ordinary completed run is metered once while the explicitly provisioned sample is exempt. Immediately before advancing, copy practiceRun.advanceCursor unchanged into practice_run_advance; do not choose between currentDay and watermarkDay or assemble call-sequence fields. If the next target reaches or crosses endDay, follow the exact terminal-confirmation retry returned by practice_run_advance. A running run authorizes state-changing Admin calls; after completion later writes receive the stable run-complete refusal. Use Console for quick proof; the tested agent remains in the caller\'s environment.',
       inputSchema: {
         type: 'object', additionalProperties: false,
-        properties: { attemptId: { type: 'string', minLength: 4, maxLength: 128, pattern: '^pa-[a-z0-9][a-z0-9-]{0,124}$', description: 'Run identity returned by practice_run_start — not the practice-store id (storeId).' } },
+        properties: {
+          workspaceId: OPTIONAL_WORKSPACE_SELECTOR_INPUT_SCHEMA,
+          attemptId: { type: 'string', minLength: 4, maxLength: 128, pattern: '^pa-[a-z0-9][a-z0-9-]{0,124}$', description: 'Run identity returned by practice_run_start — not the practice-store id (storeId).' },
+        },
         required: ['attemptId'],
       },
     },
@@ -2166,24 +2698,28 @@ export function createTools(config) {
       description: 'Capture an immutable checkpoint for an external-agent practice run and return a bounded evidence summary. Console is quick proof; agent execution remains in the caller\'s environment.',
       inputSchema: {
         type: 'object', additionalProperties: false,
-        properties: { attemptId: { type: 'string', minLength: 4, maxLength: 128, pattern: '^pa-[a-z0-9][a-z0-9-]{0,124}$', description: 'Run identity returned by practice_run_start — not the practice-store id (storeId).' } },
+        properties: {
+          workspaceId: OPTIONAL_WORKSPACE_SELECTOR_INPUT_SCHEMA,
+          attemptId: { type: 'string', minLength: 4, maxLength: 128, pattern: '^pa-[a-z0-9][a-z0-9-]{0,124}$', description: 'Run identity returned by practice_run_start — not the practice-store id (storeId).' },
+        },
         required: ['attemptId'],
       },
     },
     {
       name: 'practice_run_advance',
-      description: 'Advance an external-agent practice run by whole days or until one closed-set commerce condition, using both optimistic concurrency cursors. Immediately before every advance, call practice_run_status and copy both current cursor values from that same response. If either cursor is stale, Meguro refuses without moving Store time: refresh both cursors from practice_run_status and do not retry the stale request. Before durable agentExecutionStartedAt exists, at most 7 Store days may be advanced; connect your agent — any call unlocks further time. Console is quick proof; agent execution remains in the caller\'s environment.',
+      description: 'Advance an external-agent practice run by whole days or until one closed-set commerce condition, using the server-owned optimistic-concurrency advanceCursor. Accepted writes are disposable attempt-local state: they remain in receipt and Impact evidence, while the underlying practice store returns to baseline after completion. Terminal reads remain available and terminal writes are refused. An advance that reaches or crosses planned endDay refuses without changing Store time unless the caller explicitly retries the returned shape with confirmConclusion: true; that confirmed retry concludes the attempt and closes its write lane. return-request-pending stops before planned end with the evaluated Store day, pending-request count, and one bounded opportunity for the next read; it never resolves the request automatically. If no opportunity exists before planned end, the explicit confirmation path ends in the stable run-complete refusal for later writes and offers no write suggestion. State-changing Admin calls require a running run. Immediately before every advance, call practice_run_status and copy practiceRun.advanceCursor unchanged. If it is stale, Meguro refuses without moving Store time and returns a fresh advanceCursor for one exact retry; do not infer from currentDay, watermarkDay, or call-sequence fields. Before durable agentExecutionStartedAt exists, at most 7 Store days may be advanced; connect your agent — any call unlocks further time. Console is quick proof; agent execution remains in the caller\'s environment.',
       inputSchema: {
         type: 'object',
         additionalProperties: false,
         properties: {
+          workspaceId: OPTIONAL_WORKSPACE_SELECTOR_INPUT_SCHEMA,
           attemptId: { type: 'string', minLength: 4, maxLength: 128, pattern: '^pa-[a-z0-9][a-z0-9-]{0,124}$', description: 'Run identity returned by practice_run_start — not the practice-store id (storeId).' },
           days: { type: 'integer', minimum: 1, description: 'Whole simulated days to advance.' },
           until: PRACTICE_RUN_UNTIL_INPUT_SCHEMA,
-          expectedDay: { type: 'integer', minimum: 0, description: 'Call practice_run_status immediately before advancing and copy its current practiceRun.time.watermarkDay. This cursor is required on every advance; if it is stale, the advance is refused without moving Store time.' },
-          expectedCallSeq: { type: 'integer', minimum: -1, description: 'From the same immediately preceding practice_run_status response, copy current practiceRun.latestCallSequence (or -1 only when that response says no call exists). This cursor is required on every advance; if it is stale, the advance is refused without moving Store time.' },
+          advanceCursor: PRACTICE_RUN_ADVANCE_CURSOR_INPUT_SCHEMA,
+          confirmConclusion: { type: 'boolean', description: 'Set true only after reading the terminal-boundary teaching refusal and choosing to conclude the attempt and close its write lane.' },
         },
-        required: ['attemptId', 'expectedDay', 'expectedCallSeq'],
+        required: ['attemptId', 'advanceCursor'],
         oneOf: [
           { required: ['days'], not: { required: ['until'] } },
           { required: ['until'], not: { required: ['days'] } },
@@ -2192,43 +2728,57 @@ export function createTools(config) {
     },
     {
       name: 'practice_run_finish',
-      description: 'Explicitly finish an external-agent practice simulation run without inventing additional time or evidence. The response includes the immutable simulation run receipt and echoes the deadlines announced at start. Console is quick proof; agent execution remains in the caller\'s environment.',
+      description: 'End an external-agent practice segment without inventing time or evidence. A segment at planned end completes; an under-measured segment stops and remains explicitly incomplete. For a stopped onboarding segment, the server-owned practiceRun.recovery object gives the exact practice_run_start call that resumes the same bound root at its authoritative watermark. To abandon that incomplete onboarding evaluation permanently, set both permanentStop and acknowledgeIncompleteOnboardingEvaluation true; Meguro preserves evidence and consumed onboarding value. The response includes the immutable segment receipt and announced deadlines. Console is quick proof; agent execution remains in the caller\'s environment.',
       inputSchema: {
         type: 'object', additionalProperties: false,
-        properties: { attemptId: { type: 'string', minLength: 4, maxLength: 128, pattern: '^pa-[a-z0-9][a-z0-9-]{0,124}$', description: 'Run identity returned by practice_run_start — not the practice-store id (storeId).' } },
+        properties: {
+          workspaceId: OPTIONAL_WORKSPACE_SELECTOR_INPUT_SCHEMA,
+          attemptId: { type: 'string', minLength: 4, maxLength: 128, pattern: '^pa-[a-z0-9][a-z0-9-]{0,124}$', description: 'Run identity returned by practice_run_start — not the practice-store id (storeId).' },
+          permanentStop: { type: 'boolean', description: 'Set true only to abandon an under-measured onboarding evaluation permanently. Requires acknowledgeIncompleteOnboardingEvaluation=true.' },
+          acknowledgeIncompleteOnboardingEvaluation: { type: 'boolean', description: 'Set true with permanentStop to acknowledge that the bound onboarding evaluation will remain incomplete while its evidence and consumed value remain preserved.' },
+        },
         required: ['attemptId'],
+        dependentRequired: {
+          permanentStop: ['acknowledgeIncompleteOnboardingEvaluation'],
+          acknowledgeIncompleteOnboardingEvaluation: ['permanentStop'],
+        },
       },
     },
     {
       name: 'practice_run_report',
-      description: 'Read the run\'s receipt — a bounded receipt summary for a completed external-agent practice run. `report` is the protocol/route compatibility name for the receipt (the tool name and the `operation: "report"` field keep it for wire stability); user-facing language is "receipt". The payload includes an unguessable public receipt id, a complete environment-qualified HTTPS URL in `canonicalPath`, and SHA-256: fetch that URL without credentials and verify the exact bytes before promotion. Raw private request and response payloads stay out of MCP; use Console for quick proof while the agent remains in the caller\'s environment. Receipts remain fetchable for 7 days on Free, 90 days on Solo, and 365 days on Builder; an expired response teaches the applicable upgrade or a fresh run.',
+      description: 'Read the run\'s receipt — a bounded receipt summary for a completed external-agent practice run. `reportBack` is the exact server-owned customer summary in the fixed order Mechanics, Conduct, Scenario outcome; MCP passes it through without re-deriving or reclassifying any plane, and modeled money closes its narrative. `takeHome` is the frozen take-home packet the issued receipt itself carries — the same ordered Mechanics, Conduct, Scenario outcome facts the public receipt view serves, plus the source URL and SHA-256, the claims/evidence boundary, the verification steps, and a copy-ready `memo`; MCP passes it through unchanged and compiles no part of it. `eventResolution` passes through the exact creation-pinned template identity/revision, evaluation horizon, measured horizon, and typed event-window result; it never recovers current catalog metadata for a historical run. `gate` is the exact server-owned final machine projection; `rejectionAttribution.gateStatus` is mechanically aligned with it, and neither value is re-derived by MCP. Immutable expected-refusal declarations appear with their exact server-emitted matched or failure status; a matched rejection remains in raw receipt counts while only its unhandled Configured Receipt Gate consequence changes. Interpret `resultSemantics.lifecycle`, `evidenceAssertions`, `technicalPolicyVerdict`, and `modeledScenarioOutcome` as independent named dimensions; there is no implicit overall status. Existing `summary`, `defaultVerdict`, `verdict`, and `measurement` fields are legacy compatibility fields. `report` is the protocol/route compatibility name for the receipt (the tool name and the `operation: "report"` field keep it for wire stability); user-facing language is "receipt". The payload includes an unguessable public receipt id, a complete environment-qualified HTTPS URL in `canonicalPath`, and SHA-256: fetch that URL without credentials and verify the exact bytes before promotion. Raw private request and response payloads stay out of MCP; use Console for quick proof while the agent remains in the caller\'s environment. Receipt availability and expiry guidance are server-owned and returned by the receipt response.',
       inputSchema: {
         type: 'object', additionalProperties: false,
-        properties: { attemptId: { type: 'string', minLength: 4, maxLength: 128, pattern: '^pa-[a-z0-9][a-z0-9-]{0,124}$', description: 'Run identity returned by practice_run_start — not the practice-store id (storeId).' } },
+        properties: {
+          attemptId: { type: 'string', minLength: 4, maxLength: 128, pattern: '^pa-[a-z0-9][a-z0-9-]{0,124}$', description: 'Run identity returned by practice_run_start — not the practice-store id (storeId).' },
+          workspaceId: { type: 'string', minLength: 1, description: 'Optional account-owned workspace coordinate returned by practice_runs_list. Omit for Default.' },
+        },
         required: ['attemptId'],
       },
     },
     {
       name: 'practice_run_impact',
-      description: 'Read the impact receipt for a completed external-agent practice run: the base year — the same store, same days, without your agent — compared with your agent\'s year, showing what changed because of your agent (orders, units, and revenue), a footprint of every write, and an integrity gate that reports a reason instead of numbers when the comparison is not clean. The payload includes an unguessable public receipt id, a complete environment-qualified HTTPS URL in `canonicalPath`, and SHA-256: fetch that URL without credentials and verify the exact bytes before promotion. Read-only; never mutates the run and returns no credentials. Takes the run\'s attemptId (from practice_run_start), not the practice-store id (storeId). Receipts remain fetchable for 7 days on Free, 90 days on Solo, and 365 days on Builder; an expired response teaches the applicable upgrade or a fresh run.',
+      description: 'Read the impact receipt for a completed external-agent practice run: the base year — the same store, same days, without your agent — compared with your agent\'s year, showing what changed because of your agent (orders, units, and revenue), a footprint of every write, and an integrity gate that reports a reason instead of numbers when the comparison is not clean. `eventResolution` is the exact creation-pinned template identity/revision, evaluation horizon, measured horizon, and typed event-window result; historical runs without that snapshot are explicitly unavailable and never consult current template metadata. The payload includes an unguessable public receipt id, a complete environment-qualified HTTPS URL in `canonicalPath`, and SHA-256: fetch that URL without credentials and verify the exact bytes before promotion. Read-only; never mutates the run and returns no credentials. Takes the run\'s attemptId (from practice_run_start), not the practice-store id (storeId). Receipt availability and expiry guidance are server-owned and returned by the receipt response.',
       inputSchema: {
         type: 'object', additionalProperties: false,
-        properties: { attemptId: { type: 'string', minLength: 4, maxLength: 128, pattern: '^pa-[a-z0-9][a-z0-9-]{0,124}$', description: 'Run identity returned by practice_run_start — not the practice-store id (storeId).' } },
+        properties: {
+          attemptId: { type: 'string', minLength: 4, maxLength: 128, pattern: '^pa-[a-z0-9][a-z0-9-]{0,124}$', description: 'Run identity returned by practice_run_start — not the practice-store id (storeId).' },
+          workspaceId: { type: 'string', minLength: 1, description: 'Optional account-owned workspace coordinate returned by practice_runs_list. Omit for Default.' },
+        },
         required: ['attemptId'],
       },
     },
     {
       name: 'get_connection_details',
-      description: `Fetch connection material for supported Shopify Admin GraphQL versions ${ADMIN_API_SUPPORTED_VERSION_LABEL}; the default is ${ADMIN_API_DEFAULT_VERSION}. Returns adminApiVersion (default), adminApiVersions (supported set), adminVersions (exact versioned URLs), the default URL, access token, and shop domain for an existing Meguro practice store so an assistant can configure a user agent without opening the dashboard. Inspect the selected version with admin_schema before the first Admin call; an agent targeting a newer Shopify release outside the supported set must treat that behavior as not established. Takes the canonical practice-store id (storeId) and returns it back, so the result passes directly into practice_run_start({ storeId }) — no identifier translation. The practice-store id is not an attemptId (run identity). The hosted MCP path uses the caller's OAuth grant; the public STDIO path uses its workspace-bound account API key.`,
+      description: `Fetch connection material and a structured, state-aware Admin execution guide for supported Shopify Admin GraphQL versions ${ADMIN_API_SUPPORTED_VERSION_LABEL}; the default is ${ADMIN_API_DEFAULT_VERSION}. Returns adminApiVersion (default), adminApiVersions (supported set), adminVersions (exact versioned URLs), the default URL, access token, shop domain, current run status/cursors, valid next calls, and the read/write/idempotency sequence. The hosted OAuth grant or the public STDIO workspace-bound account API key authenticates MCP/control-plane calls only. Shopify-shaped Admin data-plane calls use the returned Admin URL and per-store token in the X-Shopify-Access-Token header; never send the OAuth bearer to that URL. Examples carry only <SHOPIFY_ADMIN_ACCESS_TOKEN>, never the returned secret. Inspect the selected recipe or mutation with admin_schema before the first Admin call; an agent targeting a newer Shopify release outside the supported set must treat that behavior as not established. Takes the canonical practice-store id (storeId) and returns it back, so the result passes directly into practice_run_start({ storeId }) — no identifier translation. The practice-store id is not an attemptId (run identity).`,
       inputSchema: {
         type: 'object',
         additionalProperties: false,
         properties: {
+          workspaceId: OPTIONAL_WORKSPACE_SELECTOR_INPUT_SCHEMA,
           storeId: { ...PRACTICE_STORE_ID_INPUT_SCHEMA, description: 'Canonical Meguro practice-store id, e.g. w-abc123. Pass the returned storeId straight into practice_run_start.' },
-          worldId: { ...PRACTICE_STORE_ID_INPUT_SCHEMA, description: 'Legacy alias for storeId — the same practice-store id under its old name. Prefer storeId.' },
         },
-        required: [],
-        anyOf: [{ required: ['storeId'] }, { required: ['worldId'] }],
+        required: ['storeId'],
       },
     },
     {
@@ -2238,6 +2788,7 @@ export function createTools(config) {
         type: 'object',
         additionalProperties: false,
         properties: {
+          workspaceId: OPTIONAL_WORKSPACE_SELECTOR_INPUT_SCHEMA,
           worldId: { type: 'string', minLength: 1, description: 'Meguro practice store id, e.g. w-abc123.' },
           query: { type: 'string', maxLength: 30000, description: 'The Admin GraphQL query or mutation document to run.' },
           apiVersion: { type: 'string', pattern: '^\\d{4}-\\d{2}$', description: `Admin API version as YYYY-MM. Supported: ${ADMIN_API_SUPPORTED_VERSIONS.join(', ')}. Defaults to ${ADMIN_API_DEFAULT_VERSION}.` },
@@ -2250,16 +2801,66 @@ export function createTools(config) {
     },
     {
       name: 'admin_schema',
-      description: `Look up an exact, bounded slice of the Shopify Admin GraphQL surface Meguro models for supported versions ${ADMIN_API_SUPPORTED_VERSION_LABEL}; the default is ${ADMIN_API_DEFAULT_VERSION}. Returns a type and its direct fields, a Type.field or root mutation with its arguments and return type, a shared commerce recipe, or an authored valid-not-modeled teaching boundary. Deterministic — it never returns the full schema, tenant data, catalog, or credentials, and on a miss it suggests only exact prefix/substring alternatives.`,
+      description: `Look up an exact, bounded slice of the Shopify Admin GraphQL surface Meguro models for supported versions ${ADMIN_API_SUPPORTED_VERSION_LABEL}; the default is ${ADMIN_API_DEFAULT_VERSION}. Returns a type and its direct fields, a Type.field or root mutation with its arguments and return type, a shared commerce recipe, or an authored valid-not-modeled teaching boundary. A recipe match carries its bindingPlan, and every published mutation recipe carries match.recipe.evidencePlan: the eligibility read to run first (its exact query, variables, a selection sentence naming which returned row to use, and bindings from each response path to the mutation variable it fills), then the mutation, then the existing independent readback. mutation.documentOperationName is the GraphQL document label; mutation.rootField is the Shopify mutation coordinate. Where the mutation has a read-before-write cursor the plan also carries expectedRefusalOperationName — the exact root-field matcher key — plus staleCursorExpectedRefusal reason and layer facts to copy unchanged into an assertionPlan. Mutation example values that only the eligibility read can supply appear as <from-eligibility:VARIABLE_PATH> placeholders, never as plausible literals. Deterministic — it never returns the full schema, tenant data, catalog, or credentials, and on a miss it suggests only exact prefix/substring alternatives. Alternatively, submit query instead of lookup + name — with optional variables, operationName, and apiVersion — to ask what this exact Admin document would receive before you create a practice store or spend credit. It parses the document and classifies the selected operation and every supplied coordinate through the same served schema, versioned compatibility registry, and required-argument recovery authority the served Admin surface uses, returning exactly one state: "served" — no compatibility teaching refusal would be produced; "unsupported-with-recovery" — the exact refusal plus the registry remedy naming the supported coordinate or the exact admin_schema call that answers a required-argument refusal; "out-of-plane" — outside the claimed Admin plane, or no exact recovery authority exists. A compatibility withdrawal also carries teachingRefusal: the same refusal the served Admin surface returns, with its code, coordinate, reason, and next step. A document that will not parse, or whose operation cannot be selected without guessing, comes back with that as its own reason rather than guessed compatibility. Store-free and pre-credit: it creates or reads no practice store, run, attempt, ledger, probe, or checkpoint, consumes no credit, and never executes the submitted document. The two modes are exclusive: pass lookup + name or query, never both.`,
       inputSchema: {
         type: 'object',
         additionalProperties: false,
         properties: {
-          lookup: { type: 'string', enum: ['type', 'field', 'mutation', 'recipe'], description: 'What to look up: a type, a Type.field, a root mutation, or a commerce recipe.' },
-          name: { type: 'string', minLength: 1, maxLength: 200, description: 'Exact name: e.g. ProductVariant, ProductVariant.inventoryQuantity, inventoryAdjustQuantities, or a recipe id/operationName like low-inventory or LowInventory.' },
+          lookup: { type: 'string', enum: ['type', 'field', 'mutation', 'recipe'], description: 'Lookup mode: what to look up — a type, a Type.field, a root mutation, or a commerce recipe. Requires name.' },
+          name: { type: 'string', minLength: 1, maxLength: 200, description: 'Lookup mode: exact name, e.g. ProductVariant, ProductVariant.inventoryQuantity, inventoryAdjustQuantities, or a recipe id/operationName like low-inventory or LowInventory.' },
+          query: { type: 'string', minLength: 1, maxLength: 30000, description: 'Refusal mode: the exact Admin GraphQL document you intend to send. Classified, never executed.' },
+          variables: { type: 'object', description: 'Refusal mode: optional GraphQL variables object (max 20,000 serialized characters). Supplied input-object fields are classified, not executed.' },
+          operationName: { type: 'string', minLength: 1, maxLength: 200, description: 'Refusal mode: which operation to classify when the document defines more than one. Without it, a multi-operation document is refused rather than guessed.' },
           apiVersion: { type: 'string', pattern: '^\\d{4}-\\d{2}$', description: `Admin API version YYYY-MM. Supported: ${ADMIN_API_SUPPORTED_VERSIONS.join(', ')}. Defaults to ${ADMIN_API_DEFAULT_VERSION}.` },
         },
-        required: ['lookup', 'name'],
+        required: [],
+        oneOf: [
+          { type: 'object', required: ['lookup', 'name'], not: { anyOf: [{ required: ['query'] }, { required: ['variables'] }, { required: ['operationName'] }] } },
+          { type: 'object', required: ['query'], not: { anyOf: [{ required: ['lookup'] }, { required: ['name'] }] } },
+        ],
+      },
+    },
+    {
+      name: 'admin_recipes_list',
+      description: 'List every canonical Admin API recipe Meguro models, with its stable id, document operation name, purpose, confirmation requirement, authored aliases/keywords, declared API version and templates, support boundary and fidelity, what an empty result means, any prerequisite that must hold first, and its bindingPlan. A published mutation recipe also carries evidencePlan with the eligibility and readback document labels, mutationDocumentOperationName, mutationRootField, and — when a stale-cursor refusal is predeclarable — expectedRefusalOperationName as the exact root-field matcher key. Names only, so discovery stays document-free. Registry-only discovery: it returns no tenant, store, catalog, credential, or probe data and never executes an Admin request. Use a returned id with admin_schema({ lookup: "recipe", name: "<id>" }) for the exact executable documents.',
+      inputSchema: {
+        type: 'object',
+        additionalProperties: false,
+        properties: {},
+        required: [],
+      },
+    },
+    {
+      name: 'plan_validate',
+      description: `Check whether an intended set of Shopify Admin GraphQL operations fits Meguro before creating a practice store or starting a run. Takes up to 25 documents in order and returns one result per input item, in input order, each carrying exactly one state: "served" — the selected operation and every supplied coordinate are represented by the current served practice Admin schema, with the exact coordinates it reaches; "unsupported-with-recovery" — an authority hands back a concrete recovery path, either the compatibility registry's remedy naming the supported coordinate (with the canonical recipe document when one is authored) or the exact admin_schema call that answers a required-argument refusal; "out-of-plane" — the operation is outside the served contract, or no exact recovery authority exists for it. Supplied variables and input-object fields are classified through the same input-field compatibility seam the served Admin surface uses. A document that will not parse, or whose operation cannot be selected without guessing, returns an item-local refusal instead of a guessed operation. Every reason, coordinate, alternative, and recovery comes from the served schema, the versioned compatibility registry, or the recovery authority — never an invented alternative, and never a claim about whether a particular practice store or template can execute it. Pre-credit and store-free: it needs no practice store, attempt, or run, creates and reads none, consumes no credit or metered usage, and never executes a submitted document. Supported Admin API versions ${ADMIN_API_SUPPORTED_VERSION_LABEL}; per-item apiVersion defaults to ${ADMIN_API_DEFAULT_VERSION}.`,
+      inputSchema: {
+        type: 'object',
+        additionalProperties: false,
+        properties: {
+          operations: {
+            type: 'array',
+            minItems: 1,
+            maxItems: 25,
+            description: 'The intended Admin GraphQL documents, in the order you plan to run them.',
+            items: {
+              type: 'object',
+              additionalProperties: false,
+              properties: {
+                query: { type: 'string', minLength: 1, maxLength: 30000, description: 'The exact Admin GraphQL document you intend to send.' },
+                variables: { type: 'object', description: 'Optional GraphQL variables object (max 20,000 serialized characters). Supplied input-object fields are classified, not executed.' },
+                operationName: { type: 'string', minLength: 1, maxLength: 200, description: 'Which operation to check when the document defines more than one. Without it, a multi-operation document is refused rather than guessed.' },
+                apiVersion: {
+                  type: 'string',
+                  enum: [...ADMIN_API_SUPPORTED_VERSIONS],
+                  default: ADMIN_API_DEFAULT_VERSION,
+                  description: `Admin API version to classify this item against. Supported: ${ADMIN_API_SUPPORTED_VERSIONS.join(', ')}.`,
+                },
+              },
+              required: ['query'],
+            },
+          },
+        },
+        required: ['operations'],
       },
     },
   ];
@@ -2277,13 +2878,16 @@ export function createTools(config) {
     if (!args || typeof args !== 'object' || Array.isArray(args)) {
       throw new Error(`${name} arguments must be an object`);
     }
+    if (name === 'workspace_archive' || name === 'workspace_unarchive') {
+      requiredWorkspaceId(args);
+    }
     if (SCHEMA_VALIDATED_TOOL_NAMES.has(name)) {
-      // Preserve the established identifier teaching messages while the published schema carries
-      // the same shape for schema-first clients. This also handles the equal-value legacy alias
-      // pair, whose equality cannot be expressed in portable JSON Schema.
       if (name === 'get_connection_details' || name === 'practice_run_start') requiredPracticeStoreId(args);
       const error = schemaValidationError(definition.inputSchema, args);
-      if (error) throw new Error(`${name} arguments do not match the declared input schema: ${error}`);
+      if (error) {
+        const correction = conditionalToolCorrection(name, args);
+        throw new Error(`${name} arguments do not match the declared input schema: ${error}${correction ? `. Corrected call: ${correction}` : ''}`);
+      }
       return;
     }
     if (definition.inputSchema.additionalProperties !== false) return;
@@ -2302,15 +2906,34 @@ export function createTools(config) {
           if (!DOCUMENTATION_TOPICS.has(topic)) {
             throw new Error(DOCUMENTATION_TOOL_CONTRACT.topicError);
           }
-          if (!Number.isSafeInteger(args.version) || args.version < 1) {
-            throw new Error('version must be the exact published positive integer');
+          // Refuse a malformed version before any document read: only a positive integer or the
+          // exact "latest" sentinel reaches the resolver.
+          const requested = args.version;
+          const wellFormed = requested === 'latest'
+            || (Number.isSafeInteger(requested) && requested >= 1);
+          if (!wellFormed) {
+            throw new Error(DOCUMENTATION_TOOL_CONTRACT.versionError);
           }
-          return textResult(documentationByTopic(topic, args.version));
+          return textResult(resolveDocumentationRead(topic, requested, DOCUMENTATION_TOOL_CONTRACT));
         }
         case 'templates_list': {
           const workspaceId = optionalWorkspaceId(args);
           const response = await fleetRequest(name, 'GET', '/practice/profiles', undefined, { workspaceId });
-          return 'error' in response ? response.error : textResult(storeTemplatesProjection(response.value));
+          return 'error' in response
+            ? response.error
+            : textResult(JSON.stringify(storeTemplatesProjection(response.value)));
+        }
+        case 'template_get': {
+          const workspaceId = optionalWorkspaceId(args);
+          const templateKey = requiredString(args, 'templateKey');
+          const response = await fleetRequest(
+            name,
+            'GET',
+            `/practice/profiles/${encodeURIComponent(templateKey)}`,
+            undefined,
+            { workspaceId },
+          );
+          return 'error' in response ? response.error : textResult(storeTemplateDetailProjection(response.value));
         }
         case 'stores_list': {
           const workspaceId = optionalWorkspaceId(args);
@@ -2363,59 +2986,6 @@ export function createTools(config) {
           const response = await fleetRequest(name, 'POST', `/workspaces/${encodeURIComponent(workspaceId)}/${action}`, {});
           return 'error' in response ? response.error : textResult(secretSafe(response.value));
         }
-        case 'share_create': {
-          const workspaceId = optionalWorkspaceId(args);
-          if (args.shareId !== undefined) {
-            const shareId = requiredShareId(args);
-            if (args.artifactType !== undefined || args.artifactRef !== undefined) {
-              throw new Error('artifactType and artifactRef are immutable; omit shareId to create a new share');
-            }
-            const body = {};
-            if (args.title !== undefined) {
-              body.title = requiredString(args, 'title');
-              if (body.title.length > 120) throw new Error('title must be 120 characters or fewer');
-            }
-            const audienceUserIds = optionalStringList(args, 'audienceUserIds', { maximum: 40 });
-            if (audienceUserIds !== undefined) body.audienceUserIds = audienceUserIds;
-            if (Object.keys(body).length === 0) throw new Error('share update requires title and/or audienceUserIds');
-            const response = await fleetRequest(name, 'PATCH', `/shares/${encodeURIComponent(shareId)}`, body, { workspaceId });
-            return 'error' in response ? response.error : textResult(secretSafe(response.value));
-          }
-          const title = requiredString(args, 'title');
-          if (title.length > 120) throw new Error('title must be 120 characters or fewer');
-          const { artifactType, artifactRef } = requiredShareArtifact(args);
-          const audienceUserIds = optionalStringList(args, 'audienceUserIds', { maximum: 40 });
-          if (!audienceUserIds) throw new Error('audienceUserIds is required when creating a share');
-          const response = await fleetRequest(name, 'POST', '/shares', {
-            title, artifactType, artifactRef, audienceUserIds,
-          }, { workspaceId });
-          return 'error' in response ? response.error : textResult(secretSafe(response.value));
-        }
-        case 'shares_list': {
-          const workspaceId = optionalWorkspaceId(args);
-          const response = await fleetRequest(name, 'GET', '/shares', undefined, { workspaceId });
-          return 'error' in response ? response.error : textResult(secretSafe(response.value));
-        }
-        case 'share_status': {
-          const workspaceId = optionalWorkspaceId(args);
-          const shareId = requiredShareId(args);
-          const response = await fleetRequest(name, 'GET', `/shares/${encodeURIComponent(shareId)}`, undefined, { workspaceId });
-          return 'error' in response ? response.error : textResult(secretSafe(response.value));
-        }
-        case 'share_publish': {
-          const workspaceId = optionalWorkspaceId(args);
-          const shareId = requiredShareId(args);
-          const action = args.action === undefined ? 'publish' : requiredString(args, 'action');
-          if (!['publish', 're-share'].includes(action)) throw new Error('action must be publish or re-share');
-          const response = await fleetRequest(name, 'POST', `/shares/${encodeURIComponent(shareId)}/${action}`, {}, { workspaceId });
-          return 'error' in response ? response.error : textResult(secretSafe(response.value));
-        }
-        case 'share_revoke': {
-          const workspaceId = optionalWorkspaceId(args);
-          const shareId = requiredShareId(args);
-          const response = await fleetRequest(name, 'POST', `/shares/${encodeURIComponent(shareId)}/revoke`, {}, { workspaceId });
-          return 'error' in response ? response.error : textResult(secretSafe(response.value));
-        }
         case 'catalog_slice_read': {
           const workspaceId = optionalWorkspaceId(args);
           const shopDomain = requiredShopifyDevDomain(args);
@@ -2429,33 +2999,33 @@ export function createTools(config) {
         }
         case 'catalog_slice_snapshot': {
           const workspaceId = optionalWorkspaceId(args);
-          const hasSavedSlice = args.sliceId !== undefined;
-          const hasLiveSlice = args.shopDomain !== undefined || args.variantIds !== undefined;
-          if (hasSavedSlice === hasLiveSlice) {
-            throw new Error('provide exactly one snapshot source: sliceId, or shopDomain plus variantIds');
-          }
+          const branch = conditionalToolBranch(name, args);
+          if (!branch) throw new Error('catalog_slice_snapshot branch selection did not match its declared input schema');
           let response;
-          if (hasSavedSlice) {
+          if (branch.id === 'saved') {
             const sliceId = requiredSavedSliceId(args);
-            response = await fleetRequest(name, 'POST', `/catalog-slices/${encodeURIComponent(sliceId)}/snapshot`, {}, { workspaceId });
+            response = await fleetRequest(name, 'POST', `/catalog-slices/${encodeURIComponent(sliceId)}/snapshot`, {}, {
+              workspaceId, invocationMutates: branch.mutates,
+            });
           } else {
             const shopDomain = requiredShopifyDevDomain(args);
             const variantIds = requiredCatalogVariantIds(args);
             response = await fleetRequest(name, 'POST', `/stores/${encodeURIComponent(shopDomain)}/catalog-slice/snapshot`, {
               variantIds,
-            }, { workspaceId });
+            }, { workspaceId, invocationMutates: branch.mutates });
           }
           return 'error' in response ? response.error : textResult(catalogSnapshotProjection(response.value));
         }
         case 'catalog_slices_saved': {
           const workspaceId = optionalWorkspaceId(args);
-          const action = requiredString(args, 'action');
-          if (!['list', 'get', 'save', 'delete', 'refresh', 'changes'].includes(action)) {
-            throw new Error('action must be list, get, save, delete, refresh, or changes');
-          }
+          const branch = conditionalToolBranch(name, args);
+          if (!branch) throw new Error('catalog_slices_saved branch selection did not match its declared input schema');
+          const action = branch.action;
           let response;
           if (action === 'list') {
-            response = await fleetRequest(name, 'GET', '/catalog-slices', undefined, { workspaceId });
+            response = await fleetRequest(name, 'GET', '/catalog-slices', undefined, {
+              workspaceId, invocationMutates: branch.mutates,
+            });
           } else if (action === 'save') {
             const shopDomain = requiredShopifyDevDomain(args);
             const label = requiredString(args, 'label');
@@ -2463,14 +3033,20 @@ export function createTools(config) {
             response = await fleetRequest(name, 'POST', `/stores/${encodeURIComponent(shopDomain)}/catalog-slices`, {
               label,
               variantIds: requiredCatalogVariantIds(args),
-            }, { workspaceId });
+            }, { workspaceId, invocationMutates: branch.mutates });
           } else {
             const sliceId = requiredSavedSliceId(args);
             const suffix = action === 'refresh'
               ? '/refresh'
               : action === 'changes' ? '/changes/latest' : '';
             const method = action === 'delete' ? 'DELETE' : action === 'refresh' ? 'POST' : 'GET';
-            response = await fleetRequest(name, method, `/catalog-slices/${encodeURIComponent(sliceId)}${suffix}`, action === 'refresh' ? {} : undefined, { workspaceId });
+            response = await fleetRequest(
+              name,
+              method,
+              `/catalog-slices/${encodeURIComponent(sliceId)}${suffix}`,
+              action === 'refresh' ? {} : undefined,
+              { workspaceId, invocationMutates: branch.mutates },
+            );
           }
           return 'error' in response ? response.error : textResult(secretSafe(response.value));
         }
@@ -2533,8 +3109,9 @@ export function createTools(config) {
         case 'run_status': {
           const runId = requiredString(args, 'runId');
           if (PRACTICE_ATTEMPT_ID.test(runId)) return practiceAttemptHistoryReadGuidance(name, runId);
-          const status = await api('GET', `/runs/${encodeURIComponent(runId)}`, undefined, { auth: true });
-          return textResult({ ...status, dashboard: dashboardLink(runId) });
+          const status = await apiRaw('GET', `/runs/${encodeURIComponent(runId)}`, undefined, { cacheBustRead: true });
+          if (!status.ok) return historyReadErrorResult(status);
+          return textResult({ ...status.json, dashboard: dashboardLink(runId) });
         }
         case 'run_ledger': {
           const runId = requiredString(args, 'runId');
@@ -2545,7 +3122,8 @@ export function createTools(config) {
         case 'run_report': {
           const runId = requiredString(args, 'runId');
           if (PRACTICE_ATTEMPT_ID.test(runId)) return practiceAttemptHistoryReadGuidance(name, runId);
-          return textResult(await api('GET', `/runs/${encodeURIComponent(runId)}/report`, undefined, { auth: true }));
+          const report = await apiRaw('GET', `/runs/${encodeURIComponent(runId)}/report`);
+          return report.ok ? textResult(report.json) : historyReadErrorResult(report);
         }
         case 'run_resume': {
           const runId = requiredString(args, 'runId');
@@ -2593,9 +3171,9 @@ export function createTools(config) {
             const teaching = isGateReceiptUnavailable(response.status, response.json)
               ? gateReceiptUnavailableTeaching(name, receiptId)
               : undefined;
-            return practiceErrorResult(response.status, response.json, response.retryAfterSeconds, teaching);
+            return practiceErrorResult(response.status, response.json, response.retryAfterSeconds, teaching, teaching ? 'pre-commit' : undefined);
           }
-          return textResult(secretSafe(response.json));
+          return configuredReceiptGateResult(secretSafe(response.json), enabled ? 'configuration saved' : 'disabled');
         }
         case 'gate_evaluate': {
           const receiptId = args.receiptId === undefined
@@ -2612,9 +3190,9 @@ export function createTools(config) {
             const teaching = receiptId && isGateReceiptUnavailable(response.status, response.json)
               ? gateReceiptUnavailableTeaching(name, receiptId)
               : undefined;
-            return practiceErrorResult(response.status, response.json, response.retryAfterSeconds, teaching);
+            return practiceErrorResult(response.status, response.json, response.retryAfterSeconds, teaching, teaching ? 'pre-commit' : undefined);
           }
-          return textResult(secretSafe(response.json));
+          return configuredReceiptGateResult(secretSafe(response.json), 'evaluation recorded');
         }
         case 'gate_verdict': {
           const runId = args.runId === undefined ? '' : requiredString(args, 'runId');
@@ -2626,7 +3204,7 @@ export function createTools(config) {
             if (!latest.ok) return practiceErrorResult(latest.status, latest.json, latest.retryAfterSeconds);
             const evaluation = latest.json?.evaluations?.[0];
             if (!evaluation) {
-              throw new Error('No Receipt Gate evaluation is available yet. Finish a practice simulation run and keep its pa-* receiptId; call gate_configure({ receiptId, enabled: true }); call gate_evaluate({}); then call gate_verdict({}) again.');
+              throw new Error("No configured Receipt Gate exists. The receipt's recorded API behavior remains available. Finish a practice simulation run and keep its pa-* receiptId; call gate_configure({ receiptId, enabled: true }); call gate_evaluate({}); then call gate_verdict({}) again.");
             }
             const verdict = evaluation.gateVerdict;
             if (!verdict || verdict.schemaVersion !== 'meguro.gate-verdict.v1') {
@@ -2634,9 +3212,9 @@ export function createTools(config) {
               const recovery = receiptId
                 ? `gate_evaluate({ receiptId: ${JSON.stringify(receiptId)} })`
                 : 'gate_evaluate({})';
-              throw new Error(`The latest Receipt Gate row predates reproducible gate policy v1 evidence. Re-evaluate it with ${recovery}, then call gate_verdict({}) again; Meguro will not invent missing cited facts from historical compact status.`);
+              throw new Error(`The latest Configured Receipt Gate row predates reproducible gate policy v1 evidence. Re-evaluate it with ${recovery}, then call gate_verdict({}) again; Meguro will not invent missing cited facts from historical compact status.`);
             }
-            return textResult(secretSafe(verdict));
+            return configuredReceiptGateResult(secretSafe(verdict), 'verdict read');
           }
           const response = await practiceApi('GET', `/practice/evaluation-suites/${encodeURIComponent(runId)}`);
           if (!response.ok && response.status === 404) return legacyGateArtifactNotFoundGuidance(runId);
@@ -2647,32 +3225,51 @@ export function createTools(config) {
           }
           // Exact pass-through is the parity contract: Console and MCP consume these same bytes as
           // an object, with no local policy derivation in this registry.
-          return textResult(verdict);
+          return configuredReceiptGateResult(verdict, 'legacy verdict read');
         }
         case 'runs_list': {
           const lifecycle = args.lifecycle === undefined ? undefined : requiredString(args, 'lifecycle');
           if (lifecycle && !['running', 'paused', 'completed', 'failed', 'cleaning'].includes(lifecycle)) {
             throw new Error('lifecycle must be running, paused, completed, failed, or cleaning');
           }
+          const query = new URLSearchParams({
+            limit: '200',
+            ...(lifecycle ? { lifecycle } : {}),
+          });
           return textResult(runsListProjection(
-            await api('GET', '/runs?limit=200', undefined, { auth: true }),
+            await api('GET', `/runs?${query}`, undefined, { auth: true }),
             lifecycle,
           ));
         }
-        case 'usage_read':
-          return textResult(usageProjection(await api('GET', '/account/usage', undefined, { auth: true })));
+        case 'usage_read': {
+          const workspaceId = optionalWorkspaceId(args);
+          const usage = await api('GET', '/account/usage', undefined, { auth: true });
+          if (args.continueFromAttemptId !== undefined && args.storeId === undefined) {
+            throw new Error('usage_read continueFromAttemptId requires storeId');
+          }
+          let eligibility = usage?.runStartEligibility;
+          if (args.storeId !== undefined) {
+            const storeId = validatedStoreId(requiredString(args, 'storeId'), 'storeId');
+            const continueFromAttemptId = args.continueFromAttemptId === undefined
+              ? undefined
+              : requiredPracticeAttemptId(args, 'continueFromAttemptId');
+            const query = continueFromAttemptId
+              ? `?continueFromAttemptId=${encodeURIComponent(continueFromAttemptId)}`
+              : '';
+            const response = await practiceApi('GET', `/practice/stores/${encodeURIComponent(storeId)}/playbacks/start-eligibility${query}`, undefined, { workspaceId });
+            if (!response.ok) return practiceErrorResult(response.status, response.json, response.retryAfterSeconds);
+            eligibility = response.json;
+          }
+          return textResult(usageProjection(usage, eligibility));
+        }
         case 'twin_diff': {
           const baselineRunId = requiredString(args, 'baselineRunId');
           const treatedRunId = requiredString(args, 'treatedRunId');
           if (PRACTICE_ATTEMPT_ID.test(baselineRunId) || PRACTICE_ATTEMPT_ID.test(treatedRunId)) {
             return practiceAttemptComparisonGuidanceFor(name, baselineRunId, treatedRunId);
           }
-          return textResult(twinDiffProjection(await api(
-            'GET',
-            `/runs/${encodeURIComponent(baselineRunId)}/twin-diff/${encodeURIComponent(treatedRunId)}`,
-            undefined,
-            { auth: true },
-          )));
+          const response = await apiRaw('GET', `/runs/${encodeURIComponent(baselineRunId)}/twin-diff/${encodeURIComponent(treatedRunId)}`);
+          return response.ok ? textResult(twinDiffProjection(response.json)) : historyReadErrorResult(response);
         }
         case 'exam_preflight': {
           const attemptId = requiredPracticeAttemptId(args);
@@ -2710,6 +3307,12 @@ export function createTools(config) {
                 expectedRevision: revision,
                 commandId: `mcp-exam-execute-${examId}-${revision}`,
               }, attemptId);
+            } else if ((exam.status === 'completed' || exam.status === 'cleaning') && !executorAdvanced) {
+              executorAdvanced = true;
+              advanced = await examRequest(name, 'POST', `/practice-exams/${encodeURIComponent(examId)}/cleanup`, {
+                expectedRevision: revision,
+                commandId: `mcp-exam-cleanup-${examId}-${revision}`,
+              }, attemptId);
             } else {
               break;
             }
@@ -2730,18 +3333,14 @@ export function createTools(config) {
           const response = await examRequest(name, 'GET', `/practice-exams/${encodeURIComponent(examId)}`);
           if ('error' in response) return response.error;
           const projected = examLifecycleProjection(response.value);
-          if (!['blocked', 'completed', 'failed', 'cleaned'].includes(projected.exam.status)) {
+          if (projected.exam.status === 'completed' || projected.exam.status === 'cleaning') {
+            return errorResult(`Shopify Exam ${examId} is not final; call exam_start({ attemptId: "${projected.exam.attemptId}", shopDomain: "${projected.exam.shopDomain}" }) to continue cleanup, then call exam_status before requesting its final report`);
+          }
+          if (!['blocked', 'failed', 'cleaned'].includes(projected.exam.status)) {
             return errorResult(`Shopify Exam ${examId} is ${projected.exam.status}; call exam_status and continue bounded execution before requesting its immutable receipts`);
           }
           if (projected.receipts.retention?.status === 'expired') {
-            const retention = projected.receipts.retention;
-            return errorResult(
-              retention.tier === 'developer'
-                ? 'Free keeps receipts available for 7 days. Solo keeps receipts available for 90 days; Builder keeps them available for 365 days. Upgrade, then retry this receipt if its age fits the new window, or start a new run.'
-                : retention.tier === 'solo'
-                  ? 'Solo keeps receipts available for 90 days. Builder keeps receipts available for 365 days. Upgrade, then retry this receipt if its age fits the new window, or start a new run.'
-                  : 'Builder keeps receipts available for 365 days. Start a new run to mint a fresh receipt.',
-            );
+            return errorResult(projected.receipts.retention.expiredMessage);
           }
           if (!projected.receipts.privateAvailable || !projected.receipts.publicAvailable) {
             return errorResult(`Shopify Exam ${examId} does not yet carry both immutable receipts`);
@@ -2764,6 +3363,7 @@ export function createTools(config) {
         }
         case 'practice_run_start': {
           const storeId = requiredPracticeStoreId(args);
+          const workspaceId = optionalWorkspaceId(args);
           const body = {
             purpose: 'external-agent',
             ...(args.continueFromAttemptId !== undefined ? { continueFromAttemptId: requiredPracticeAttemptId(args, 'continueFromAttemptId') } : {}),
@@ -2771,15 +3371,26 @@ export function createTools(config) {
             ...(args.externalAgent !== undefined ? { externalAgent: args.externalAgent } : {}),
             ...(args.subject !== undefined ? { subject: args.subject } : {}),
             ...(args.observationPlan !== undefined ? { observationPlan: args.observationPlan } : {}),
+            ...(args.assertionPlan !== undefined ? { assertionPlan: args.assertionPlan } : {}),
             ...(args.graphqlThrottleMode !== undefined ? { graphqlThrottleMode: args.graphqlThrottleMode } : {}),
           };
-          const response = await practiceApi('POST', `/practice/stores/${encodeURIComponent(storeId)}/playbacks`, body);
-          if (!response.ok) return practiceErrorResult(response.status, response.json, response.retryAfterSeconds);
+          const response = await practiceApi('POST', `/practice/stores/${encodeURIComponent(storeId)}/playbacks`, body, { workspaceId });
+          if (!response.ok) {
+            const unavailable = isPracticeStoreUnavailable(response.status, response.json);
+            return practiceErrorResult(
+              response.status,
+              response.json,
+              response.retryAfterSeconds,
+              unavailable ? practiceStoreUnavailableTeaching(storeId) : undefined,
+              unavailable ? 'pre-commit' : undefined,
+            );
+          }
           const started = response.json ?? {};
           return textResult(secretSafe({
             operation: 'start',
             attemptId: started.attemptId ?? started.practiceRun?.attemptId,
             ...(started.segmentPlan ? { segmentPlan: started.segmentPlan } : {}),
+            ...(started.assertionPlan ? { assertionPlan: started.assertionPlan } : {}),
             practiceRun: practiceRunProjection(started.practiceRun),
             paths: {
               state: started.statePath,
@@ -2799,16 +3410,23 @@ export function createTools(config) {
             ? undefined
             : requiredPracticeAttemptId(args, 'receiptId');
           if (receiptId) {
-            const listed = await fleetRequest(name, 'GET', '/practice/playbacks', undefined, { workspaceId });
-            if ('error' in listed) return listed.error;
-            const playbacks = Array.isArray(listed.value?.playbacks) ? listed.value.playbacks : [];
-            const referenced = playbacks.find((attempt) => attempt?.attemptId === receiptId);
-            if (!referenced) return practiceRunReceiptSelectionError(receiptId);
+            const pointPath = `/practice/playbacks/${encodeURIComponent(receiptId)}/state`;
+            const point = await apiRaw('GET', pointPath, undefined, { workspaceId });
+            if (!point.ok) {
+              const authenticationError = authenticationErrorResult(point.status, point.json);
+              if (authenticationError) return authenticationError;
+              if (point.status === 404) return practiceRunReceiptSelectionError(receiptId);
+              return fleetErrorResult(name, pointPath, point.status, point.json, point.requestId);
+            }
+            const referenced = point.json ?? {};
             const receiptStoreId = String(referenced.storeId ?? referenced.worldId ?? '');
             if (requestedStoreId && requestedStoreId !== receiptStoreId) {
               return practiceRunReceiptStoreMismatch(receiptId, receiptStoreId, requestedStoreId);
             }
-            return textResult(practiceRunsProjection(listed.value, receiptStoreId, 'receipt-derived'));
+            const listPath = queryPath('/practice/playbacks', { worldId: receiptStoreId });
+            const listed = await fleetRequest(name, 'GET', listPath, undefined, { workspaceId });
+            if ('error' in listed) return listed.error;
+            return textResult(practiceRunsProjection(listed.value, receiptStoreId, 'receipt-derived', workspaceId));
           }
 
           const fleet = await fleetRequest(name, 'GET', '/practice/stores', undefined, { workspaceId });
@@ -2832,12 +3450,19 @@ export function createTools(config) {
             listed.value,
             selectedStoreId,
             requestedStoreId ? 'explicit-store-id' : 'single-store',
+            workspaceId,
           ));
         }
         case 'practice_run_status': {
           const attemptId = requiredPracticeAttemptId(args);
-          const response = await practiceApi('GET', `/practice/playbacks/${encodeURIComponent(attemptId)}/state`);
-          if (!response.ok) return practiceErrorResult(response.status, response.json, response.retryAfterSeconds);
+          const workspaceId = optionalWorkspaceId(args);
+          const response = await practiceApi('GET', `/practice/playbacks/${encodeURIComponent(attemptId)}/state`, undefined, { workspaceId });
+          if (!response.ok) {
+            const teaching = isPracticeRunUnavailable(response.status, response.json)
+              ? practiceRunUnavailableTeaching(name, attemptId)
+              : undefined;
+            return practiceErrorResult(response.status, response.json, response.retryAfterSeconds, teaching);
+          }
           const state = response.json ?? {};
           return textResult(secretSafe({
             operation: 'status',
@@ -2848,7 +3473,8 @@ export function createTools(config) {
         }
         case 'practice_run_checkpoint': {
           const attemptId = requiredPracticeAttemptId(args);
-          const response = await practiceApi('POST', `/practice/playbacks/${encodeURIComponent(attemptId)}/checkpoint`, {});
+          const workspaceId = optionalWorkspaceId(args);
+          const response = await practiceApi('POST', `/practice/playbacks/${encodeURIComponent(attemptId)}/checkpoint`, {}, { workspaceId });
           if (!response.ok) {
             const teaching = isPracticeRunUnavailable(response.status, response.json)
               ? practiceRunUnavailableTeaching(name, attemptId)
@@ -2859,23 +3485,31 @@ export function createTools(config) {
             operation: 'checkpoint',
             attemptId,
             alreadyCaptured: response.json?.alreadyCaptured === true,
+            advanceCursor: response.json?.advanceCursor,
             checkpoint: checkpointProjection(response.json?.checkpoint),
             ...consoleUrlFields(response.json?.consoleRef, response.json?.consoleRefExpiresAt),
           }));
         }
         case 'practice_run_advance': {
           const attemptId = requiredPracticeAttemptId(args);
+          const workspaceId = optionalWorkspaceId(args);
           const hasDays = args.days !== undefined;
           const hasUntil = args.until !== undefined;
           if (hasDays === hasUntil) throw new Error('practice_run_advance requires exactly one of days or until');
-          const expectedDay = requiredNonNegativeInteger(args, 'expectedDay');
-          const expectedCallSeq = requiredNonNegativeInteger(args, 'expectedCallSeq', -1);
+          const advanceCursor = args.advanceCursor;
           if (hasDays && (!Number.isSafeInteger(args.days) || args.days < 1)) throw new Error('days must be a positive integer');
           if (hasUntil && (!args.until || typeof args.until !== 'object' || Array.isArray(args.until))) throw new Error('until must be an object');
           const response = await practiceApi('POST', `/practice/playbacks/${encodeURIComponent(attemptId)}/advance`, {
-            ...(hasDays ? { days: args.days } : { until: args.until }), expectedDay, expectedCallSeq,
-          });
-          if (!response.ok) return practiceErrorResult(response.status, response.json, response.retryAfterSeconds);
+            ...(hasDays ? { days: args.days } : { until: args.until }),
+            advanceCursor,
+            ...(args.confirmConclusion === true ? { confirmConclusion: true } : {}),
+          }, { workspaceId });
+          if (!response.ok) {
+            const teaching = isPracticeRunUnavailable(response.status, response.json)
+              ? practiceRunUnavailableTeaching(name, attemptId)
+              : undefined;
+            return practiceErrorResult(response.status, response.json, response.retryAfterSeconds, teaching);
+          }
           const advanced = response.json ?? {};
           return textResult(secretSafe({
             operation: 'advance',
@@ -2890,7 +3524,13 @@ export function createTools(config) {
         }
         case 'practice_run_finish': {
           const attemptId = requiredPracticeAttemptId(args);
-          const response = await practiceApi('POST', `/practice/playbacks/${encodeURIComponent(attemptId)}/finish`, {});
+          const workspaceId = optionalWorkspaceId(args);
+          const response = await practiceApi('POST', `/practice/playbacks/${encodeURIComponent(attemptId)}/finish`, {
+            ...(args.permanentStop === true ? { permanentStop: true } : {}),
+            ...(args.acknowledgeIncompleteOnboardingEvaluation === true
+              ? { acknowledgeIncompleteOnboardingEvaluation: true }
+              : {}),
+          }, { workspaceId });
           if (!response.ok) {
             const teaching = isPracticeRunUnavailable(response.status, response.json)
               ? practiceRunUnavailableTeaching(name, attemptId)
@@ -2906,8 +3546,14 @@ export function createTools(config) {
         }
         case 'practice_run_report': {
           const attemptId = requiredPracticeAttemptId(args);
-          const response = await practiceApi('GET', `/practice/playbacks/${encodeURIComponent(attemptId)}/report?v=2`);
-          if (!response.ok) return practiceErrorResult(response.status, response.json, response.retryAfterSeconds);
+          const workspaceId = optionalWorkspaceId(args);
+          const response = await practiceApi('GET', `/practice/playbacks/${encodeURIComponent(attemptId)}/report?v=2`, undefined, { workspaceId });
+          if (!response.ok) {
+            const teaching = isPracticeRunUnavailable(response.status, response.json)
+              ? practiceRunUnavailableTeaching(name, attemptId)
+              : undefined;
+            return practiceErrorResult(response.status, response.json, response.retryAfterSeconds, teaching);
+          }
           return textResult({
             operation: 'report',
             ...receiptProjection(response.json ?? {}),
@@ -2916,17 +3562,24 @@ export function createTools(config) {
         }
         case 'practice_run_impact': {
           const attemptId = requiredPracticeAttemptId(args);
-          const response = await practiceApi('GET', `/practice/playbacks/${encodeURIComponent(attemptId)}/impact`);
-          if (!response.ok) return practiceErrorResult(response.status, response.json, response.retryAfterSeconds);
+          const workspaceId = optionalWorkspaceId(args);
+          const response = await practiceApi('GET', `/practice/playbacks/${encodeURIComponent(attemptId)}/impact`, undefined, { workspaceId });
+          if (!response.ok) {
+            const teaching = isPracticeRunUnavailable(response.status, response.json)
+              ? practiceRunUnavailableTeaching(name, attemptId)
+              : undefined;
+            return practiceErrorResult(response.status, response.json, response.retryAfterSeconds, teaching);
+          }
           // T1 owns the shape and the API already ran the public-safe scan; pass it through verbatim
           // (no array truncation) rather than re-projecting.
           return textResult({ operation: 'impact', ...(response.json ?? {}) });
         }
         case 'get_connection_details': {
           const requestedStoreId = requiredPracticeStoreId(args);
+          const workspaceId = optionalWorkspaceId(args);
           let details;
           try {
-            details = await api('GET', `/practice/${encodeURIComponent(requestedStoreId)}/connection`, undefined, { auth: true });
+            details = await api('GET', `/practice/${encodeURIComponent(requestedStoreId)}/connection`, undefined, { auth: true, workspaceId });
           } catch (error) {
             if (error instanceof ToolResultError) throw error;
             if (error instanceof Error && error.message.startsWith('404 ')) {
@@ -2934,8 +3587,8 @@ export function createTools(config) {
             }
             throw error;
           }
-          const storeId = details.storeId ?? details.worldId ?? requestedStoreId;
-          const shopDomain = details.host ?? `${details.worldId ?? requestedStoreId}.meguro.io`;
+          const storeId = details.storeId ?? requestedStoreId;
+          const shopDomain = details.host ?? `${requestedStoreId}.meguro.io`;
           return textResult({
             identity: details.identity,
             // Canonical practice-store id first: pass it straight into practice_run_start({ storeId }).
@@ -2947,6 +3600,7 @@ export function createTools(config) {
             adminApiVersions: details.adminApiVersions,
             adminVersions: details.admin?.versions,
             adminVersionPolicy: details.adminVersionPolicy ?? details.admin?.supportPolicy,
+            adminExecutionGuide: details.adminExecutionGuide,
             env: {
               SHOPIFY_ADMIN_GRAPHQL_URL: details.adminUrl,
               SHOPIFY_ADMIN_ACCESS_TOKEN: details.token,
@@ -2956,6 +3610,7 @@ export function createTools(config) {
         }
         case 'admin_probe': {
           const worldId = requiredWorldId(args);
+          const workspaceId = optionalWorkspaceId(args);
           const body = {
             query: typeof args.query === 'string' ? args.query : '',
             ...(args.apiVersion !== undefined ? { apiVersion: args.apiVersion } : {}),
@@ -2965,7 +3620,7 @@ export function createTools(config) {
             // MEG-34: always ask the server to mint a durable Console reference for a successful probe.
             createConsoleReference: true,
           };
-          const { ok, status, json } = await apiRaw('POST', `/practice/${encodeURIComponent(worldId)}/probe/admin`, body);
+          const { ok, status, json } = await apiRaw('POST', `/practice/${encodeURIComponent(worldId)}/probe/admin`, body, { workspaceId });
           if (ok) {
             // Replace the internal reference id with a ready-to-open Console URL (opaque ref only).
             const { consoleRef, consoleRefExpiresAt, ...envelope } = json;
@@ -2978,15 +3633,27 @@ export function createTools(config) {
           return { content: [{ type: 'text', text: JSON.stringify(secretSafe(json), null, 2) }], isError: true };
         }
         case 'admin_schema': {
-          const lookup = requiredString(args, 'lookup');
-          const lookupName = requiredString(args, 'name');
-          const body = {
-            lookup,
-            name: lookupName,
-            ...(args.apiVersion !== undefined ? { apiVersion: args.apiVersion } : {}),
-          };
+          // MEG-1164: two exclusive modes on one tool. A submitted `query` asks what refusal the
+          // served Admin surface would return for that document; `lookup` + `name` is the unchanged
+          // schema lookup. Neither executes an Admin operation or touches practice-store state.
+          const body = args.query !== undefined
+            ? {
+              query: requiredString(args, 'query'),
+              ...(args.variables !== undefined ? { variables: args.variables } : {}),
+              ...(args.operationName !== undefined ? { operationName: args.operationName } : {}),
+              ...(args.apiVersion !== undefined ? { apiVersion: args.apiVersion } : {}),
+            }
+            : {
+              lookup: requiredString(args, 'lookup'),
+              name: requiredString(args, 'name'),
+              ...(args.apiVersion !== undefined ? { apiVersion: args.apiVersion } : {}),
+            };
           return textResult(await api('POST', '/practice/admin-schema', body, { auth: true }));
         }
+        case 'admin_recipes_list':
+          return textResult(await api('GET', '/practice/admin-recipes', undefined, { auth: true }));
+        case 'plan_validate':
+          return textResult(await api('POST', '/practice/plan-validate', { operations: args.operations }, { auth: true }));
         default:
           return errorResult(`Unknown tool: ${name}`);
       }
@@ -2999,24 +3666,32 @@ export function createTools(config) {
             meaning: 'The fleet tool arguments were invalid or the request could not be sent.',
             nextStep: 'Correct the arguments shown by the tool schema and retry.',
           }],
-        });
+        }, undefined, CONDITIONAL_TOOL_BRANCHES.has(name) ? toolInvocationMutates(name, args) : undefined);
       }
-      return errorResult(error instanceof Error ? error.message : String(error));
+      const failed = errorResult(error instanceof Error ? error.message : String(error));
+      return typeof error?.operationCommitBoundary === 'string'
+        ? withOperationCommitBoundary(failed, error.operationCommitBoundary)
+        : failed;
     }
   }
 
   async function call(name, args = {}) {
-    const mutates = TOOL_PRESENTATION[name]?.readOnlyHint === false;
+    const mutates = toolInvocationMutates(name, args);
     try {
       validateTopLevelArguments(name, args);
     } catch (error) {
+      if ((name === 'workspace_archive' || name === 'workspace_unarchive')
+        && error instanceof Error
+        && error.message.startsWith('workspaceId')) {
+        return workspaceLifecycleIdentityGuidance(name, args?.workspaceId, error.message);
+      }
       const result = errorResult(error instanceof Error ? error.message : String(error));
       return mutates ? withOperationCommitBoundary(result, 'pre-commit') : result;
     }
-    const result = await dispatch(name, args);
-    return mutates && result?.isError === true
-      ? withOperationCommitBoundary(result, 'unknown')
-      : result;
+    // MEG-1054: no generic derivation here. A failed mutation carries only the classification the
+    // control plane declared for it; an undeclared outcome falls through to the single `unknown`
+    // default at the resource boundary rather than being asserted twice.
+    return dispatch(name, args);
   }
 
   return { definitions, call };